openpomodoro-cli

Open-Pomodoro CLI

A command-line Pomodoro tracker which uses the Open Pomodoro Format

Table of Contents

• Installation
• Usage
  • Start a Pomodoro
  • Amend the current Pomodoro
  • Check the status of the current Pomodoro
  • Clear a finished Pomodoro
  • Cancel an active Pomodoro
  • Finish a Pomodoro early (or late)
  • Take a break
  • Repeat the last Pomodoro
  • Show Pomodoro history
  • Tmux Color
• Status Format
  • Available Parts
• Hooks
• Settings
• MCP Server

Installation

1. Download the latest package for your platform from the Releases page.
2. Untar the package with tar -zxvf openpomodoro-cli*.tar.gz.
3. Move the extracted openpomodoro-cli file to a directory in your $PATH (for most systems, this will be /usr/local/bin/).

Or, if you have a Go development environment:

go install github.com/BuddhiLW/openpomodoro-cli/cmd/pomodoro@latest

Or, if you've cloned this repository:

make install

Usage

Start a Pomodoro

$ pomodoro start
25:00 🍅

# Start a Pomodoro in the past
$ pomodoro start --ago 10m
15:00 🍅

# Set the Pomodoro duration in minutes
$ pomodoro start --duration 30
30:00 🍅

# Set the Pomodoro duration in seconds
$ pomodoro start --duration 22m30s
22:30 🍅

# Provide a description and tags
$ pomodoro start "Blog post" -t writing,personal
25:00 🍅
Blog post
writing,personal

# Block until the Pomodoro finishes
$ pomodoro start --wait
25:00 🍅
24:99

Amend the current Pomodoro

$ pomodoro start "Blog postt" --tags writing,personal
25:00 🍅
Blog postt
writing,personal

# Pass any options accepted by start. Only passed options will be changed.
$ pomodoro amend "Blog post"
24:30 🍅
Blog post
writing,personal

Check the status of the current Pomodoro

$ pomodoro status
12:34 🍅

# When the Pomodoro has finished
$ pomodoro status
❗🍅

# Customize the status format
$ pomodoro status -f "%mr %c/%g 🍅"
12 🍅 2/8

# Block until the Pomodoro finishes
$ pomodoro status --wait
12:34 🍅
12:33

See below for documentation on the status format string.

Clear a finished Pomodoro

$ pomodoro status
❗🍅
$ pomodoro clear
$ pomodoro status

Cancel an active Pomodoro

$ pomodoro status
12:34 🍅
$ pomodoro cancel
$ pomodoro status

Finish a Pomodoro early (or late)

$ pomodoro status
1:23 🍅
$ pomodoro finish
23:37
$ pomodoro status
❗️🍅

Take a break

$ pomodoro break
4:59

$ pomodoro break 15
14:59

Repeat the last Pomodoro

$ pomodoro repeat
25:00 🍅
Writing a blog post
writing,personal

# Block until the Pomodoro finishes
$ pomodoro repeat --wait
25:00 🍅
Writing a blog post
writing,personal
24:59

Show Pomodoro history

$ pomodoro history
2015-06-14T12:34:00-04:00 description="Blog post" duration=25 tags=writing,personal

# Output in JSON format
$ pomodoro history --output json
{
  "pomodoros": [
    {
      "start_time": "2015-06-14T12:34:56-04:00",
      "description": "Blog Post",
      "duration": 25,
      "tags": [
        "writing",
        "personal"
      ]
    }
  ]
}

# Output in iCal format
$ pomodoro history --output ical > ~/Pomodoros.ics

Tmux Color

tmux-color returns a color for the current Pomodoro status.

# Active Pomodoro
$ pomodoro tmux-color
colour2 # Green

# Finished Pomodoro
$ pomodoro tmux-color
colour1 # Red

Nothing is output if no Pomodoro is active.

Colors can be used within a Tmux configuration like so:

set -g status-left '#[bg=#(pomodoro tmux-color)]🍅'

You can also define custom colors:

# Active Pomodoro
$ pomodoro tmux-color --active colour166 --done colour165
colour166 # Orange

# Finished Pomodoro
$ pomodoro tmux-color --active colour166 --done colour165
colour165 # Purple

Status Format

All commands which display the status of a single Pomodoro can take an additional --format / -f argument. This argument controls how to display the Pomodoro.

By default, it displays the time remaining (or an Emoji exclamation point if zero), an Emoji tomato, the description, and tags. Consecutive spaces and newlines are de-duplicated.

$ pomodoro status
12:34 🍅 
Writing a blog post
writing,personal

$ pomodoro status --format "%R ⏱ %c/%g 🍅\n%d"
13 ⏱ 2/8 🍅
Writing a blog post

Available Parts

# Time
%r  - Time remaining in mm:ss
%R  - Time remaining in minutes, rounded
%!r - Same as %r, but with an exclamation point if the Pomodoro is done
%!R - Same as %R, but with an exclamation point if the Pomodoro is done
%l  - Length of the Pomodoro in mm:ss
%L  - Length of the Pomodoro in minutes

# Metadata
%d  - Pomodoro description
%t  - Pomodoro tags, joined by a comma

# Goals
%g  - Daily Pomodoro goal
%!g  - Daily Pomodoro goal, with a preceding slash
%c  - Completed Pomodoros today

Hooks

Hooks can be run when Pomodoros change state. There are 3 possible hooks:

• break
• start
• stop

Commands which run hooks:

• break: break immediately, stop when break is over
• cancel: stop
• clear: stop
• finish: stop
• repeat: start
• start: start

To enable a hook, create an executable file in the hooks subdirectory within your configuration directory. For example:

#!/usr/bin/env bash
set -exo pipefail

say "Pomodoro started"

$ chmod +x ~/.pomodoro/hooks/start

Settings

The Pomodoro CLI can be configured using a settings file in your configuration directory (~/.pomodoro/settings). The settings file uses the logfmt format.

Available Settings

• daily_goal - The number of Pomodoros you want to complete each day (integer, default: 0 = no goal)
• default_pomodoro_duration - Default duration for work sessions (duration string, default: 25m)
• default_break_duration - Default duration for breaks (duration string, default: 5m)
• default_tags - Default tags to apply to new Pomodoros (comma-separated strings, default: none)

Example Settings File

Create or edit ~/.pomodoro/settings:

daily_goal=8
default_pomodoro_duration=25m
default_break_duration=5m
default_tags=work,focus

Duration Format

Duration values can be specified in the following formats:

• Plain numbers default to minutes: 25 = 25 minutes
• Explicit minutes: 25m, 30m
• Seconds: 90s, 1500s
• Mixed: 25m30s, 1h30m

Using Settings

Settings are automatically applied when:

• Starting a new Pomodoro (pomodoro start)
• Taking a break (pomodoro break or pomodoro finish --break)
• Displaying daily progress in status format (%c/%g)

The daily goal setting is used by the status format parts %g (goal) and %c (completed today) to show progress toward your daily target.

MCP Server

An MCP (Model Context Protocol) server is available for integration with Claude Code and other MCP-compatible clients.

Installation

go install github.com/BuddhiLW/openpomodoro-cli/cmd/pomodoro-mcp@latest

Configure with Claude Code

claude mcp add pomodoro -- pomodoro-mcp

Available Tools

All tools trigger hooks (start/stop/break) just like the CLI commands.