Claudoro: Pomodoro Timer for Claude Code

Claudoro: Pomodoro Timer for Claude Code

Claudoro integrates time management directly into the Claude Code terminal

Claudoro is a Pomodoro timer designed specifically for the Claude Code environment, embedding a live countdown and cycle tracker directly into the terminal's status line. By placing the timer where the developer's eyes are already focused, it eliminates the need for external apps, browser tabs, or phone notifications that typically cause context switching and break deep work flow.

Installation and Setup

Claudoro requires Node.js version 22 or higher. It can be installed globally via npm or from source for development purposes.

Installation Steps:

  1. Install via npm: npm install -g claudoro
  2. Initialize: Run pomo setup to wire the tool into Claude Code. This process creates the /pomo command file and merges the necessary statusLine configuration into the settings.json file (after creating a backup).

Once setup is complete, users can start the timer in a new Claude Code session by running /pomo start.

Core Functionality and Usage

Claudoro operates as a CLI tool that provides a single source of truth for the timer state, which is then reflected in the Claude Code status line. It does not require model round-trips, meaning it does not consume API tokens.

Timer Control

Users can manage their focus sessions using the following commands:

  • /pomo start [mins]: Starts a focus block. Users can override defaults using flags: -w (work), -s (short break), -l (long break), and -f (frequency of long breaks).
  • /pomo pause | resume | stop: Controls the current timer state.
  • /pomo skip: Advances to the next phase of the Pomodoro cycle.
  • /pomo reset: Restarts the current phase.
  • /pomo extend [N]: Adds N minutes to the current phase.

Status Line Views

Claudoro offers three visual modes switchable via /pomo view <mode>:

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

Transition Modes

To accommodate different work styles, Claudoro provides three transition behaviors via /pomo mode <mode>:

  • Auto (Default): Automatically transitions between focus and break phases.
  • Balanced: Automatically starts breaks but waits for manual input to start the next focus block to avoid wasting focus time.
  • Manual: Requires manual advancement for all phase transitions, ideal for deep-flow work.

Data Management and Privacy

Claudoro follows a local-first architecture. All data is stored on the user's machine in the XDG state directory, with no network requirements, accounts, or telemetry.

  • Logging: Completed focus blocks are saved as immutable records in daily JSONL logs. All statistics are derived from these logs rather than stored as counters, ensuring that the pomo undo command can remove records without desyncing data.
  • Analytics: The pomo stats command provides terminal-based analytics, including streaks and focus heatmaps. Running pomo stats --web generates a self-contained HTML dashboard for visual analysis.
  • Privacy: The generated HTML dashboard is stored locally at ~/.local/state/claudoro/dashboard.html and is never uploaded to a server.

Technical Architecture and Guardrails

System Design

The pomo CLI acts as the central controller. The status line and /pomo command are thin interfaces that communicate with the CLI. An independent, detached process handles the alarm (sound and OS notifications) to ensure it fires even if the terminal session is closed.

Abandonment Guard

To prevent skewed statistics when a timer is accidentally left running, Claudoro implements an abandonment guard. If a block runs significantly past its planned duration (default 30 minutes overtime), the tool credits focus only up to the threshold and flags the record as abandoned in the logs.

Community Insights

While the tool is praised for its integration into the existing workflow, some users have noted the challenges of maintaining "deep work" when managing multiple AI agents simultaneously. One user noted:

"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 highlighted the value of small, integrated tools over standalone productivity apps, noting that reducing the friction of opening a separate app makes the system more likely to be used.

Sources