A calm, premium terminal timer, stopwatch, and Pomodoro ritual with built-in procedural sounds.
zenritme --timer-down 25m --theme ember
zenritme --pomodoro --view cinematic --theme aura
zenritme --stopwatch --view minimal --theme mono
zenritme --timer-up --theme void --view orbitzenritme --timer-up
zenritme --timer-down <DURATION>
zenritme --stopwatch
zenritme --pomodoro [FOCUS BREAK]
zenritme --sound-test
zenritme --check-update
zenritme --check-updated
zenritme --help
zenritme -V, --version
Duration format: 30s, 10m, 1h
| Theme | Style |
|---|---|
void |
Minimal dark |
ember |
Warm red/orange |
aura |
Purple/magenta |
forest |
Green tones |
mono |
Monochrome/gray |
| View | Description |
|---|---|
minimal |
Compact single-line display |
orbit |
Circular progress indicator |
cinematic |
Full-width centered box layout |
$ zenritme -V
Version: v4.0.2
Build: linux-x86_64 (1e84ccb)
Copyright: (c) 2026 rezky_nightky (oxyzenQ)
License: GPL-3.0-only
Source: https://github.com/oxyzenQ/zenritmezenritme --check-update queries the GitHub releases API and reports whether
a newer version is available. --check-updated is accepted as an alias. This
command is read-only — it does not download, install, or replace any
binaries.
$ zenritme --check-update
zenritme update check
Current: v4.0.2
Latest: v4.0.2
Status: up to date
Source: https://github.com/oxyzenQ/zenritme/releases/latestRequires curl on the system PATH. Does not require a GitHub token.
zenritme --pomodoro # defaults: 25m focus, 5m break, 15m long break, 4 cycles
zenritme --pomodoro 3s 2s # legacy positional syntax
zenritme --pomodoro --cycles 4 # custom cycle count
zenritme --pomodoro --focus 45m --break 10m --long-break 20m --cycles 3
zenritme --pomodoro --focus 3s --break 2s --long-break 4s --cycles 2 --theme aura --view cinematic| Option | Default | Description |
|---|---|---|
--focus |
25m |
Focus session length |
--break |
5m |
Short break length |
--long-break |
15m |
Long break (after final focus cycle) |
--cycles |
4 |
Focus sessions per round |
Session flow: FOCUS 1/N → SHORT BREAK 1/N → … → FOCUS N/N → LONG BREAK → COMPLETE
| Key | Action |
|---|---|
q / Esc |
Quit |
p |
Pause / resume |
r |
Reset current session |
Zenritme ships four built-in procedural notification sounds, embedded directly into the binary at compile time. No external audio files or network access are required. The sound system is split into focused submodules (assets, playback, resolve, cooldown, cleanup) for long-term maintainability. A no-spam cooldown system prevents rapid sound toggling from producing audible spam. Temp sound files are automatically cleaned up on process exit via an RAII guard.
| Event | File | Duration | Description |
|---|---|---|---|
| Start | start.wav |
~250 ms | Gentle two-tone ascending chime |
| Pause | pause.wav |
~120 ms | Short soft blip |
| Phase | phase.wav |
~500 ms | Two-tone descending chime |
| Complete | complete.wav |
~900 ms | Three-note ascending melody |
All sounds are generated by scripts/generate-sounds.py using only the Python
standard library — pure sine-wave math, no samples, no copyrighted content.
Playback chain: The binary tries pw-play (PipeWire/PulseAudio) first.
If unavailable or playback fails, it falls back to the terminal bell (\x07).
If ZENRITME_VISUAL_BELL=1 is set, a screen flash is also triggered.
No-spam cooldowns prevent sound spam on rapid toggling:
| Event | Cooldown | Reason |
|---|---|---|
| Start | None | One-shot, fires once per session |
| Pause | 500 ms | Debounce on rapid pause toggle |
| Phase | 1 s | Debounce on phase switch |
| Complete | 2 s | Prevents repeated completion sounds |
Sound profiles control when notification sounds play:
| Profile | Behavior |
|---|---|
calm (default) |
All notification sounds enabled |
silent |
All notification sounds suppressed |
The --mute flag overrides any profile to silent.
Per-event overrides via environment variables:
ZENRITME_SOUND_START /path/to/custom.wav
ZENRITME_SOUND_PAUSE /path/to/custom.wav
ZENRITME_SOUND_PHASE /path/to/custom.wav
ZENRITME_SOUND_COMPLETE /path/to/custom.wav
ZENRITME_SOUND_FILE /path/to/global-fallback.wav
Resolution order: event-specific env → global env → built-in.
--mute flag suppresses all notification sounds for the session.
--sound-profile flag selects a sound profile (calm or silent).
zenritme --pomodoro --mute # run silently
zenritme --pomodoro --sound-profile silent # same as --mute
zenritme --pomodoro --sound-profile calm # explicit calm (default)
zenritme --sound-test # preview all soundsTemp sound files are automatically cleaned up on process exit via an RAII guard. The cleanup is PID-specific and project-specific, ensuring only Zenritme's own temp files are removed. Cleanup is idempotent and safe across panics, Ctrl+C, and normal exit paths.
Sound module architecture:
| Module | Responsibility |
|---|---|
assets |
Embedded WAV data via include_bytes!, env var names, asset metadata |
playback |
pw-play invocation, terminal bell, visual bell |
resolve |
Env override resolution, source display |
cooldown |
No-spam cooldown rules and debounce logic |
cleanup |
Temp file lifecycle, RAII TempCleanupGuard |
--theme <THEME> void | ember | aura | forest | mono (default: void)
--view <VIEW> minimal | orbit | cinematic (default: orbit)
--sound-profile <P> calm | silent (default: calm)
--mute suppress all notification sounds (default: off)
--focus <DURATION> focus session length (default: 25m)
--break <DURATION> short break length (default: 5m)
--long-break <DURATION> long break length (default: 15m)
--cycles <N> focus sessions per round (default: 4)
tar xzf zenritme-vVERSION-x86_64-unknown-linux-gnu.tar.gz
cd zenritme-vVERSION-x86_64-unknown-linux-gnu
sudo ./install.shcargo build --release --locked
sudo ./scripts/install.shCustom prefix:
PREFIX=/usr ./scripts/install.shsudo ./scripts/uninstall.sh- RULES.md — project rules, LOC guard, generated assets policy
- docs/ENDURANCE.md — endurance testing and smoke test
- docs/SECURITY.md — security policy and supply-chain minimization
- assets/sounds/README.md — built-in sound documentation
- scripts/doctor.sh — local binary health check
- scripts/endurance-smoke.sh — endurance smoke test
- Zero external dependencies — the project uses only the Rust standard library.
- LOC guard — all core code files must stay under 1000 lines. Enforced by
scripts/check-loc.sh. - Procedural assets — built-in sounds are generated from code, not downloaded.
Zenritme is licensed under the GNU General Public License v3.0 only (GPL-3.0-only).
You may use, study, modify, and redistribute Zenritme under the terms of the GPLv3. Modified versions that are distributed must preserve the same license terms and provide the corresponding source code.
Older versions that were previously released under the MIT License remain available under their original MIT terms.
The Zenritme name, logo, visual identity, README branding, screenshots, and release assets are reserved by the author unless explicitly stated otherwise.
