# tomodoro
A terminal Pomodoro timer with animated backgrounds.
[](https://crates.io/crates/tomodoro)
## Install
```sh
cargo install tomodoro
```
Requires Rust — install via [rustup](https://rustup.rs) 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.
| `Space` | Start / pause |
| `n` | Skip to next phase |
| `r` | Restart current phase |
| `e` | Edit timer durations |
| `t` | Set task label |
| `[` / `]` | Volume down / up |
| `←` / `→` | Cycle animation themes |
| `↑` / `↓` | Cycle render modes (Half → Quarter → Braille) |
| `?` | Toggle help overlay |
| `Esc` | Cancel edit / quit |
| `q` / `Ctrl+C` | Quit |
### CLI flags
```sh
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:
```sh
# 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.
| `Space` | Pause / resume animation |
| `←` / `→` | Cycle animation themes |
| `↑` / `↓` | Cycle render modes |
| `q` / `Esc` / `Ctrl+C` | Quit |
## Config
On first launch, `~/.config/tomodoro/config.toml` is created with all options commented out. Uncomment and edit to set persistent defaults:
```toml
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:
```sh
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:
```sh
tomodoro list
```
Run a specific version:
```sh
tomodoro --use 0.2.2
```
To remove an old version, delete its directory:
```sh
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](CONTRIBUTING.md).