pomo β Terminal Pomodoro Timer


A simple, customizable Pomodoro timer for your terminal, built with Bubble Tea.
Features
- π
Work and break timer sessions
- β±οΈ Stopwatch mode for open-ended work sessions
- π Pomodoro cycles with long break
- π Task chaining with user confirmation prompts
- π Real-time progress bar visualization
- β¨οΈ Keyboard shortcuts to adjust time mid-session
- βΈοΈ Pause and resume sessions
- βοΈ Skip to next session
- π Cross-platform desktop notifications
- π¨ Clean, minimal terminal UI with ASCII art timer fonts
- π οΈ Custom commands when timers complete
Statistics
Track and manage your productivity with pomo stats:
- Overview β duration ratio (work vs break), streaks, weekly bar chart, and 4-month heatmap
- Sessions β browse all saved sessions with exact registration date and time
- Group by Title (
-t) β group saved sessions by custom task title, ordered by date and hour
- Group by Date β group saved sessions by date with daily work/break totals
- Session management β navigate saved sessions or groups and delete them with confirmation
Heatmap icons require a Nerd Font

Desktop Notifications
pomo sends native desktop notifications when sessions complete
π View notification examples
Linux (GNOME)

Windows

Note: Actual notification appearance varies by operating system and desktop environment
Timer Fonts
| mono12 |
rebel |
 |
 |
| ansi |
ansiShadow |
 |
 |
Usage
Work sessions:
pomo # work session
pomo 30m # 30m work session
pomo 45m 15m # 45m work with 15m break
pomo -t "write report" # work session with custom title (or --title)
Stopwatch sessions:
pomo stopwatch # stopwatch session
pomo stopwatch -t "deep work" # stopwatch session with custom title (or --title)
Break sessions:
pomo break # break session
pomo break 10m # 10m break session
Rest sessions (standalone break not saved to DB, counts up extra time when finished):
pomo rest # standalone rest session
pomo rest 10m # 10m standalone rest session
View statistics:
pomo stats # View your productivity stats
Installation
Homebrew (macOS)
brew install --cask bahaaio/pomo/pomo
Winget (Windows)
winget install Bahaaio.pomo
Go
go install github.com/binarynotfound/pomo@latest
Pre-built Binaries
Download pre-built binaries from the releases page.
Nix
βοΈ Nix flake installation
Option 1: Add to flake inputs and system packages
In your flake.nix:
pomo = {
url = "github:binarynotfound/pomo";
inputs.nixpkgs.follows = "nixpkgs";
};
Then add to your system packages:
environment.systemPackages = with pkgs; [
inputs.pomo.packages.${pkgs.stdenv.hostPlatform.system}.default
];
Option 2: Run directly
nix run github:binarynotfound/pomo
Build from Source
git clone https://github.com/binarynotfound/pomo
cd pomo
go build .
Configuration
π Config file search order
pomo looks for its config file in the following order:
- Current directory:
pomo.yaml (highest priority)
- System config directory:
- Linux/macOS:
~/.config/pomo/pomo.yaml
- Windows:
%APPDATA%\pomo\pomo.yaml
- Built-in defaults if no config file is found
Example pomo.yaml:
# action to take after session completion
# options: "ask" | "start" | "quit"
onSessionEnd: "ask"
asciiArt:
# use ASCII art for timer display
enabled: true
# available fonts: "mono12" | "rebel" | "ansi" | "ansiShadow"
# default: mono12
font: ansiShadow
# color of the ASCII art timer
# hex color or "none"
color: "#5A56E0"
work:
duration: 25m
title: work session
# cross-platform notifications
notification:
enabled: true
urgent: true # persistent notification with alert sound (platform-dependent)
title: work finished π
message: time to take a break
icon: ~/my/icon.png
break:
duration: 5m
# will run after the session ends
then:
- [spd-say, "Back to work!"]
longBreak:
# enable long break after a certain number of work sessions
enabled: true
# number of work sessions before long break
after: 4
# long break duration
duration: 15m
Check out pomo.yaml for a full example with all options.
Sound Notifications
You can play sounds when sessions complete by running commands in the then section.
work:
then:
- [paplay, ~/sounds/work-done.mp3] # Linux
# - [afplay, ~/sounds/work-done.mp3] # macOS
# - [powershell, start, work-done.mp3] # Windows
Commands run with a 5 second timeout and are automatically cancelled when starting the next session.
Key Bindings
Timer Controls
| Key |
Action |
β / k |
Increase time by 1 minute |
Space |
Pause/Resume timer |
β / h |
Reset to initial duration |
s |
Skip to next session |
q / Ctrl+C |
Quit |
Skip button skips directly to the next session, bypassing any prompts
Stopwatch Controls
| Key |
Action |
Space |
Pause/Resume stopwatch |
β / h |
Reset elapsed time to 00:00 |
q / Ctrl+C |
Quit and record work session |
Confirmation Dialog
| Key |
Action |
y |
Confirm (Yes) |
n |
Cancel (No) |
s |
Start short session (2 minutes) |
Tab |
Toggle selection |
Enter |
Submit choice |
q / Ctrl+C |
Quit |
Short sessions extend the current session by 2 minutes, useful when you need a bit more time
Statistics Controls (pomo stats)
| Key |
Action |
Tab / β / l |
Next view (Overview, Sessions, By Title, By Date) |
Shift+Tab / β / h |
Previous view |
1 - 4 |
Jump directly to view 1β4 |
β / k, β / j |
Navigate saved sessions and groups |
Enter / Space |
Expand/collapse group (in By Title / By Date) |
e / r |
Add or change the name of a saved session/group |
d / x / Delete |
Delete selected session or group (asks confirm) |
q / Ctrl+C |
Quit |
License
This project is licensed under the MIT License. See the LICENSE file for details.