Work Hours Tracker TUI

A Rust TUI (Terminal User Interface) application for tracking working hours across projects. It offers a simple flow: pick a job, start/pause the timer, and sessions are automatically persisted to JSON.

Key features

• Real-time timing: start/pause with automatic session saving
• Job management: create (in progress), select, delete, quick navigation
• JSON persistence: data is saved in data/jobs.json
• Reactive UI: clear layout, terminal resizing, real-time updates
• On-disk logs: UI-separated log files with automatic cleanup
• Modular architecture: separate layers for app, UI, and database

Requirements

• Rust 1.75+ (2024 edition)
• Git (optional, for cloning)
• Terminal with Unicode support (Terminal.app, iTerm2, Windows Terminal)

Quick install and run

# Clone (replace with your repository URL)
git clone <repository-url>
cd work-hours-tracker-tui

# Build
cargo build

# Run
cargo run

# Run with verbose logging (recommended during development)
RUST_LOG=debug cargo run

Keyboard controls (Normal mode)

• j/k: select next/previous job
• Enter: select current job
• Esc: deselect job
• s: start/resume timer
• p: pause and save session
• d: delete selected job
• n: new job (in development)
• e: edit name (in development)
• f: filter jobs (in development)
• ?: help (in development)
• q: quit application

Data and logs

• Database: data/jobs.json (auto-created at runtime)

• Manual backup:

  cp data/jobs.json backup-$(date +%Y-%m-%d).json

• Logs: logs/work-hours-tracker_YYYY-MM-DD_HH-MM-SS.log

  • level controlled via RUST_LOG (debug, info, etc.)
  • last 5 files are kept (automatic cleanup at startup)

Project structure

src/
├── main.rs              # Application entry (lifecycle, init/cleanup)
├── lib.rs               # Module declarations
├── logging.rs           # File-based logging system
├── app/                 # Business logic (state, events)
├── ui/                  # Presentation (layout, blocks, rendering)
└── database/            # Persistence (models, JSON operations)

Main dependencies

• ratatui 0.29.0 — modern TUI framework
• crossterm 0.29.0 — portable terminal control
• color-eyre 0.6.5 — rich error reporting
• chrono 0.4 — time/date (with serde)
• serde 1.0, serde_json 1.0 — serialization and JSON storage
• log 0.4, env_logger 0.11 — logging infrastructure

Roadmap (selected)

• Job creation dialog (modal) and input validation
• Edit job name, job status (Completed)
• Real-time job search/filter
• Integrated help system
• Time export (CSV/JSON) and reports
• Configuration options and themes

Guides and documentation

• User manual: docs/USER_MANUAL.md
• Development guide: docs/DEVELOPMENT.md
• Project structure: docs/PROJECT_STRUCTURE.md
• API reference: docs/API_REFERENCE.md

Contributing

• Follow the style and patterns in docs/DEVELOPMENT.md
• Open discussions/issues for feature proposals
• Update the corresponding documentation when you change the API or behavior

License

This project does not yet have a published license file. If you intend to distribute it, add a LICENSE file (e.g., MIT) and update this section.