timr-tui

March 23, 2026 · View on GitHub

TUI to organize your time: Pomodoro, 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.
[4] event Count the time for any event in the future or past.

Preview

(theme depends on your terminal preferences)

Pomodoro

Timer

Countdown (incl. Mission Elapsed Time)

Event (past/future)

Local time

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 time to count down from. Formats: 'ss', 'mm:ss', 'hh:mm:ss'
  -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]
      --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

Extra option (if --features sound is enabled by local build only):

--sound <SOUND>                Path to sound file (.mp3 or .wav) to play as notification. Experimental.

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.

Key	Description
`m`	Toggle menu

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
`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)
`ctrl+r`	reset round
`ctrl+s`	save initial value

In Countdown screen only:

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

Appearance

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

Installation

Cargo

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.

Command line

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

Configuration

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

Home Manager

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

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.

Development

Requirements

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

Commands

just

Available recipes:
    default                  # list commands

    [build]
    build                    # build app [alias: b]

    [demo]
    demo-blink               # build demo: blink animation [alias: db]
    demo-countdown           # build demo: countdown [alias: dc]
    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-rocket-countdown    # build demo: rocket countdown [alias: drc]
    demo-style               # build demo: styles [alias: ds]
    demo-timer               # build demo: timer [alias: dt]

    [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-sound path           # run app while sound feature is enabled. It expects a path to a sound file. [alias: rs]
    run-sound-args path args # run app while sound feature is enabled by adding a path to a sound file and other arguments as string (e.g. "-c 5:00"). [alias: rsa]

    [misc]
    format                   # format files [alias: f]
    lint                     # lint [alias: l]

    [test]
    test                     # run tests [alias: t]

Build

Linux

nix build
# or for bulding w/ statically linked binaries
nix build .#linuxStatic

Windows (cross-compilation)

nix build .#windows

Run tests

cargo test

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