Skip to main content
Glama
pomoduck
by comficker

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

id

Focus / break

Long break

Good for

Browser timer

pomodoro

25 / 5

15 after 4

Most desk work, starting a task you avoid

25 minute Pomodoro timer

short

10 / 2

10 after 4

Low energy, ADHD-friendly starts, chores

10 minute timer

deep

50 / 10

30 after 3

Writing, coding, dense study

50 minute focus timer

52-17

52 / 17

—

Knowledge work with offline breaks

50 minute focus timer

ultradian

90 / 20

—

One or two big creative blocks a day

90 minute timer

study

45 / 15

30 after 3

Exam revision, reading, problem sets

Study timer

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

Related MCP server: Task MCP Server

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

Tool

What it does

start_session

Start a focus or break timer (kind, minutes, label)

status

Running session and seconds left

stop_session

Stop early (logged as abandoned)

stats

Focus minutes and sessions over the last N days

plan

Split focus time into rounds of a technique

list_techniques

The 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to manage todo tasks through Tools for adding, listing, completing, and searching, alongside Prompts for daily reviews and task breakdowns. Exposes task lists and statistics as Resources with local JSON file persistence.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables coding agents to create, start, pause, and delete labeled timers within projects, with persistence via SQLite, through a stdio MCP interface.
      MIT