{"id":45435978,"url":"https://github.com/tmux-contrib/tmux-pomodoro","last_synced_at":"2026-04-02T11:49:34.081Z","repository":{"id":333665376,"uuid":"1138187470","full_name":"tmux-contrib/tmux-pomodoro","owner":"tmux-contrib","description":"A tmux plugin for pomodoro","archived":false,"fork":false,"pushed_at":"2026-02-19T10:07:28.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T11:39:18.602Z","etag":null,"topics":["pomodoro","tmux","tmux-plugins"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmux-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T10:56:04.000Z","updated_at":"2026-01-20T13:46:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tmux-contrib/tmux-pomodoro","commit_stats":null,"previous_names":["tmux-contrib/tmux-pomodoro"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tmux-contrib/tmux-pomodoro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-pomodoro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-pomodoro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-pomodoro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-pomodoro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmux-contrib","download_url":"https://codeload.github.com/tmux-contrib/tmux-pomodoro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-pomodoro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29704400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T23:35:04.139Z","status":"online","status_checked_at":"2026-02-22T02:00:08.193Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pomodoro","tmux","tmux-plugins"],"created_at":"2026-02-22T03:00:49.402Z","updated_at":"2026-04-02T11:49:34.073Z","avatar_url":"https://github.com/tmux-contrib.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmux-pomodoro\n\n\u003e A full-featured Pomodoro timer for tmux with color-coded status, chord keybindings, and interactive duration menus — powered by the **pomodoro** CLI built in this repository.\n\n[![Test](https://github.com/tmux-contrib/tmux-pomodoro/actions/workflows/test.yml/badge.svg)](https://github.com/tmux-contrib/tmux-pomodoro/actions/workflows/test.yml) [![Release](https://img.shields.io/github/v/release/tmux-contrib/tmux-pomodoro)](https://github.com/tmux-contrib/tmux-pomodoro/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## Prerequisites\n\n- [pomodoro](/crates/pomodoro/README.md) — the Pomodoro\n  timer CLI built in this repository\n\n### Installing pomodoro\n\n**Using Nix** (recommended):\n\n```bash\nnix profile install github:tmux-contrib/tmux-pomodoro\n```\n\n**Using Cargo:**\n\n```bash\ncargo install --path crates/pomodoro\n```\n\n## Installation\n\n### Using TPM (Tmux Plugin Manager)\n\nAdd the following line to your `~/.tmux.conf`:\n\n```tmux\nset -g @plugin 'tmux-contrib/tmux-pomodoro'\n```\n\nThen press `prefix + I` to install the plugin.\n\n### Manual Installation\n\n1. Clone this repository:\n\n   ```bash\n   git clone https://github.com/tmux-contrib/tmux-pomodoro ~/.tmux/plugins/tmux-pomodoro\n   ```\n\n2. Add this line to your `~/.tmux.conf`:\n\n   ```tmux\n   run-shell ~/.tmux/plugins/tmux-pomodoro/main.tmux\n   ```\n\n3. Reload tmux configuration:\n\n   ```bash\n   tmux source-file ~/.tmux.conf\n   ```\n\n## Usage\n\nAdd `#{pomodoro}` to your `status-right` or `status-left`:\n\n```tmux\nset -g status-right \"#{pomodoro} | %H:%M\"\n```\n\nThe plugin color-codes the remaining time automatically based on the current\nsession state and kind:\n\n| State | Kind  | Color   | Example output |\n| ----- | ----- | ------- | -------------- |\n| any   | focus | red     | ` 20:45`      |\n| any   | break | blue    | ` 05:00`      |\n| none  | none  | default | ` 00:00`      |\n\n## Keybindings\n\nPress `prefix + p` to enter the pomodoro key table, then:\n\n| Key | Action                                      |\n|-----|---------------------------------------------|\n| `f` | Smart toggle: start focus / pause / resume  |\n| `b` | Start a break session                       |\n| `s` | Stop and reset the current session          |\n\nThe smart toggle (`f`) checks the current state:\n- **running** → pauses the session (`pomodoro stop`)\n- **anything else** → starts/resumes (`pomodoro start`)\n\n### Customizing the chord prefix\n\nThe `p` key is configurable. To use a different key, set `@pomodoro-key` in\nyour `~/.tmux.conf` **before** the plugin loads:\n\n```tmux\nset -g @pomodoro-key \"P\"   # use prefix+P instead\n```\n\n\u003e **Note:** tmux binds `prefix + p` to `previous-window` by default. This\n\u003e plugin overwrites that binding. To keep previous-window accessible, rebind it\n\u003e before loading the plugin:\n\u003e\n\u003e ```tmux\n\u003e bind-key N previous-window\n\u003e ```\n\n### Customizing sub-keys\n\nThe three sub-keys are individually configurable via `@pomodoro-key-focus`,\n`@pomodoro-key-break`, and `@pomodoro-key-stop`:\n\n```tmux\nset -g @pomodoro-key-focus \"f\"   # default\nset -g @pomodoro-key-break \"b\"   # default\nset -g @pomodoro-key-stop  \"s\"   # default\n```\n\nFor example, to use Ctrl-key variants instead:\n\n```tmux\nset -g @pomodoro-key-focus \"C-f\"\nset -g @pomodoro-key-break \"C-b\"\nset -g @pomodoro-key-stop  \"C-s\"\n```\n\n### Disabling notifications\n\nBy default, each action (start, pause, resume, stop) shows a tmux status-bar\nnotification. To suppress all notifications, set `@pomodoro-notify` to\n`off` in your `~/.tmux.conf` **before** the plugin loads:\n\n```tmux\nset -g @pomodoro-notify \"off\"\n```\n\n## CLI Commands\n\nControl the timer directly from your terminal:\n\n```bash\n# Start a 25-minute focus session (default)\npomodoro start\n\n# Start a 5-minute break session\npomodoro start --mode break\n\n# Start a focus session with a custom duration\npomodoro start --mode focus --duration 45m\n\n# Pause a running session\npomodoro stop\n\n# Abort (reset) the current session\npomodoro stop --reset\n\n# Display current status (text format)\npomodoro status\n\n# Display current status as JSON\npomodoro status --output json\n\n# Display with a custom MiniJinja template\npomodoro status --format \"{{ kind }} | {{ '%02d:%02d' | format(remaining_secs // 60, remaining_secs % 60) }}\"\n```\n\n### Template Variables\n\nThe `--format` flag accepts a [MiniJinja](https://docs.rs/minijinja) template. The following variables are available:\n\n| Variable         | Type    | Description                                              | Example                                             |\n| ---------------- | ------- | -------------------------------------------------------- | --------------------------------------------------- |\n| `kind`           | string  | Session type                                             | `focus`, `break`, `none`                            |\n| `state`          | string  | Current lifecycle state                                  | `running`, `paused`, `completed`, `aborted`, `none` |\n| `planned_secs`   | integer | Planned session duration in seconds                      | `1500`                                              |\n| `elapsed_secs`   | integer | Total elapsed time in seconds                            | `300`                                               |\n| `remaining_secs` | integer | Time remaining in seconds (clamped to zero when expired) | `1200`                                              |\n\nTime formatting with MiniJinja's `format` filter:\n\n```\n{{ '%02d:%02d' | format(remaining_secs // 60, remaining_secs % 60) }}\n```\n\n## Troubleshooting\n\n### Status bar shows nothing\n\n1. Check if pomodoro is installed:\n\n   ```bash\n   which pomodoro\n   ```\n\n2. Verify pomodoro works:\n\n   ```bash\n   pomodoro status\n   ```\n\n3. Start a session to test:\n\n   ```bash\n   pomodoro start\n   ```\n\n4. Reload tmux configuration:\n\n   ```bash\n   tmux source-file ~/.tmux.conf\n   ```\n\n### Icons not displaying\n\nYour terminal may not support the Nerd Font icons or emoji used in the format\ntemplate. Ensure you have a [Nerd Font](https://www.nerdfonts.com/) installed\nand configured in your terminal emulator.\n\n### Status not updating\n\ntmux status bars refresh based on the `status-interval` option. For\nsecond-level accuracy:\n\n```tmux\nset -g status-interval 1\n```\n\n### Permission denied errors\n\nEnsure the scripts are executable:\n\n```bash\nchmod +x ~/.tmux/plugins/tmux-pomodoro/main.tmux\nchmod +x ~/.tmux/plugins/tmux-pomodoro/scripts/*.sh\n```\n\n## How It Works\n\n1. The plugin registers a `#{pomodoro}` format string that tmux will interpolate\n2. When tmux renders the status bar, it executes `scripts/tmux_pomodoro.sh`\n3. The script queries `pomodoro status --format \"\u003ctemplate\u003e\"` where the\n   template embeds tmux color codes based on `state` and `kind`\n4. The colored output is written directly to the status bar\n5. If no Pomodoro is active (`state` is `none`), nothing is displayed\n6. If the pomodoro CLI is not installed, nothing is displayed\n\n## Development\n\n### Prerequisites\n\nInstall dependencies using [Nix](https://nixos.org/):\n\n```sh\nnix develop\n```\n\nThis drops you into a shell with `bash`, `tmux`, `bats`, and the full Rust\ntoolchain (`cargo`, `rustc`, `rustfmt`, `clippy`, `rust-analyzer`).\n\nOr install manually: `bash`, `tmux`, `bats`, and [Rust](https://rustup.rs/).\n\n### Running Tests\n\n```sh\nbats tests/\n```\n\n### Building the CLI\n\n```sh\n# With Nix\nnix build\n\n# With Cargo\ncargo install --path crates/pomodoro\n```\n\n### Debugging\n\nEnable trace output with the `DEBUG` environment variable:\n\n```sh\nDEBUG=1 /path/to/tmux-pomodoro/scripts/tmux_pomodoro.sh\n```\n\n## Related Projects\n\n- [tmux-keyboard](https://github.com/tmux-contrib/tmux-keyboard) — Display\n  keyboard layout in tmux\n- [tmux-flow](https://github.com/tmux-contrib/tmux-flow) — Display Flow app\n  status in tmux\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmux-contrib%2Ftmux-pomodoro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmux-contrib%2Ftmux-pomodoro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmux-contrib%2Ftmux-pomodoro/lists"}