Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Time Tracker (tt)

A Rust-based time tracking application with both CLI and web interfaces. Parse markdown files to generate time reports with filtering, interactive visualizations, and multiple output formats.

Tests Coverage Status

Installation

Local Install

just install

Build from Source

# Build CLI
just build

# Build web server
just build-web

Usage

Web Dashboard

Run the interactive web dashboard:

# Start web server with your data
just web -i ./data/time-entries.md

# Auto-detect data/time-entries.md in current directory
just web

# With auto-reload during development
just web-w -i ./data/time-entries.md

# View available options
cargo run --features web -- --web --help

Server runs at http://127.0.0.1:3000

Features:

  • Interactive dashboard with project time summaries
  • Filter by period (Today, This Week, This Month, custom date ranges)
  • Limit to top 90% of projects by cumulative time
  • Drill-down to individual entries per tag
  • Dedicated outcomes analysis page
  • HTMX-powered updates without page reload
  • Robust error handling for production use

See Web Dashboard Documentation for configuration, architecture, and development guide.

Architecture Docs (C4)

Generate and preview architecture diagrams locally:

just architecture-docs-validate
just architecture-docs-export
just architecture-docs-view

One-time GitHub Pages setup:

  • Source: Deploy from a branch
  • Branch: main
  • Folder: /docs

After exporting, commit docs/site alongside DSL changes and push main. The published URL path is /site/ (for example https://<owner>.github.io/<repo>/site/).

CLI

Basic Usage

# Run with specific file and period
just run "./data.md" "this-week"

# Direct cargo run
cargo run -- -i "./data.md" --period "this-week"

Features

  • Web Dashboard - Interactive browser-based interface with filtering and drill-down
  • Parse markdown files for time entries
  • Filter by time periods (this-week, last-week, etc.)
  • Generate reports in multiple formats (text, markdown)
  • Tag-based categorization and filtering
  • Hierarchical time breakdown by calendar units (day, week, month, year)
  • CLI-based interface with comprehensive options
  • Hexagonal Architecture - Domain logic shared between CLI and web adapters

Time Breakdown Reports

View hierarchical breakdowns of tracked time by calendar units. The --breakdown flag requires either --tags or --project to filter entries.

Supported Units

  • day: No hierarchy, lists all days with entries
  • week: Hierarchical: weeks → days
  • month: Hierarchical: months → weeks (→ days if needed)
  • year: Hierarchical: years → months
  • auto: Automatically selects a unit one level above the current period
    • Day period → Week breakdown
    • Week period → Month breakdown
    • Month period → Year breakdown
    • Year period → Year breakdown

Examples

# Show daily breakdown for specific tag (current day)
just run "./data.md" "today" --tags work --breakdown day

# Show weekly breakdown (weeks with days) for this week
just run "./data.md" "this-week" --tags work --breakdown week

# Show monthly breakdown (months with weeks) for a month
just run "./data.md" "this-month" --project myproject --breakdown month

# Show yearly breakdown (years with months) for a year
just run "./data.md" "2024" --tags work --breakdown year

# Automatic breakdown (one level above the period)
just run "./data.md" "this-week" --tags work --breakdown auto

# Markdown format output
just run "./data.md" "this-month" --tags work --breakdown week --format markdown

Features

  • Chronological ordering: Entries appear in date order
  • Human-friendly labels: Includes weekday names (e.g., "2025-01-15 (Wed)"), ISO week numbers ("2025-W03")
  • Zero-entry omission: Days/weeks with no entries are excluded
  • Multiple formats: Text (indented tree) and Markdown (heading hierarchy)
  • Tag filtering: Works with --tags (OR semantics) or --project (first tag)

Output Format Examples

Text format (week breakdown):

2025-W03
  2025-01-15 (Wed)  3h 45m
  2025-01-16 (Thu)  2h 30m
  2025-01-17 (Fri)  1h 15m

Markdown format:

# Time Breakdown Report

## 2025-W03

- 2025-01-15 (Wed): 3h 45m
- 2025-01-16 (Thu): 2h 30m
- 2025-01-17 (Fri): 1h 15m

Breakdown with Task Details

Combine --breakdown with --details to show tasks aggregated by their first tag at each level of the hierarchy.

Examples

# Day breakdown with tasks per day
just run "./data.md" "this-week" --tags project-a,project-b --breakdown day --details

# Week breakdown with tasks per day
just run "./data.md" "this-month" --tags project-a --breakdown week --details

# Month breakdown with tasks per week
just run "./data.md" "2025" --tags project-a --breakdown month --details --format markdown

Output Format Examples

Text format (day breakdown with details):

2025-01-15 (Wed).. 4h 00m
  - project-a............... 3h 00m (75%)
  - project-b............... 1h 00m (25%)
2025-01-16 (Thu).. 5h 00m
  - project-c............... 3h 00m (60%)
  - project-a............... 2h 00m (40%)

Markdown format:

# Time Breakdown Report

## 2025-01-15 (Wed)

- **Time**: 4h 00m
- **project-a**: 3h 00m (75%)
- **project-b**: 1h 00m (25%)

## 2025-01-16 (Thu)

- **Time**: 5h 00m
- **project-c**: 3h 00m (60%)
- **project-a**: 2h 00m (40%)

Features

  • Task aggregation by first tag: Tasks are grouped by their primary project/context tag
  • Hierarchical display: Tasks appear at the leaf level of the breakdown hierarchy
  • Percentage calculation: Relative to the immediate parent period
  • Multiple formats: Text (indented tree) and Markdown (heading hierarchy)

Development Setup

Prerequisites

  • Rust toolchain
  • Just (command runner)

Or, all batteries included dependencies management:

  • Nix (for isolated dependency management, optional)
  • direnv (optional but recommended for automatic environment loading)

Claude Code Integration

This project includes project-scoped Serena MCP integration for enhanced Claude Code capabilities.

Usage

# Just enter the directory. direnv handles the rest.
# Then, simply run the claude command.
claude

Serena's tools will be automatically available within your Claude session.

Architecture

  • Zero-Configuration: direnv automatically configures your shell. Just run claude.
  • No Global Installs: All Python dependencies managed via Nix flake
  • Project Scoped: Serena MCP only active when using this repo's configuration
  • Zero Pollution: No changes to global Claude Code configuration
  • Reproducible: Same environment across machines via Nix

Files

  • scripts/serena-mcp - Serena MCP server launcher (uses nix develop -c uvx)
  • .envrc - Automatically configures the claude command with project-specific settings.
  • flake.nix - Updated with Python 3.12 and uv dependencies

Maintenance

  • Serena updates automatically via uvx --from git+https://github.com/oraios/serena
  • To pin a specific version, modify the git reference in scripts/serena-mcp
  • If Serena changes its invocation pattern, update scripts/serena-mcp

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages