timr-tui

TUI to organize your time: Pomodoro, Tabata, Countdown, Timer, Event.

[1] countdown Use it for your workout, yoga/breathing sessions, meditation, handstand or whatever.
[2] timer Check the time on anything you are doing.
[3] pomodoro Organize your working time to be focused all the time by following the Pomodoro Technique. Pomodoro becomes Tabata by auto-detection.
[4] event Count the time for any event in the future or past.

Preview

(theme depends on your terminal preferences)

Pomodoro

Tabata (auto-detected)

Timer

Countdown (incl. Mission Elapsed Time)

Event (past/future)

Local time

Local time (footer)

Toggle deciseconds

Maximum (`9999y` `364d` `23:59:59.9`)

Change style

CLI

timr-tui --help

Usage: timr-tui [OPTIONS]

Options:
  -c, --countdown <COUNTDOWN>        Countdown time to start from. Formats: 'Yy Dd hh:mm:ss', 'Dd hh:mm:ss', 'Yy mm:ss', 'Dd mm:ss', 'Yy ss', 'Dd ss', 'hh:mm:ss', 'mm:ss', 'ss'. Examples: '1y 5d 10:30:00', '2d 4:00', '1d 10', '5:03'.
  -w, --work <WORK>                  Work time to count down from. Formats: 'ss', 'mm:ss', 'hh:mm:ss'
  -p, --pause <PAUSE>                Pause duration. Single value (every round): '5:00'. Variable: 'regular,special[,every_n_rounds]' - special pause every N rounds, default every 4. Examples: '5:00,25:00' or '5:00,30:00,5'. Duration formats: 'ss', 'mm:ss', 'hh:mm:ss'.
      --max-rounds <MAX_ROUNDS>      Maximum number of pomodoro rounds. 0 = unlimited.
      --tabata                       Tabata regimen: work 20s, pause 10s, 8 rounds, auto-switch enabled.
      --auto-switch                  Enable auto-switch between `work` and `pause` screens.
  -e, --event <EVENT>                Event date time and title (optional). Format: 'YYYY-MM-DD HH:MM:SS' or 'time=YYYY-MM-DD HH:MM:SS[,title=...]'. Examples: '2025-10-10 14:30:00' or 'time=2025-10-10 14:30:00,title=My Event'.
  -d, --decis                        Show deciseconds.
  -m, --mode <MODE>                  Mode to start with. [possible values: countdown, timer, pomodoro, event, localtime]
  -s, --style <STYLE>                Style to display time with. [possible values: full, light, medium, dark, thick, cross, braille]
      --menu                         Open menu.
  -v, --vim <VIM>                    Enable/disable Vim motions. [possible values: on, off]
  -r, --reset                        Reset stored values to defaults.
  -n, --notification <NOTIFICATION>  Enable/disable desktop notifications. Experimental. [possible values: on, off]
      --blink <BLINK>                Enable/disable blink mode to animate a clock when it reaches its finished mode. [possible values: on, off]
      --sound [<SOUND>]              Sound notification: 'on', 'off' or path to a custom sound file (.mp3 or .wav).
      --log [<LOG>]                  Directory for log file. If not set, standard application log directory is used (check README for details).
  -h, --help                         Print help
  -V, --version                      Print version

--sound is not available in builds w/o sound (timr-tui-nosound-* release binaries or built with --no-default-features).

Notification

Desktop

Toggle desktop notifications with --notification on|off or by pressing d (see Keybindings).

Sound

A sound is played by default when a clock is done. Toggle it with --sound on|off or by pressing s (see Keybindings). --sound without a value equals --sound on.

A custom sound (--sound <path>) is used for the current session only. Every start without a path plays the default sound. To use a custom sound permanently, add an alias to your shell config, e.g. alias timr='timr-tui --sound {path-to}/my-sound.mp3'.

Keybindings

Note: To enable Vim motions key binding, run with --vim=on once. It will be stored as part of settings, so only running once is needed. To disable, run --vim=off.

Screens

Key	Description
`1`	Pomodoro
`2`	Countdown
`3`	Timer
`4`	Event
`0`	Local Time
`→`	next screen
`←`	previous screen
`l`	next screen (Vim motions)
`h`	previous screen (Vim motions)

Controls

Key	Description
`space`	start/stop
`r`	reset
`e`	enter edit mode
`d`	toggle desktop notification
`s`	toggle sound
`q`	quit

In edit mode only:

