HackHours

HackHours is a local-first, offline coding activity tracker inspired by WakaTime. It runs as a lightweight background watcher, records activity in ChronoDB, and provides rich CLI summaries.

Features

• Local-first, offline-only storage (ChronoDB JSON files)
• Automatic session tracking with idle detection
• Language, project, and file breakdowns
• Daily/weekly/monthly summaries with ASCII charts
• Cross-platform CLI (Windows/macOS/Linux)

Install (local dev)

npm install

Build

npm run build

Initialize

hackhours init

Start/Stop Tracking

hackhours start
hackhours stop
hackhours status

Reports

hackhours today
hackhours week
hackhours month
hackhours stats --from 2026-02-01 --to 2026-02-28
hackhours languages --from 2026-02-01 --to 2026-02-28
hackhours projects --from 2026-02-01 --to 2026-02-28

Config

Config is stored at ~/.hackhours/config.json:

{
  "directories": ["C:/work/my-project"],
  "idleMinutes": 2,
  "exclude": ["**/node_modules/**", "**/.git/**"],
  "dataDir": "C:/Users/USER/.hackhours/data"
}

Data Storage (ChronoDB)

Data is stored in ~/.hackhours/data by default. Collections used:

• sessions
• events
• aggregates

Shell Completions

source completions/hackhours.bash

For zsh, copy completions/_hackhours into your $fpath.

Tests

npm test

Notes

• hackhours start spawns a detached background process.
• Use hackhours stop to end tracking cleanly.