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
tomodoro completions bash       # print bash completion script
tomodoro completions zsh        # print zsh completion script
tomodoro completions fish       # print fish completion script

To enable tab completion, pipe the output into your shell's completion setup. Examples:

# bash
tomodoro completions bash > ~/.bash_completion
echo 'source ~/.bash_completion' >> ~/.bashrc

# zsh
mkdir -p ~/.zfunc
tomodoro completions zsh > ~/.zfunc/_tomodoro
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc

# fish
tomodoro completions fish > ~/.config/fish/completions/tomodoro.fish

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
update_check = true    # notify if a newer version is available on startup
bar_style = "half"     # lock progress bar style: half | quarter | braille (default: follows render mode)

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; invalid or unrecognised values are reset to defaults with an in-app warning; new keys added by updates are merged in automatically without overwriting existing settings
• 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
• Ambient audio — looping background track per scene; all 8 themes covered; plays while the timer runs; volume follows [/]
• 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
• Update check — notifies on startup if a newer version is available; dismissible with any key; disable with update_check = false
• Bar style — lock the progress bar to half, quarter, or braille via bar_style in config, independent of the animation render mode
• Shell completions — tomodoro completions <bash|zsh|fish> prints a completion script; pipe into your shell's completion setup for tab completion
• 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.