Key	Description
`s`	save changes
`esc`	skip changes
`←` or `→`	change selection
`h` or `l`	change selection (Vim motions)
`↑`	edit to go up
`k`	edit to go up (Vim motions)
`ctrl+↑`	edit to go up 10x
`ctrl+k`	edit to go up 10x (Vim motions)
`↓`	edit to go down
`j`	edit to go down (Vim motions)
`ctrl+↓`	edit to go down 10x
`ctrl+j`	edit to go down 10x (Vim motions)

In Event edit mode only:

Key	Description
`enter`	save changes
`esc`	skip changes
`tab`	switch input

In Pomodoro screen only:

Key	Description
`ctrl+←` or `ctrl+→`	switch work/pause
`ctrl+h` or `ctrl+l`	switch work/pause (Vim motions)
`a`	toggle auto switch work/pause
`↑`	next round
`k`	next round (Vim motions)
`↓`	previous round
`j`	previous round (Vim motions)
`ctrl+↑`	increase max rounds
`ctrl+k`	increase max rounds (Vim motions)
`ctrl+↓`	decrease max rounds
`ctrl+j`	decrease max rounds (Vim motions)
`ctrl+r`	reset rounds
`ctrl+s`	save initial value

In Countdown screen only:

Key	Description
`ctrl+e`	edit by local time
`ctrl+s`	save initial value
`:`	toggle finish time

Appearance

Key	Description
`,`	toggle styles
`.`	toggle deciseconds
`:`	toggle local time

Installation

Requirements

Windows / macOS: nothing to install.
Linux w/ sound requires ALSA to be installed. It's usually pre-installed on desktop systems. Without ALSA the binary doesn't start (error while loading shared libraries: libasound.so.2). Use a build w/o sound instead (timr-tui-nosound-* release binary or --no-default-features).

Runtime packages per distro

Distro	Package
Debian 12 / Ubuntu ≤ 23.10	`libasound2`
Debian 13+ / Ubuntu 24.04+	`libasound2t64`
Fedora	`alsa-lib`
Arch	`alsa-lib`
openSUSE	`libasound2`
Others	ALSA library (`libasound.so.2`)

Cargo

On Linux, building w/ sound (default) requires the ALSA headers and pkg-config:

Build dependencies per distro

Distro	Packages
Debian / Ubuntu	`libasound2-dev`, `pkg-config`
Fedora	`alsa-lib-devel`, `pkgconf-pkg-config`
Arch	`alsa-lib`, `pkgconf`
openSUSE	`alsa-devel`, `pkg-config`
Others	ALSA headers + `pkg-config`

To build w/o sound, add --no-default-features to the commands below.

From crates.io

cargo install timr-tui

From GitHub repository

cargo install --git https://github.com/sectore/timr-tui

Arch Linux

Install from the AUR:

paru -S timr

Nix

Note: Currently timr-tui is available on the unstable channel only.

Note: Since v1.12.0 sound is enabled by default. Use enableSound = false to disable it. Before v1.12.0 sound was disabled by default and had to be enabled by enableSound = true.

Command line

# default (w/ sound)
nix-env -iA nixpkgs.timr-tui
# or w/o sound
nix-env -iA nixpkgs.timr-tui --arg timr-tui '(timr-tui.override { enableSound = false; })'

Configuration

# default (w/ sound)
environment.systemPackages = with pkgs; [
  timr-tui
];
# or w/o sound
environment.systemPackages = with pkgs; [
  (timr-tui.override { enableSound = false; })
];

Home Manager

# default (w/ sound)
home.packages = with pkgs; [
  timr-tui
];
# or w/o sound
home.packages = with pkgs; [
  (timr-tui.override { enableSound = false; })
];

Source at nixpkgs: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ti/timr-tui/package.nix

Release binaries

Pre-built artifacts are available to download from latest GitHub release.

Platform	w/ sound	w/o sound
Linux (x86_64)	`timr-tui-<version>-linux_x86_64.tar.gz`	`timr-tui-nosound-<version>-linux_x86_64.tar.gz`
Windows (x86_64)	`timr-tui-<version>-windows_x86_64.zip`	-
macOS (Apple Silicon, macOS 14+)	`timr-tui-<version>-macos_aarch64.tar.gz`	-

Binaries w/ sound play a sound by default. To turn it off, use --sound off or press s.

Linux w/ sound requires glibc 2.28+ and ALSA (see Requirements). timr-tui-nosound-* is statically linked and runs on any Linux (x86_64).

Development

Requirements

Nix users (recommend)

