Coffee Clock

Coffee Clock is a terminal countdown timer and Pomodoro app built with Rust, Ratatui, and Crossterm. It displays time in large FIGlet art and supports pausing, automatic work and break cycles, a live system clock, and customizable colors and fonts. Fonts are bundled into the executable, so no runtime downloads are needed.

简体中文文档

Requirements and Setup

Install Rust 1.88 or newer and Cargo. From the project directory, run:

cargo run

By default, the app starts a one-minute countdown. You can specify a duration or start a Pomodoro session:

cargo run -- --time 25m
cargo run -- --time 1h30m10s
cargo run -- --pomo

Durations use positive integer values with units in hour, minute, second order: h, m, and s. Examples include 1h30m10s, 25m, and 45s. The --pomo and --time options are mutually exclusive. Build a release executable with:

cargo build --release

Invalid durations are reported on stderr with exit code 2, before the terminal UI starts.

Keyboard and Commands

Press : to open the command bar. Press Enter to execute a command or Esc to cancel. Use the arrow keys, Home, End, Backspace, and Delete to edit input. Tab or ↓ selects the next suggestion; Shift-Tab or ↑ selects the previous one. Suggestions appear as you type. Commands and suggestions are case-insensitive. Pressing q in normal mode does not exit; use :q or :quit.

Command	Action
q, quit	Exit the app
r, restart	Restart the current countdown or Pomodoro phase
r 25m, restart 25m	Restart a regular countdown with the specified duration
s, stop	Pause the timer and retain the remaining time
c, continue	Start or resume the timer
cd 25m, countdown 25m	Set a regular countdown; run :continue to start it
t, time	Toggle between the timer and the local 24-hour clock
pomo	Start Pomodoro mode; replacing an unfinished countdown requires confirmation
worktime 25m	Set the duration for the next work phase
breaktime 5m	Set the duration for the next short break
resttime 15m	Set the duration for the next long break
restart work, restart break, restart rest	Restart the specified Pomodoro phase and reset the cycle count
set color cyan, sc #12ABEF	Set the FIGlet display color
set font slant, sf mini	Set the FIGlet font
help	Open command help; arrows scroll, Esc closes
set bell on, set bell off	Enable or disable the terminal bell
save	Save current appearance, phase durations, and bell setting

Command feedback appears at the right side of the title row and disappears after a few seconds. Opening the command bar, help, or the system clock does not pause the timer. A finished countdown displays 00:00:00; restart it or set a new duration to count again. In the command bar, Ctrl-P / Ctrl-N browse up to 100 commands from this session and restore your draft when returning past the latest command. Up / Down retain their completion behavior.

Countdown completion and Pomodoro transitions produce a terminal bell and visible feedback. Terminal settings determine whether the bell is audible. Use --no-bell at startup or :set bell off to disable it; delayed ticks spanning multiple phases produce one alert for the latest phase.

Pomodoro Timer

The default cycle consists of 25 minutes of work followed by a 5-minute short break. After four work phases, the app runs a 15-minute long break and then starts a new cycle. Transitions start automatically. Changes to phase durations take effect the next time that phase begins. Use stop and continue to pause and resume the current phase.

The status bar shows both the phase and timer state, for example [Work | Running] or [Work | Paused]. The paused state stays visible after command feedback disappears, including while viewing the system clock.

While the app is running, use :pomo to switch from a regular countdown to Pomodoro mode, or :countdown 25m to switch back. Replacing the active mode requires confirmation. The confirmation dialog defaults to No; use the Left/Right arrow keys or Tab to change the selection, then press Enter. You can also press y to confirm or n or Esc to cancel. The timer keeps running while confirmation is pending.

Appearance

Built-in FIGlet fonts are standard (default), small, big, slant, mini, and banner. Colors can be specified by common terminal color names (such as cyan, orange, purple, and pink) or HEX values in #RRGGBB and #RGB formats. Color and font names are case-insensitive. Color rendering depends on terminal support. If the selected font does not fit, the display tries small, then mini, then plain digits; enlarging the window restores the selected font. Short windows use a compact command line.

Bundled fonts originate from the FIGlet 2.2.5 fonts in the cmatsuoka/figlet repository. See assets/fonts/LICENSE for their license. Font data is embedded in the executable.

Saved Settings

Use :save to persist the current color, font, three Pomodoro durations, and bell setting. Settings load on the next launch; active countdowns and command history stay within the current session. Configuration files are validated before starting the terminal UI and replaced atomically when saved.

The default file is %APPDATA%\coffee-clock\config\config.toml on Windows, ~/.config/coffee-clock/config.toml on Linux (or $XDG_CONFIG_HOME/coffee-clock/config.toml), and ~/Library/Application Support/coffee-clock/config.toml on macOS. Use --config path/to/config.toml for another location. A missing file uses defaults until you save; --no-config ignores settings and disables saving. --no-bell overrides the loaded bell setting for the session; an explicit :save includes that override.

See examples/config.toml for all supported fields. Download prebuilt archives from Releases; changes are listed in CHANGELOG.md.

Development and Validation

cargo fmt --check
cargo test --locked --all-targets
cargo clippy --locked --all-targets -- -D warnings

GitHub Actions runs these checks on Linux, Windows, and both Intel and Apple Silicon macOS for pull requests and pushes to master. Version tags run the same checks before building release archives. See CONTRIBUTING.md for the development and release workflow.

CI also verifies the minimum supported Rust version and audits Cargo.lock for RustSec advisories. Dependabot checks for Cargo and GitHub Actions updates.

Project Structure

• src/main.rs: CLI arguments, terminal lifecycle, and event loop.
• src/app.rs: Application state, keyboard events, and command execution.
• src/command.rs: Command parsing, input editing, and completion.
• src/config.rs: Validated settings and atomic configuration saves.
• src/model.rs: Countdown state and duration parsing.
• src/pomodoro.rs: Work and break cycle logic.
• src/appearance.rs: Color parsing, fonts, and appearance settings.
• src/view.rs: Terminal UI and FIGlet layout.
• assets/fonts/: Bundled FIGlet fonts.