tomodoro

A terminal Pomodoro timer with animated backgrounds.

Install

cargo install tomodoro

Requires Rust — install via rustup if you don't have it.

Usage

On launch, a setup screen lets you choose your focus and break durations. Use Tab to move between fields, ←/→ to select hours or minutes, and ↑/↓ to change the value — or just type a number directly. Press Enter to start, Esc to quit.

CLI flags

tomodoro --help       # list flags and subcommands
tomodoro --version    # print version
tomodoro --endless    # endless animation mode (also -E)
tomodoro history      # show session history

Endless mode

tomodoro -E runs the animated background full-screen with no timer, no session indicators, no progress bar, and no sounds — pure ambient display.

Config

On first launch, ~/.config/tomodoro/config.toml is created with all options commented out. Uncomment and edit to set persistent defaults:

theme = 2              # starting animation (0–7): waves, rain, leaves, stars, fire, aurora, blossom, sunset
focus_theme = 4        # animation for focus phase
break_theme = 0        # animation for break phases
render_mode = "half"   # half | quarter | braille
focus = 25             # minutes
short_break = 5
long_break = 15
volume = 0.8           # 0.0–1.0
long_break_interval = 4
auto_start = false     # skip startup screen
countdown_beeps = 5    # beep seconds before break ends
notifications = false  # notify-send on phase end

Features

• Custom durations — set focus, short break, and long break times on startup or mid-session with e; type values directly or use arrow keys
• Volume control — adjust bell and beep volume with [/], displayed in the header
• Session tracker — dots in the top-right show progress toward a long break (every 4 sessions)
• Config file — ~/.config/tomodoro/config.toml auto-created on first launch; set persistent defaults for themes, durations, volume, and more
• Desktop notifications — optional notify-send alerts on phase end; enable with notifications = true in config
• Task labeling — press t mid-session to name the current task; shown in the header; logged with each completed session
• Session history — completed focus sessions saved to ~/.local/share/tomodoro/history.json; run tomodoro history to see totals and task breakdown
• 8 animated themes — waves, rain, falling leaves, starfield, fireplace, aurora borealis, cherry blossom, sunset; all AI-crafted scenes with detailed foreground elements; set different themes for focus and break phases
• 3 render modes — half-block, quarter-block, or braille; increasing pixel density per terminal cell
• Coloured progress bar — matches the current theme; uses braille dots in braille mode
• Bell sounds — single bell when a focus session ends; countdown beeps for the last N seconds of a break (configurable)
• Phase indicators — F (focus), B (short break), LB (long break)
• Endless mode — tomodoro -E runs animations full-screen with no timer, sounds, or UI chrome; pure ambient display
• Version management — install and switch between old releases with tomodoro install, list, and --use

Version management

Install a specific older version alongside the current one:

tomodoro install 0.2.2

This pulls that version from crates.io and stores it at ~/.local/share/tomodoro/0.2.2/bin/tomodoro. It does not affect the current binary on your PATH.

List all installed versions:

tomodoro list

Run a specific version:

tomodoro --use 0.2.2

To remove an old version, delete its directory:

rm -rf ~/.local/share/tomodoro/0.2.2

Requirements

• A terminal with true colour and Unicode support (Ghostty, Kitty, WezTerm, etc.)
• Linux (Debian/Ubuntu/Mint): libasound2-dev required for audio — install with sudo apt install libasound2-dev

Contributing

Contributions welcome — see CONTRIBUTING.md.