cd into root directory.

If you have direnv installed, run direnv allow once to install dependencies. In other case run nix develop.

Non Nix users

Rust
Clippy
rustfmt
dprint
just
Linux only: ALSA headers + pkg-config (see Cargo) to build w/ sound

Commands

just

Available recipes (just)

Available recipes:
    default                    # list commands

    [build]
    build                      # build app [alias: b]
    build-nosound              # build app without sound feature [alias: bn]

    [demo]
    demo-all                   # build all demos [alias: da]
    demo-blink                 # build demo: blink animation [alias: db]
    demo-countdown             # build demo: countdown [alias: dc]
    demo-countdown-finish      # build demo: countdown + finish time [alias: dcf]
    demo-countdown-max         # build demo: countdown-max [alias: dcmx]
    demo-countdown-met         # build demo: countdown + met [alias: dcm]
    demo-decis                 # build demo: deciseconds [alias: dd]
    demo-event                 # build demo: event [alias: de]
    demo-local-time            # build demo: local time [alias: dlt]
    demo-local-time-footer     # build demo: local time (footer) [alias: dltf]
    demo-menu                  # build demo: menu [alias: dm]
    demo-pomodoro              # build demo: pomodoro [alias: dp]
    demo-pomodoro-auto-special # build demo: pomodoro + auto-switch + special pause [alias: dpas]
    demo-rocket-countdown      # build demo: rocket countdown [alias: drc]
    demo-style                 # build demo: styles [alias: ds]
    demo-timer                 # build demo: timer [alias: dt]
    demo-timer-max             # build demo: timer-max [alias: dtm]

    [dev]
    run                        # run app [alias: r]
    run-args args              # run app with arguments. It expects arguments as a string (e.g. "-c 5:00"). [alias: ra]
    run-nosound args=""        # run app without sound feature. Optional arguments as string (e.g. "-c 5:00"). [alias: rn]

    [misc]
    format                     # format files [alias: f]
    lint                       # lint [alias: l]
    lint-nosound               # lint without sound feature [alias: ln]

    [test]
    test                       # run tests [alias: t]
    test-nosound               # run tests without sound feature [alias: tn]

Build

Linux

# w/ sound, for Nix only
nix build
# or w/ sound, dynamically linked against glibc 2.28+ (non Nix distros)
nix build .#linux
# or w/o sound, statically linked
nix build .#linuxNoSound

Windows (cross-compilation)

nix build .#windows

Run tests

cargo test
# or w/o sound
cargo test --no-default-features

Misc

Persistant app state

Stored on file system:

# Linux
~/.local/state/timr-tui/data/app.data
# macOS
/Users/{user}/Library/Application Support/timr-tui/data/app.data
# Windows
C:/Users/{user}/AppData/Local/timr-tui/data/app.data

Logs

To get log output, start the app by passing --log to timr-tui. See CLI for details.

Logs will be stored in an app.log file at following locations:

# Linux
~/.local/state/timr-tui/logs/app.log
# macOS
/Users/{user}/Library/Application Support/timr-tui/logs/app.log
# `Windows`
C:/Users/{user}/AppData/Local/timr-tui/logs/app.log

Optional: You can use a custom directory by passing it via --log arg.

Contributing

CONTRIBUTING.md

License

MIT License

Default sound: confirmation-004 via soundcn, CC0.

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.github/workflows		.github/workflows
assets		assets
demo		demo
src		src
.envrc		.envrc
.gitignore		.gitignore
.rustfmt.toml		.rustfmt.toml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
dprint.json		dprint.json
flake.lock		flake.lock
flake.nix		flake.nix
justfile		justfile
rust-toolchain.toml		rust-toolchain.toml

Latest commit

History

Folders and files

Repository files navigation

timr-tui

Table of Contents

Preview

Pomodoro

Tabata (auto-detected)

Timer

Countdown (incl. Mission Elapsed Time)

Event (past/future)

Local time

Local time (footer)

Toggle deciseconds

Maximum (9999y 364d 23:59:59.9)

Change style

Menu

CLI

Notification

Desktop

Sound

Keybindings

Menu

Screens

Controls

Appearance

Installation

Requirements

Cargo

From crates.io

From GitHub repository

Arch Linux

Nix

Command line

Configuration

Home Manager

Release binaries

Development

Requirements

Nix users (recommend)

Non Nix users

Commands

Build

Run tests

Misc

Persistant app state

Logs

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages

Maximum (`9999y` `364d` `23:59:59.9`)