A professional, global terminal tool to manage multiple projects, track workdays, and manage your hour balance.
time-balance is a global console application designed for productivity. It no longer depends on local files; all your projects and records are stored in a centralized SQLite database. It features a domain-driven modular architecture, a decoupled UI layer, and a robust localization system.
If you have downloaded the release files (e.g., time_balance-0.5.0-py3-none-any.whl), you can install it directly:
# Install the Wheel file
pip install time_balance-0.5.0-py3-none-any.whlTo install the application from the source code:
# Clone and enter directory
git clone <repo-url>
cd time-balance
# Install globally
pip install .If you want to contribute, we recommend using the direct entry point:
# Run without installing
./main.py --versionSimply run the command from any folder to open the manager:
time-balanceThe interface uses a standardized navigation system:
- Numbers (1-5) to select main actions.
- Letters (V, N, P) for navigation:
Vto go back,N/Pto navigate history pages.
Check your status without entering the menu:
# Show balance for the active project
time-balance --status
# List last 10 records for the active project
time-balance --list 10- ✅ Domain-Driven Architecture: Clean separation between CLI, Database, and UI logic.
- ✅ UI Abstraction: Decoupled from visual libraries for maximum flexibility.
- ✅ JSON-Based Localization: Easily add new languages via external JSON files.
- ✅ High-Performance Caching: Atomic balance updates with automatic NULL handling for imported data.
- ✅ SQLite Backend: Robust persistence following XDG standards.
- ✅ Multi-project Management: Manage different work contexts independently with project-isolated operations.
- ✅ Delete Records: Safely delete daily time records with confirmation and immediate balance recalculation.
- ✅ Balance Recalculation: Force a full rebuild of the balance cache with a single command to fix any inconsistencies.
- ✅ Data Integrity: Foreign key constraints and atomic transactions ensure referential integrity.
If you want to contribute or understand the internals:
- ARCHITECTURE.md: System design, modules, and domain structure.
- DEVELOPMENT.md: Technical guide for developers.
- CONTRIBUTING.md: How to submit improvements and translations.
This project is Open Source under the GPL-3.0 license.