Skip to content

Latest commit

 

History

History
335 lines (237 loc) · 7.62 KB

SESSIONS.md

File metadata and controls

335 lines (237 loc) · 7.62 KB

Timer Sessions

Sessions track time in real-time with automatic updates, pause/resume support, and shared state between TUI and CLI.

Table of Contents

What are Sessions?

A session is an active timer that tracks time spent on a task. Recorded data:

  • Task name and optional description
  • Optional project and customer metadata
  • Start time
  • Elapsed time (updated in real-time)
  • Pause/resume history
  • Final duration when stopped

Start a timer when you begin work, stop it when done. End time is automatically set to the current time.

TUI Usage

Starting a Session

In the TUI, you must select an existing work record, then press S to start a session:

  • Updates that record's end time when stopped
  • Use to extend existing entries

To create a new task with a session, use the CLI session start command.

Session Controls

Key Action
S Start/Stop session on selected record
P Pause/Resume active session

Visual Indicators

Active session displays:

  1. Timer Status Bar (top of screen):

    ⏱ Running: Task Name | 1h 23m 45s | Status: Running

    Shows task name, elapsed time (H:MM:SS), and status (Running/Paused)

  2. Record Highlighting:

    • Active session records show ⏱ icon

Session States

  • Running: Time is actively being tracked
  • Paused: Timer is paused, paused duration is tracked separately
  • Stopped: Session has ended, time is saved to the work record

CLI Usage

Control sessions from the command line without opening the TUI.

Starting a Session

The CLI can create new tasks with sessions:

# Start a basic session
work-tuimer session start "My Task"

# Start with a description
work-tuimer session start "Bug Fix" -d "Fixing authentication issue"

# Start with project/customer metadata
work-tuimer session start "Bug Fix" --project "Platform" --customer "ACME"

This creates a new work record and starts tracking immediately.

Output:

✓ Session started
  Task: My Task
  Project: Platform
  Customer: ACME
  Description: Optional description
  Started at: 14:30:45

Checking Session Status

work-tuimer session status

Output:

⏱ Session Status
  Task: My Task
  Status: Running
  Elapsed: 1h 23m 45s
  Started at: 14:30:45
  Project: Platform
  Customer: ACME
  Description: Optional description

Pausing and Resuming

# Pause the active session
work-tuimer session pause

Output:

⏸ Session paused
  Task: My Task
  Elapsed: 0m 45s

# Resume the paused session
work-tuimer session resume

Output:

▶ Session resumed
  Task: My Task
  Total elapsed (before pause): 0m 45s

Stopping a Session

work-tuimer session stop

Output:

✓ Session stopped
  Task: My Task
  Duration: 1h 23m 45s
  Started at: 14:30:45
  Ended at: 15:54:30

Error Handling

If you try to control a session when none is running:

$ work-tuimer session stop
Error: No session is running

If you try to start a session when one is already running:

$ work-tuimer session start "Another Task"
Error: A timer is already running

Session Features

Automatic Time Updates

End time is automatically set to current time when stopped.

Pause Support

Pause and resume sessions:

  • Elapsed time: Only counts active time (excludes paused duration)
  • Paused duration: Tracked separately
  • Multiple pauses: Pause/resume as needed

Persistence Across Restarts

Sessions survive application restarts. State is saved in a SQLite database under the application data directory returned by dirs::data_local_dir(), for example:

  • Linux: ~/.local/share/work-tuimer/work-tuimer.db
  • macOS: ~/Library/Application Support/work-tuimer/work-tuimer.db
  • Windows: %LOCALAPPDATA%\work-tuimer\work-tuimer.db

Cross-Date Support

Start a session on a record from any date:

  • Navigate to any day in the TUI
  • Start a session on that day's record
  • End time updates correctly when stopped

CLI and TUI Integration

Sessions share state across both interfaces:

  • Start in CLI, pause in TUI
  • Start in TUI, check status in CLI
  • Changes sync automatically

TUI auto-reloads every 500ms to reflect external changes.

Common Workflows

Workflow 1: Simple Session

# Start working
work-tuimer session start "Write documentation"

# ... work on your task ...

# Stop when done
work-tuimer session stop

Workflow 2: Session with Breaks

# Start working
work-tuimer session start "Code review"

# ... work for a while ...

# Take a break
work-tuimer session pause

# ... break time ...

# Resume work
work-tuimer session resume

# ... finish up ...

# Stop when done
work-tuimer session stop

Workflow 3: TUI + CLI Hybrid

# Start in CLI before opening TUI
work-tuimer session start "Morning standup prep"

# Open TUI to view full day
work-tuimer

# Continue working in TUI, see session status at top
# Press P to pause, S to stop, or let it run

# Later, check status from CLI
work-tuimer session status

# Stop from CLI when done
work-tuimer session stop

Workflow 4: Updating Existing Records

In the TUI:

  1. Navigate to a work record to extend
  2. Press S to start a session
  3. Work continues...
  4. Press S again to stop

Record's end time and duration update automatically.

Workflow 5: Quick Status Checks

# Quick check if anything is running
work-tuimer session status

# If nothing running, start new task
work-tuimer session start "New task"

Data Persistence

Active Session Storage

Active sessions are stored in SQLite table active_timer (single-row state):

  • Linux: ~/.local/share/work-tuimer/work-tuimer.db
  • macOS: ~/Library/Application Support/work-tuimer/work-tuimer.db
  • Windows: %LOCALAPPDATA%\work-tuimer\work-tuimer.db
  • Fallback: ./data/work-tuimer.db

Session State Fields

The active_timer row stores:

  • task_name, description
  • start_time, end_time, date
  • status, paused_duration_secs, paused_at
  • source_record_id, source_record_date

Work Record Integration

When a session stops, it creates or updates a work record in SQLite (work_records table) for the target day.

Database Location Priority

Daily work records are saved to (checked in order):

  1. <dirs::data_local_dir()>/work-tuimer/work-tuimer.db
  2. ./data/work-tuimer.db (fallback)

Tips

  1. Use descriptive task names: Easier to identify work later
  2. Add descriptions for context: Useful when reviewing time logs
  3. Pause during interruptions: Accurate tracking excludes breaks
  4. Check status regularly: work-tuimer session status shows active sessions
  5. Stop sessions promptly: Remember to stop when switching tasks
  6. Use CLI for quick starts: Start sessions without opening TUI
  7. Work in both interfaces: Auto-reload syncs changes every 500ms

Troubleshooting

Session not showing in TUI

  • The TUI auto-reloads every 500ms, wait a moment
  • If still not visible, restart the TUI

Lost session after restart

  • Sessions are saved to work-tuimer.db (table active_timer) - check if the DB file exists
  • If the DB file was deleted, the session cannot be recovered

Wrong end time on stopped session

  • End time is set to when you stopped
  • If stopped late, manually edit the end time in the TUI

CLI and TUI showing different data

  • The TUI caches data and auto-reloads every 500ms
  • Wait a moment or restart the TUI to see latest changes