PomoDuck

Pomodoro timer for agents: start, check and stop focus sessions, see weekly focus stats and plan rounds (25/5, 50/10, 90/20). Zero-dependency npm package; also a terminal timer.

Documentation

pomoduck

A small Pomodoro timer for the terminal, plus an MCP server so AI agents (Claude, Cursor, Cline…) can start, check and log focus sessions. Zero dependencies, Node 18+.

Same timers run in the browser at PomoDuck — free Pomodoro timer, where focus sessions also grow a little duck farm.

npx pomoduck            # 25 min focus, then a 5 min break
npx pomoduck 50         # 50 min focus, 10 min break
npx pomoduck run deep   # loop 50/10 rounds until Ctrl+C
npx pomoduck plan 120   # split 2 hours into rounds and breaks
npx pomoduck stats      # focus minutes for the last 7 days

Sessions are stored locally in ~/.pomoduck/state.json (override with POMODUCK_HOME). Nothing is sent anywhere.

Techniques

idFocus / breakLong breakGood forBrowser timer
pomodoro25 / 515 after 4Most desk work, starting a task you avoid25 minute Pomodoro timer
short10 / 210 after 4Low energy, ADHD-friendly starts, chores10 minute timer
deep50 / 1030 after 3Writing, coding, dense study50 minute focus timer
52-1752 / 17—Knowledge work with offline breaks50 minute focus timer
ultradian90 / 20—One or two big creative blocks a day90 minute timer
study45 / 1530 after 3Exam revision, reading, problem setsStudy timer

The table lives in data/techniques.json if you want to reuse it. New to the method? Read what the Pomodoro technique is.

CLI

pomoduck [minutes]                 focus timer (default 25), then a break
pomoduck run <technique>           loop focus/break rounds
pomoduck break [minutes]           break timer (default 5)
pomoduck plan <minutes> [technique]
pomoduck status
pomoduck stats [days]
pomoduck techniques
pomoduck mcp                       run as an MCP server on stdio
  -l, --label <text>               what the session is for
  --no-break                       skip the break after focus

Ctrl+C stops a session and logs it as abandoned. The terminal bell rings when a timer ends.

MCP server

{
  "mcpServers": {
    "pomoduck": { "command": "npx", "args": ["-y", "pomoduck", "mcp"] }
  }
}

Claude Code: claude mcp add pomoduck -- npx -y pomoduck mcp

ToolWhat it does
start_sessionStart a focus or break timer (kind, minutes, label)
statusRunning session and seconds left
stop_sessionStop early (logged as abandoned)
statsFocus minutes and sessions over the last N days
planSplit focus time into rounds of a technique
list_techniquesThe technique table above

Example prompts: "Start a 50 minute focus session for the API refactor", "How much did I focus this week?", "Plan 3 hours of study with 45/15 blocks."

The timer state is a file, so the CLI and the MCP server see the same session: start it from your agent, check it with pomoduck status in a terminal.

Want more than a terminal timer?

PomoDuck is the free web version: a focus timer with tasks, daily goals, streaks and a heatmap, a website blocker extension for Chrome, and an Android app. Focus earns seed, breaks earn water, and your ducks turn both into eggs.

License

Code: MIT. Technique data (data/techniques.json): CC BY 4.0 — suggested credit: Focus techniques by PomoDuck.