A simple, object-oriented Python application for tracking time spent on projects and sub-projects. All data is stored locally in a data.json file.
Project Management: Create, list, rename, delete, close, re-open, move, promote, and demote main projects and tasks.
Time Tracking: Start, stop, and view the current work session. Automatically stops the previous session when a new one begins.
Reporting & Analysis:
- Daily & Date Range Reports: Generate detailed reports for specific days or periods.
- Detailed Project Reports: Create in-depth reports for individual main projects or tasks, including:
- Total time, session count, and average session duration.
- A timeline of first and last activity.
- A breakdown of time spent per weekday (e.g., Monday: 2.5 hours, 30%).
- For main projects, a summary of time distribution across its tasks.
- For tasks, a day-by-day list of all time entries.
- Inactivity Tracking: Identify main projects and tasks that have been inactive for a configurable duration.
Local Data Storage: All project data and time entries are saved in a data.json file in the application's directory.
Automatic Updates: The application can check for new versions on GitHub upon exit and install them on the next start.
Interface:
- Experimental GUI: A graphical user interface based on Streamlit for a more visual experience.
Interactive CLI: A user-friendly command-line interface (
TimeTrackerCLI.py) for task and project management.
SOAP API: A full-featured SOAP web service (TimeTrackerSOAP_Server.py) to integrate TimeControl with other tools or dashboards.
Unit Testing: Includes comprehensive unit tests in tests/test_TimeTracker.py for feature reliability.
- Python 3.9 - 3.14: Ensure you have Python 3 installed on your system. You can download it from python.org. (Note: Python 3.14 is currently not supported on Windows due to dependency issues.)
Clone the repository:
git clone https://github.com/FrankFaulstich/TimeControl.git
cd TimeControlInstall the required Python packages:
pip install -r requirements.txtThe application will also attempt to self-install missing dependencies on first run.
The application can be configured via the config.json file.
{
"update": {
"github_repo": "FrankFaulstich/TimeControl"
},
"language": "de",
"streamlit_port": 8501,
"soap_port": 8600,
"data_file": "data.json",
"css_file": "style.css"
}update.github_repo: The GitHub repository (username/reponame) to check for new versions.language: The user interface language ("en", "de", "fr", "es", "cs").soap_port: The port on which the SOAP server listens (default: 8600).
To start the interactive command-line interface, run:
python TimeTrackerCLI.pyor
python3 TimeTrackerCLI.pyTo start the interactive command-line interface, run:
python TimeTrackerSL_GUI.pyor
python3 TimeTrackerSL_GUI.pyThe interactive CLI provides a structured menu for all operations.
Main Menu:
=== Time Control [version] ===
--- Main Menu ---
1. Start work on task
2. Show current work
3. Stop current work
4. Handle projects and tasks
5. Reporting
6. Settings
--------------------------------
0. Exit
Project Management Submenu (Option 4):
--- Project Management ---
1. Main Project Management
2. Task Management
--------------------------------
0. Back to Main Menu
Main Project Management Submenu:
--- Main Project Management ---
1. Add Main Project
2. List Main Projects
3. Rename Main Project
4. Close Main Project
5. Re-open Main Project
6. Delete Main Project
7. List Inactive Main Projects
8. Demote Main-Project to Sub-Project
9. List Completed Main Projects
--------------------------------
0. Back
Task Management Submenu:
--- Task Management ---
1. Add Task
2. List Tasks
3. Rename Task
4. Close Task
5. Re-open Task
6. Delete Task
7. Move Task
8. List Inactive Tasks
9. List All Closed Tasks
10. Delete All Closed Tasks
11. Promote Task to Main-Project
--------------------------------
0. Back
Reporting Submenu (Option 5):
--- Reporting ---
1. Daily Report (Today)
2. Daily Report (Specific Day)
3. Date Range Report
4. Detailed Task Report
5. Detailed Main-Project Report
6. Detailed Daily Report
--------------------------
0. Back to Main Menu
Settings Submenu (Option 6):
--- Settings ---
1. Change Language
2. Restore Previous Version
3. Change Data Storage Location
--------------------------
0. Back to Main Menu
This project uses Sphinx to generate documentation from the docstrings in the source code.
-
Install dependencies: Make sure you have installed the required packages for building the docs:
pip install -r requirements.txt
-
Build the HTML documentation: Navigate to the
docsdirectory and use themakecommand:cd docs make htmlThe generated documentation can be found in
docs/_build/html/index.html.
All your project data, including main projects, tasks, and time entries, is automatically saved in a local file named data.json in the same directory as the script. This file is created upon the first run if it doesn't exist.
The data.json file has the following structure:
{
"projects": [
{
"main_project_name": "Example Main Project",
"tasks": [
{
"task_name": "Example Task 1",
"status": "open",
"time_entries": [
{
"start_time": "YYYY-MM-DDTHH:MM:SS.ffffff",
"end_time": "YYYY-MM-DDTHH:MM:SS.ffffff"
},
{
"start_time": "YYYY-MM-DDTHH:MM:SS.ffffff"
// "end_time" is missing if the entry is still active
}
]
},
// ... other tasks
]
},
// ... other main projects
]
}Time entries are stored in ISO 8601 format (e.g., "2025-09-12T09:30:00.123456"). If an end_time is missing for a time_entry, it means that time tracking is currently active for that task.
Contributions are welcome! If you have any suggestions for improvements or new features, please feel free to:
- Fork the repository.
- Create a new branch (
git checkout -b feature/your-feature-name). - Make your changes.
- Commit your changes (
git commit -m 'Add some Feature'). - Push to the branch (
git push origin feature/your-feature-name). - Open a Pull Request.
Please ensure your code follows the existing style and includes relevant unit tests for new functionality.
This project is licensed under the MIT License - see the LICENSE.md file for details. (You might want to create a LICENSE.md file in your repository.)