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.
just install# Build CLI
just build
# Build web server
just build-webRun 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 --helpServer 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.
Generate and preview architecture diagrams locally:
just architecture-docs-validate
just architecture-docs-export
just architecture-docs-viewOne-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/).
# Run with specific file and period
just run "./data.md" "this-week"
# Direct cargo run
cargo run -- -i "./data.md" --period "this-week"- 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
View hierarchical breakdowns of tracked time by calendar units. The --breakdown flag requires either --tags or --project to filter entries.
- 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
# 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- 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)
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
Combine --breakdown with --details to show tasks aggregated by their first tag at each level of the hierarchy.
# 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 markdownText 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%)
- 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)
- 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)
This project includes project-scoped Serena MCP integration for enhanced Claude Code capabilities.
# Just enter the directory. direnv handles the rest.
# Then, simply run the claude command.
claudeSerena's tools will be automatically available within your Claude session.
- Zero-Configuration:
direnvautomatically configures your shell. Just runclaude. - 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
scripts/serena-mcp- Serena MCP server launcher (usesnix develop -c uvx).envrc- Automatically configures theclaudecommand with project-specific settings.flake.nix- Updated with Python 3.12 and uv dependencies
- 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