TRK

Minimal CLI time tracker — event-driven, zero cloud.

TRK is a command-line time tracker built for engineers who want to own their time data.

The application is wired together by an event-driven architecture using @glandjs/events. Every CLI command publishes an event; every service is a pure subscriber. No framework, no DI container — just a clean message bus.

Install

npm install -g @medishn/trk

Or with pnpm:

pnpm add -g @medishn/trk

Run without installing:

npx @medishn/trk --help

Requirements

• Node.js >= 20
• macOS, Linux, or Windows (WSL recommended)

Quick start

trk start "Working on feature X"
trk stop
trk report daily

Full command reference: docs/USAGE.md

Configuration

TRK merges two YAML files at runtime:

1. config/default.yml — shipped defaults, do not edit
2. ~/.trk/config.yaml — your personal overrides

# ~/.trk/config.yaml
work:
  daily_hours: 9
  pomodoro_minutes: 90

display:
  week_starts_on: "monday"

Changes take effect on the next command run.

Development

git clone https://github.com/m-mdy-m/trk
cd trk
pnpm install
pnpm dev start "test label"

See docs/DEVELOPMENT.md for architecture, how to add features, and the full development workflow.

Contributing

See docs/CONTRIBUTING.md. Issues and PRs are welcome.

Commits must follow the Conventional Commits format.

License

MIT — see LICENSE.

Powered by