npm

🍅 Claudoro: Integrated Pomodoro for Claude Code

Claudoro is a sophisticated Pomodoro productivity timer designed specifically to reside within the status line of the Claude Code terminal. It provides a persistent, ticking countdown exactly where your focus already lies, complemented by a robust alarm system that triggers regardless of whether the status line is visible or the session is active.

The Philosophy: Why put a timer in the status line? Because ~~switching to a browser tab, checking a phone, or glancing at a menu-bar app~~ creates a context switch. Claudoro utilizes the unused, always-visible real estate of your terminal to protect your attention.

🚀 Getting Started

Prerequisites

To run Claudoro, you need $\text{Node} \ge 22$ (which is standard if you've already installed Claude Code via npm).

Installation Checklist

Install the package
Run the setup utility
Verify status line integration

Option A: Via npm (Recommended)

npm install -g claudoro
pomo setup

Option B: From Source (For Developers)

git clone https://github.com/emson/claudoro.git
cd claudoro
npm install
npm link # Creates a global `pomo` binary linked to this folder
pomo setup

Note: Using npm link allows you to git pull updates and see changes immediately without re-installing.

How `pomo setup` Works

The setup process automates the integration into Claude Code by:

Writing the necessary /pomo command file.
Merging the statusLine configuration into your settings.json (a backup is created first).
Generating a manifest of all changes to ensure a ~~messy~~ clean uninstallation.

🛠 Usage & Commands

You can interact with the timer using /pomo commands directly in the terminal.

Core Controls

/pomo start [mins] — Begin a session. Use flags like -w 25 -s 5 -l 15 -f 4 to customize.
/pomo pause | resume | stop — Manage the current timer state.
/pomo skip — Jump to the next phase immediately.
/pomo reset — Restart the current phase (does not affect cycle count).
/pomo next — Advance a waiting boundary (used in balanced or manual modes).
/pomo back — Undo a phase transition (available for a short window).
/pomo extend [N] — Add $N$ minutes to the current timer.

Information & Management

/pomo status — View detailed metrics (elapsed time, labels, daily count, etc.).
/pomo mode [auto|balanced|manual] — Change transition behavior.
/pomo view [minimal|classic|full] — Change the status line appearance.
/pomo mute | unmute — Toggle audio alerts.
/pomo log — Review today's completed focus blocks.
/pomo stats — View analytics (streaks, heatmaps, top tags). Use --web for the dashboard.
/pomo undo [N] — Delete the last $N$ records (backup is created first).
/pomo restore — Recover from a backup.
/pomo guide — Learn the Pomodoro Technique. Use --web for the web version.
/pomo version — Check the current version.
/pomo help [command] — Get assistance.

Labeling & Organization

/pomo note "text" — Append text to the current block (supports #tags).
/pomo tag name — Add a specific #tag.
/pomo label "text" — Overwrite the current block's label.

Pro Tip: To avoid model round-trips, use pomo status --json.

📊 Visuals & Configuration

Status Line View Modes

The timer is invisible when idle, ensuring your layout doesn't shift.

Mode	Output Example	Description
`minimal`	`🍅 22:47 ▕████████░░▏`	Just the timer and progress bar.
`classic`	`🍅 22:47 ▕████████░░▏ ●●○○`	Timer, bar, and cycle dots (Default).
`full`	`🍅 22:47 ▕████████░░▏ ●●○○ write tests`	Includes the current task label.

Cycle Logic: The dots (●●○○) track progress toward a long break. They reset to $\text{○○○○}$ at midnight or after a long break is completed.

Duration Settings

Durations are set per session via flags rather than a static config file.

Flag	Default	Purpose
`-w, --work`	25 min	Length of a focus block
`-s, --short`	5 min	Length of a short break
`-l, --long`	15 min	Length of a long break
`-f, --frequency`	4	Blocks required before a long break

Examples:

pomo start 50 $\rightarrow$ 50m focus, others default.
pomo start -s 10 -l 30 $\rightarrow$ 25m focus, 10m short, 30m long.
pomo start 50 -s 10 -l 30 -f 3 $\rightarrow$ Fully custom cadence.

🔄 Transition Logic

The way Claudoro moves between phases depends on the selected mode:

Mode	Focus $\rightarrow$ Break	Break $\rightarrow$ Focus	Ideal Use Case
Auto (Default)	Automatic	Automatic	Hands-free operation
Balanced	Automatic	Wait	Prevents interrupting deep flow
Manual	Wait	Wait	Maximum control over transitions

When waiting, the status line displays +M:SS (overtime) and the pending step.

🔒 History & Privacy

Every completed focus block is recorded for analytics, with built-in support for undoing records and restoring from backups to ensure data integrity.