Claudoro: Pomodoro Timer for Claude Code

Claudoro is a Pomodoro timer designed specifically for the Claude Code terminal. By embedding a live countdown directly into the status line, it allows developers to track focus blocks and breaks without leaving the terminal or switching to external productivity apps.

Core Functionality and Integration

Claudoro integrates into the Claude Code environment as a status line segment that remains visible while the user and the AI agent work. This prevents the "broken focus" associated with alt-tabbing to a browser tab, phone, or menu-bar app.

Status Line Views

Users can switch between three display modes using /pomo view <mode>:

Minimal: Displays only the timer and a progress bar (🍅 22:47 ▕████████░░▏).
Classic (Default): Adds cycle dots to track progress toward the next long break (🍅 22:47 ▕████████░░▏ ●●○○).
Full: Includes the current task label (🍅 22:47 ▕████████░░▏ ●●○○ write tests).

The timer segment is hidden when idle, ensuring that the status line layout does not shift when the timer is not in use. It preserves existing status line information, such as the active model, context percentage, and git branch.

Command Interface

Claudoro is controlled via /pomo commands within Claude Code or directly through the pomo CLI using the ! prefix to avoid model round-trips (e.g., !pomo start 50 "architecture spike").

Key commands include:

/pomo start [mins]: Begins a focus block with optional flags for custom durations.
/pomo pause | resume | stop: Manages the current timer state.
/pomo skip | reset: Advances the phase or restarts the current one.
/pomo status: Provides detailed information on elapsed time and today's count.
/pomo stats: Generates analytics on streaks and focus heatmaps.

Configuration and Customization

Durations and Cadence

Claudoro does not use a configuration file for durations; instead, it uses flags during the start command to allow per-run flexibility:

Flag	Default	Control
`-w, --work`	25 min	Focus block length
`-s, --short`	5 min	Short break length
`-l, --long`	15 min	Long break length
`-f, --frequency`	4	Blocks before a long break

Transition Modes

To manage how the timer advances at phase boundaries, Claudoro offers three modes:

Auto (Default): Automatically transitions between focus and breaks.
Balanced: Automatically transitions to breaks, but waits for manual input before starting a new focus block.
Manual: Requires manual advancement for all transitions, ideal for deep-flow work.

Data Management and Privacy

Claudoro follows a local-first architecture. All state and history are stored on the local machine in the XDG state directory, with no network requirements, accounts, or telemetry.

Logging and Analytics

Every completed focus block is saved as an immutable record in a daily JSONL log. This ensures that data remains consistent even when using the undo command to remove erroneous records.

Users can view their productivity data in two ways:

Terminal Panel: pomo stats provides a text-based summary of streaks and top tags.
Web Dashboard: pomo stats --web generates a self-contained, offline HTML file that renders a visual dashboard of focus history and heatmaps.

Technical Implementation

Claudoro is built as a Node package where the pomo CLI serves as the single source of truth. The status line, /pomo commands, and alarms are thin interfaces that interact with the CLI. This architecture ensures that the core timer functionality does not consume API tokens, as it runs independently of the AI model.

Installation and Setup

Installation requires Node $\ge$ 22. The setup process involves:

npm install -g claudoro
pomo setup (which wires the tool into Claude Code by modifying settings.json and creating the /pomo command file).

Community Insights and Perspectives

While the tool is praised for its integration into the developer workflow, some users have raised concerns regarding the nature of "deep work" when using AI agents.

"if you're following Cal Newport-ian rules, watching over multiple agents doing their work is no longer a 25 minute 'deep work' Pomodoro"

Other users noted that a ticking second-by-second timer in the status line could be distracting for some, suggesting that the ability to customize the display to remove seconds would improve focus for specific users.