Cross-platform Pomodoro timer CLI. Zero dependencies, Node.js >= 18.
pomo start returns immediately. The session runs in a detached worker.
When time is up you get a beep and a desktop notification. Sessions are
logged to ~/.pomo/sessions.jsonl.
npm install -g pomotracker
Or without installing:
npx pomotracker start 25
pomo start [duration] [--label "..."] [--force]
pomo break [duration] [--label "..."] [--force]
pomo stop
pomo status [--json]
pomo stats [day|week|month|all] [--json]
pomo log [--limit N] [--today] [--type focus|break] [--json]
pomo config get|set|list|reset [key] [value]
pomo completions <bash|zsh|fish>
pomo --version
pomo --help
A bare number is minutes. With a suffix: 90s, 25m, 1h, 1h30m.
Maximum: 24h. To pass a value that starts with a dash, put -- first:
pomo start -- -5m
pomo start # focus, default 25m
pomo start 1h30m --label "deep work"
pomo break 10
pomo status # 00:24 left (of 01:30) — deep work
pomo stats week
pomo log -n 5
pomo config set focusMinutes 50
pomo completions bash > ~/.pomo-completion.bash
~/.pomo/config.json. Defaults:
| Key | Default | Notes |
|---|---|---|
| focusMinutes | 25 | default focus length |
| breakMinutes | 5 | default break length |
| longBreakMinutes | 15 | reserved (long breaks: not implemented) |
| longBreakEvery | 4 | reserved |
| autoBreak | false | reserved (auto-start break: not impl.) |
| notify | true | desktop notification on completion |
| beep | true | console beep on completion |
| label | "" | default label applied to new sessions |
pomo config set <key> <value> validates the value (positive number for
duration keys, true/false for booleans) and writes it back.
| File | Purpose |
|---|---|
~/.pomo/config.json |
config |
~/.pomo/active.json |
current session (deleted on finish) |
~/.pomo/sessions.jsonl |
one JSON record per session |
| OS | Beep | Notification |
|---|---|---|
| Windows | PowerShell [Console]::Beep |
BurntToast if installed, else balloon-tip fallback |
| macOS | terminal bell | osascript display notification |
| Linux | terminal bell | notify-send (libnotify) |
On Windows, to get rich toasts: Install-Module -Scope CurrentUser BurntToast
in an elevated PowerShell (one-time).
pomo start writes active.json, spawns bin/pomo-worker.mjs detached, and
exits. The worker sleeps until the deadline, writes the session record, deletes
active.json, and fires the beep + notification.
Any subsequent pomo command reconciles active.json. If the worker is gone
and the deadline has passed, the session is logged as completed. If the worker
is gone but the deadline is still in the future, the session is logged as
stopped. This handles system reboots, kills, and pomo stop.
pomo stop deletes active.json and kills the worker.
git clone https://github.com/wowori/pomo
cd pomo
npm test
MIT