Time Tracking Tool - Ubuntu (Wayland)

A modern Python-based Time Tracking TUI (Terminal User Interface) application built with Textual for Ubuntu Wayland systems.

Features

Core Functionality

• Real-time Task Tracking: Start and stop multiple tasks concurrently
• Daily Reset: All tracking resets at midnight (00:00)
• Manual Entry: Add work sessions with custom dates and durations
• Session Management: View, edit, and delete individual work sessions
• Weekly View: See your work distribution across the week at a glance
• Auto-save: Automatic data persistence every 60 seconds
• JSON Storage: Human-editable JSON format for work data

Security

• API Key Validation: Requires a valid 16-character APP_API_KEY in .env
• No Root Required: Runs without sudo privileges
• Graceful Exit: Properly saves data before shutdown

Proof-of-Work

• Automated Screenshots: Captures screen at random intervals (4-8 minutes)
• Wayland Compatible: Uses grim command-line utility for Wayland
• Smart Timing: Only takes screenshots when tasks are actively running
• Organized Storage: Screenshots saved as DD-MM-YYYY/screenshot_HH-MM-SS.png

Installation

Prerequisites

• Python 3.10+
• Ubuntu with Wayland display server
• grim utility (for Wayland screenshot capture)

Setup

1. Clone/Navigate to Project

cd /path/to/tt

2. Create Virtual Environment (if not already done)

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install textual python-dotenv
apt install grim  # For Wayland screenshot support

4. Configure API Key Create or update .env file in the project root:

APP_API_KEY=YourExactly16CharacterKeyHere

The API key must be exactly 16 characters. If missing or invalid, the app will exit with "Unauthorized Access".

Usage

Starting the Application

source venv/bin/activate
python main.py

Keyboard Shortcuts

Key	Action
T	Add a new task
S	Start/Stop task tracking
A	Manually add a work session
D	Delete a session
←	Navigate to previous week
→	Navigate to next week
Esc	Close dialogs/cancel actions
Enter	Confirm selections in dialogs

Available Actions

[T] New Task

1. Press T to open the new task dialog
2. Enter a task name (e.g., "Project Alpha", "Code Review")
3. Press Enter or click "Add" to create the task

[S] Start/Stop

• When no tasks are running: Shows a list of available tasks to start

  • Default selection: Last used task (if available)
  • Press Enter or click task name to start

• When tasks are running: Shows active tasks to stop

  • Select a task and press Enter to stop it

[A] Manual Add

Add a work session retroactively:

1. Press A to open the manual add dialog
2. Enter date (default: today, format DD-MM-YYYY)
3. Enter hours and minutes worked
4. Enter the task name
5. Click "Add" to save

Example: Add 2.5 hours to "Research" for today

• Date: 23-12-2025
• Hours: 2
• Minutes: 30
• Task: Research

[D] Delete Session

Remove a recorded session:

1. Press D to view today's sessions
2. Select the session to delete
3. Press Enter to confirm deletion

Navigation

• ←: Move to the previous week
• →: Move to the next week
• View displays all tasks and total hours per day

Main Display

The application shows three main sections:

1. Header Bar: Quick reference for available keybinds
2. Weekly Table:
   • Columns: Mon-Sun with dates
   • Rows: All your tasks
   • Cells: Total time spent on each task per day
   • Footer: Daily and weekly totals
3. Daily Breakdown:
   • All sessions recorded today
   • Shows task name, start time, end time, and duration
   • Actively running tasks highlighted in green

Data Storage

Structure

All data is stored in work_data.json in the project root:

{
  "tasks": {
    "Project A": {
      "sessions": [
        {
          "start": "2025-12-23T09:00:00",
          "end": "2025-12-23T11:30:00",
          "duration_seconds": 9000
        }
      ]
    }
  },
  "last_used_task": "Project A"
}

Key Points

• Thread-safe: Uses locks to prevent data corruption
• Auto-save: Saves every 60 seconds automatically
• Human-readable: JSON format allows manual editing
• Recovery-friendly: Can restart app and resume tracking

Screenshots

Screenshots are automatically captured while tasks are running:

Location

screenshots/
├── 23-12-2025/
│   ├── screenshot_09-15-30.png
│   ├── screenshot_09-22-45.png
│   └── screenshot_09-31-12.png
├── 24-12-2025/
│   └── screenshot_14-05-22.png

Capture Timing

• Interval: Random between 4-8 minutes
• Condition: Only when at least one task is active
• Frequency: Interval resets after each screenshot

Wayland Support

Requires grim command-line utility:

sudo apt install grim  # Debian/Ubuntu

If grim is not available, screenshots silently fail (no data loss).

Project Structure

tt/
├── main.py                 # Application entry point
├── .env                    # Environment configuration (API key)
├── work_data.json          # Work session data (auto-generated)
├── requirements.txt        # Python dependencies
├── README.md               # This file
├── src/
│   ├── config.py          # Configuration and validation
│   ├── storage.py         # JSON data persistence layer
│   ├── tracker.py         # Core time tracking logic
│   ├── screenshots.py     # Automated screenshot thread
│   └── ui.py              # Textual TUI application
├── screenshots/           # Captured screenshots (auto-generated)
└── venv/                  # Python virtual environment

Module Descriptions

• config.py: API key validation, file path management
• storage.py: Thread-safe JSON operations, data model
• tracker.py: High-level time tracking interface
• screenshots.py: Background screenshot thread with Wayland support
• ui.py: Textual widgets, screens, and event handlers
• main.py: App initialization, threading, lifecycle management

Troubleshooting

"Unauthorized Access" on startup

• Check .env file exists in project root
• Verify APP_API_KEY is exactly 16 characters
• Ensure no extra spaces or newlines

No screenshots being taken

• Verify grim is installed: which grim
• Check that at least one task is currently active
• Verify screenshots/ directory is writable

Data not persisting

• Check file permissions on work_data.json
• Verify disk space is available
• Check that the app didn't crash unexpectedly

TUI display issues

• Ensure terminal width is at least 80 characters
• Update Textual library: pip install --upgrade textual
• Try clearing terminal: clear before running

Technical Details

Concurrency Model

• Main thread: Textual event loop
• Auto-save thread: Saves data every 60 seconds
• Screenshot thread: Runs independently every 4-8 minutes
• Thread safety: All data access protected with locks

Session Duration Calculation

• Sessions with both start and end times: end - start
• Active sessions (no end time): Shown as "ACTIVE" in display
• Manual sessions: User-specified hours + minutes

Time Zones

• All times stored in local system time
• No timezone conversion applied
• Midnight (00:00) local time = day reset

Development

Running Tests

# Verify Python syntax
python -m py_compile main.py src/*.py

# Test API key validation
python -c "
import sys
sys.path.insert(0, 'src')
from config import validate_api_key
validate_api_key()
print('API key valid')
"

# Test tracker functionality
python -c "
import sys
sys.path.insert(0, 'src')
from tracker import TimeTracker
tracker = TimeTracker()
tracker.add_task('Test')
tracker.start_task('Test')
tracker.stop_task('Test')
print('Tracker working')
"

Code Style

• Python 3.10+ compatible
• Type hints for clarity
• Docstrings for all public methods
• Thread-safe operations with locks

License

[Add your license here]

Support

For issues or questions:

1. Check the Troubleshooting section above
2. Review the project files for more details
3. Examine work_data.json for data integrity

Future Enhancements

Potential improvements:

• Task categories/tags
• Time estimates and progress tracking
• Export to CSV/PDF reports
• Dark/light theme toggle
• Keyboard-driven UI refinements
• Database backend (SQLite) option
• Cloud sync capability