Claudoro: Pomodoro timer embedded in Claude Code

My notes

Summary

Claudoro is an open-source Pomodoro timer that renders directly in the Claude Code status line instead of a separate app, browser tab, or phone. It ticks live in the terminal, fires a reliable alarm even when the status line is hidden, and derives all stats from an immutable local log so undo/edit operations can never desync the numbers.

Key Insight

• Placement is the whole pitch: every existing Pomodoro tool competes for attention outside the terminal (alt-tab cost); Claudoro sits in the one surface a coding-agent user is already staring at, so starting/stopping a timer costs zero context switch.
• Immutable-log architecture avoids a classic bug class: every completed focus block is an append-only JSONL record; today’s count, cycle position, and streaks are all derived on read, never stored as counters, so undo or backup/restore can never leave stats in an inconsistent state.
• Overtime guard prevents inflated stats: if you forget to stop a session and it runs unattended for hours, Claudoro credits only planned + max_overtime (default 30 min) and flags the record abandoned, rather than logging “11h 32m of deep focus.” Full credit is available via pomo stop --full if the long run was deliberate.
• Three advance modes for phase transitions (auto/balanced/manual) solve a real design tension: auto moves hands-free through focus, break, focus; balanced auto-starts breaks but waits for you to resume focus (never wastes a block while you’re away); manual waits at every boundary for deep-flow work.
• Zero-token architecture: the CLI (pomo) is the single source of truth and runs with no model involvement, so the status line, /pomo slash command, and alarm are thin wrappers, and the timer itself never costs API tokens. A !pomo start 50 "task" bang-prefix bypasses the model entirely for zero round-trip cost.
• Single global timer across sessions: if multiple Claude Code panes are open, exactly one alarm fires regardless of how many sessions are watching, avoiding duplicate notification spam.
• Fully local and offline: state lives under the XDG state dir, no network calls, no telemetry, no accounts, and the --web stats dashboard is a single self-contained HTML file with no external dependencies.
• Clean uninstall path with data preservation by default: pomo uninstall restores the prior status line from a timestamped backup; history/stats are kept unless you explicitly pass --purge --yes.