Frequently Asked Questions

Termodoro is compiled to a single native binary that requires no external language runtime or interpreter. Platform libraries (such as ALSA's libasound on Linux) may be dynamically linked. It supports:

• Linux: x86_64, aarch64, armv7 (glibc or musl). If building from source on Linux, ALSA development headers are required for audio synthesis (libasound2-dev on Debian/Ubuntu, alsa-lib-devel on Fedora/RHEL, or alsa-lib on Arch).
• macOS: macOS 10.15+ Catalina, Big Sur, Monterey, Ventura, Sonoma, and Sequoia (native Apple Silicon M1/M2/M3/M4 & Intel x86_64).
• Windows: Windows 10 & Windows 11 (Command Prompt, PowerShell, or Windows Terminal).
• Terminal Emulators: Any modern terminal supporting ANSI TrueColor (Alacritty, Kitty, WezTerm, KDE Konsole, GNOME Terminal, iTerm2, Ghostty, Foot, Windows Terminal).

The recommended global installation method is through Cargo, Rust's official package manager:

Option A: From local clone (Recommended):

git clone https://github.com/amanalip/Termodoro.git
cd Termodoro
cargo install --path .

Option B: Directly from Git repository:

cargo install --git https://github.com/amanalip/Termodoro.git

Cargo compiles an optimized, standalone binary (~5.1 MB) and links termodoro directly into your ~/.cargo/bin directory.

Ensure Cargo's binary installation path is exported in your environment PATH variable:

• Bash (~/.bashrc) / Zsh (~/.zshrc):

  export PATH="$HOME/.cargo/bin:$PATH"

• Fish Shell (~/.config/fish/config.fish):

  fish_add_path $HOME/.cargo/bin

• PowerShell (Windows):

  $env:Path += ";$env:USERPROFILE\.cargo\bin"

After adding this, restart your terminal or run source ~/.bashrc (or source ~/.zshrc) and type termodoro to launch.

To compile and install Termodoro on Linux distributions:

1. Install build tools and ALSA audio development headers for your distribution:

   Ubuntu / Debian:

   sudo apt update && sudo apt install -y build-essential git libasound2-dev pkg-config

   Arch Linux / Manjaro / CachyOS:

   sudo pacman -S --needed base-devel git alsa-lib pkgconf

   Fedora / RHEL:

   sudo dnf install -y git alsa-lib-devel pkgconf-pkg-config

2. Install Rust and Cargo via rustup.rs (if not already installed):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source "$HOME/.cargo/env"

3. Install Termodoro globally via Cargo:

   cargo install --git https://github.com/amanalip/Termodoro.git

4. Type termodoro to launch in your favorite Linux terminal emulator (Alacritty, Kitty, WezTerm, KDE Konsole, GNOME Terminal, Ghostty, Foot).

Termodoro runs natively on macOS across both Apple Silicon (M1, M2, M3, M4) and Intel architectures:

1. Install Apple Command Line Tools if you haven't already:

   xcode-select --install

2. Install Rust and Cargo via the official installer:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source "$HOME/.cargo/env"

3. Compile and install Termodoro globally:

   cargo install --git https://github.com/amanalip/Termodoro.git

4. Ensure ~/.cargo/bin is in your ~/.zshrc:

   echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

5. Type termodoro to launch in your favorite macOS terminal (iTerm2, Ghostty, Alacritty, WezTerm, or Terminal.app). Audio chimes use macOS CoreAudio natively without extra drivers.

Termodoro is fully supported on Windows 10 and 11:

1. Download and run rustup-init.exe from rustup.rs. Select option 1 (default) to install Rust and the Microsoft Visual C++ Build Tools.
2. Open PowerShell or Windows Terminal and install Termodoro:

   cargo install --git https://github.com/amanalip/Termodoro.git

3. If termodoro is not found, ensure Cargo's binary path is added to your user PATH:

   [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.cargo\bin", "User")

4. We recommend running Termodoro inside Windows Terminal with a Nerd Font (e.g. Cascadia Code NF or JetBrains Mono) for full 24-bit TrueColor and crisp Unicode block-digit rendering.

Run cargo install with the --force flag. This tells Cargo to fetch the latest git commit on the main branch, recompile the binary in release mode, and atomically overwrite your existing binary:

cargo install --force --git https://github.com/amanalip/Termodoro.git

Your local tasks, analytics history, and saved configuration are preserved in your local XDG data directory and will not be overwritten.

To completely remove Termodoro from your system:

1. Remove the binary:

cargo uninstall termodoro

2. (Optional) Delete your local data directory:

# Linux (XDG Base Directory)
rm -rf ~/.local/share/termodoro/

# macOS
rm -rf "$HOME/Library/Application Support/com.termodoro.termodoro/"

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\termodoro\termodoro"

tmux 3.2+ includes built-in support for modal popups via display-popup. Add this to your ~/.tmux.conf:

# Bind Prefix + P to open Termodoro in a 75% centered modal popup
bind-key P display-popup -E -w 75% -h 75% "termodoro"

# Or bind Prefix + T to open in a 30% side split pane
bind-key T split-window -h -p 30 "termodoro"

Reload your configuration with tmux source ~/.tmux.conf. Pressing Prefix + P will pop up Termodoro over your current code editor or shell without disturbing your pane arrangement.

In Zellij, you can open Termodoro in a dedicated floating window with custom dimensions:

zellij run --floating --width 70% --height 70% -- termodoro

You can also define a custom keybinding in your ~/.config/zellij/config.kdl to spawn floating Termodoro windows on demand.

Yes, flawlessly. Termodoro communicates purely via standard terminal ANSI control sequences over standard I/O (stdout / stdin). It requires:

• Zero X11 forwarding or Wayland display servers (no ssh -X required).
• Zero GPU or OpenGL acceleration.
• Extremely low network bandwidth: rendering differential buffer updates consumes under 2 KB/s over SSH connections.

If themes appear washed out or reduced to 16 base ANSI colors, your terminal emulator may not be advertising 24-bit TrueColor support. Add this export to your ~/.bashrc or ~/.zshrc:

export COLORTERM=truecolor

If you are inside tmux, also ensure your ~/.tmux.conf contains:

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

Termodoro implements the canonical 4-interval Pomodoro Technique finite state machine (FSM):

1. Focus Pomodoro #1 (25 minutes) → Short Break (5 minutes)
2. Focus Pomodoro #2 (25 minutes) → Short Break (5 minutes)
3. Focus Pomodoro #3 (25 minutes) → Short Break (5 minutes)
4. Focus Pomodoro #4 (25 minutes) → Long Break (15 minutes)

The cycle indicator dots [◉ ○ ○ ○] in the top header dynamically track your progress. Once the long break finishes, the cycle counter resets back to Cycle 1.

All timer actions are mapped to ergonomic, single-keystroke controls:

• Space: Start / Pause. Pausing transitions the status to [❚❚ PAUSED] and preserves exact remaining seconds. Pressing Space again resumes the countdown.
• r: Reset Phase. Resets the clock back to the configured target duration for the current phase (e.g. back to 25:00).
• s: Skip Phase. Abandons the current phase and advances to the next state (e.g., skip the rest of a break if you are ready to focus early). Skipping never counts as a completed Pomodoro and does not advance cycle progress.
• Tab / Shift+Tab: Cycle tabs. 1-4: Jump directly to a tab (except on Tasks, where 1-3 switch backlog filters).

Yes. Navigate to Settings (4 or Tab). Termodoro supports extensive configuration bounds:

• Focus Duration: 1 to 120 minutes (default: 25 min).
• Short Break Duration: 1 to 60 minutes (default: 5 min).
• Long Break Duration: 1 to 90 minutes (default: 15 min).
• Long Break Interval: 1 to 24 cycles (default: 4 cycles).

Use j / k to select the row and h / l (or ← / →) to increment or decrement values. Changes take effect immediately and are saved to disk.

Yes. In the Settings tab (4), you can configure automated session transitions:

• Auto-Start Breaks: Automatically starts the short or long break countdown when a focus session finishes.
• Auto-Start Work: Automatically starts the next focus session when a break concludes.

Toggle either flag on or off by highlighting the setting and pressing Space or Enter.

To associate your work sessions with a specific task in your backlog:

1. Navigate to the Tasks view by pressing 2.
2. Use j / k (or ↑ / ↓) to highlight your target task.
3. Press t. A vibrant 🎯 ACTIVE badge will appear next to the item.
4. Return to the Timer view (Shift+Tab). The active task card now displays the task title and live completion progress. Every time a focus Pomodoro finishes, effort is automatically credited to this item!

When creating a task with a, you set an estimated Pomodoro count from 1 to 20. Termodoro visualizes effort using Unicode block gauges:

• [■■□□] 2/4 🍅: 2 focus intervals completed out of 4 estimated.
• [■■■■■] 5/4 🍅: Dynamic overflow handling if a complex task takes longer than originally anticipated.

On the Tasks tab (2), use the top numeric keys to switch backlog filters:

• 1: All Tasks: Displays full backlog regardless of status.
• 2: Pending Tasks: Shows only active, in-progress items.
• 3: Completed Tasks: Shows archived, finished items marked with ✔.

There is no practical limit. Tasks are indexed using 128-bit UUIDv4 identifiers and stored as compact JSON. The storage subsystem is exercised by automated stress tests handling hundreds of tasks with fast serialization and search filtering.

Termodoro's audio subsystem (src/audio.rs) is a pure procedural acoustic synthesizer. It algorithmically constructs valid 16-bit PCM RIFF WAV byte buffers in memory using mathematical sine wave functions:

• Focus Pomodoro Done: 528 Hz transformation frequency base tone blended with 1056 Hz (octave) and 1584 Hz (compound fifth) harmonic overtones and smooth exponential decay ($A(t) = A_0 e^{-\lambda t}$).
• Short Break Done: Melodic upward two-tone interval from D5 (587.33 Hz) to A5 (880.0 Hz).
• Long Break Done: Bright major triad chord arpeggio from C5 (523.25 Hz) → E5 (659.25 Hz) → G5 (783.99 Hz).

Because audio is synthesized on the fly, Termodoro requires zero external audio assets, zero sound packs, and zero disk I/O to play alerts.

Termodoro's audio engine is non-blocking and fault-tolerant. If Rodio cannot acquire an audio output handle (e.g. in a headless cloud VM or container), it silently catches the condition without panicking, triggers the native ASCII terminal bell (\x07), and continues timer execution uninterrupted.

You can also globally disable audio in Settings → Sound / Bell Alert (Space).

Termodoro utilizes notify-rust to interface with native OS notification daemons in the background:

• Linux: Communicates over the D-Bus protocol with desktop notification servers (KDE Plasma, GNOME, Dunst, Mako, SwayNC).
• macOS: Dispatches alerts via Apple's native User Notification Center API.
• Windows: Emits standard Windows Action Center Toast notifications.

Data is stored locally following standard OS conventions:

• Linux (XDG specification): ~/.local/share/termodoro/data.json (or $XDG_DATA_HOME/termodoro/data.json).
• macOS: ~/Library/Application Support/com.termodoro.termodoro/data.json.
• Windows: %APPDATA%\termodoro\termodoro\data\data.json.

All tasks, completed session records, streaks, and preferences reside in this single human-readable JSON file. You can easily back it up, sync it via Git, or inspect it with jq.

Zero. Termodoro makes no internet/HTTP requests and includes no telemetry or cloud synchronization. There are no HTTP client crates (e.g. reqwest or curl), no analytics, and no background reporting daemons. Your productivity data never leaves your local drive.

The analytics subsystem (src/stats.rs) processes your session history log:

• Daily Focus Minutes: Sums all focus sessions recorded for the current calendar date.
• 7-Day Visual Bar Chart: Renders a normalized ASCII histogram across the trailing 7 days.
• Active Streak Tracking: Counts uninterrupted consecutive days with at least one completed focus session. It properly handles midnight rollovers, leap years (366 days), and cross-year calendar boundaries.

Rust provides three foundational engineering properties essential for a robust terminal workstation:

• No Garbage-Collection Pauses: Languages like Go and Python use periodic Garbage Collection (GC) pauses to clean up memory. In a countdown timer ticking every 250ms, GC pauses introduce unpredictable timing micro-stutters. Rust provides deterministic RAII memory cleanup with zero GC pauses (though OS scheduling and I/O can still introduce timing jitter).
• Zero-Cost Abstractions: High-level Rust constructs (pattern matching, iterators, functional closures, state machines) compile down to highly efficient machine code without inherent abstraction overhead.
• Single Native Binary Distribution: Unlike Python or Node.js which require heavy runtime environments and virtualenvs, Rust compiles into a single native binary with no language runtime required.

Ratatui is the gold standard for terminal user interfaces in the Rust ecosystem:

• Immediate-Mode UI Architecture: Rather than maintaining a complex, mutable virtual DOM that can get out of sync, Ratatui renders the full UI freshly on each frame directly from immutable state structs (&App). This reduces UI/state synchronization complexity.
• Cassowary Constraint Layout Engine: Ratatui incorporates the Cassowary linear constraint solver, allowing Termodoro's 4 views, tables, and modal dialogs to fluidly adapt across terminal geometries tested from $20\times 10$ through $350\times 120$.
• Headless TestBackend Testing: Ratatui provides a headless in-memory buffer backend. This enables our 311 automated test suite to assert exact cell characters, colors, and layout invariants in CI without needing a virtual display server (Xvfb).

Cargo provides exceptional build engineering, security, and developer ergonomics:

• Cryptographic Lockfile Reproducibility (Cargo.lock): Every transitive dependency version and SHA256 checksum is pinned, so all machines build from identical, checksum-verified dependency sources. (This pins dependency resolution; it does not by itself guarantee bit-for-bit identical binaries across different toolchains.)
• Integrated Security Audits: The project can be checked with cargo audit, which flags dependencies with known RustSec advisories, while cargo clippy enforces idiomatic Rust conventions.
• One-Line Global Installation: Anyone with Rust installed can run cargo install --git ... to build and link the binary directly to their PATH.

Electron applications must bundle an entire Google Chromium web browser engine, the V8 JavaScript compiler, and the Node.js runtime, consuming 200MB to 500MB of system RAM just to run a countdown timer.

Termodoro is compiled directly to native machine code (ELF on Linux, Mach-O on macOS, PE on Windows). Its entire state resides in compact stack-allocated Rust structs and cache-friendly vectors, measuring a tiny 4,676 kB resident set size (VmRSS) in a single measurement on a Linux development machine (release build; results vary by hardware and OS).

Termodoro uses an event-driven loop with a 250 ms tick rate and non-blocking key event polling (crossterm::event::poll), so the thread sleeps whenever there is no input or tick due.

When unattended, the process sleeps between events and wakes only once per 250 ms tick, yielding execution back to the kernel so CPU cores can enter deep low-power sleep states (C-states). Average idle CPU usage is very low and power draw is negligible, though not literally zero.

Termodoro's own Rust source contains no unsafe blocks, enforced at compile time via [lints.rust] unsafe_code = "forbid" in Cargo.toml (with CI running cargo clippy -- -D warnings). Dependencies may internally use unsafe code.

When you feel the urge to start a focus session, waiting 3 to 8 seconds for a heavy web app to load breaks your momentum. Termodoro starts from cold disk to full interactive TUI in 5.13 milliseconds on the reference Linux development machine (release build; results vary by hardware, OS, and storage), giving you instantaneous focus flow without cognitive friction.

Termodoro installs a custom panic hook in src/main.rs (setup_panic_hook()) before starting the event loop. If an unhandled panic ever occurs, the hook immediately catches the error, restores raw terminal mode back to cooked mode, exits the alternate screen buffer (LeaveAlternateScreen), and restores cursor visibility (cursor::Show) before printing the stack trace.

This guarantees that your terminal emulator is never left in a frozen or broken state.