# Claudoro: Pomodoro timer embedded in Claude Code

> Open-source Pomodoro timer that lives in the Claude Code status line, with an immutable JSONL log and zero-token CLI so the timer never costs API tokens.

Published: 2026-06-19
URL: https://daniliants.com/insights/claudoro-pomodoro-timer-embedded-in-claude-code/
Tags: claude-code, productivity, focus, open-source

---

## 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`.