pomo

Terminal Pomodoro timer with a virtual study room. Zero dependencies, POSIX sh, macOS + Linux.

  FOCUS SESSION

  24:32  ████████████████░░░░░░░░░░░░  work

Features

• Live countdown with pink progress bar, rewrites in place
• Auto tmux layout — runs pomo start from any terminal, spawns a 4-pane tmux session automatically
• Virtual study room — NPCs join your session, change statuses, go on tangents, leave mid-session. 10 companions, 6 personalities, 70+ activities
• Toast notifications — slide in from the right, vanish — NPC events without interrupting the timer
• Ambient sound loop — shuffles your own audio files via afplay
• Discord-style status cards — your card + individual NPC cards, dynamic width
• tmux integration — cava audio visualizer, cbonsai bonsai tree, live room watcher, status bar countdown
• Session log + stats — flat CSV log, today's focus time, all-time totals
• macOS notifications — native Notification Center via osascript

Install

git clone https://github.com/YOUR_USERNAME/pomo.git ~/pomo
sh ~/pomo/install.sh

Symlinks pomo into ~/.local/bin/. Assumes ~/.local/bin/ is already on your $PATH.

Optional tools (auto-detected, skip silently if absent):

brew install cava cbonsai

Usage

pomo start [mins]     # work session         (default: 25)
pomo break [mins]     # short break          (default: 5)
pomo long  [mins]     # long break           (default: 15)
pomo stop             # kill running session
pomo log   [n]        # last N sessions      (default: 20)
pomo stats            # today + all-time focus totals
pomo mood  "text"     # set your status card text
pomo room             # print the full room (your card + active NPCs)
pomo card             # print just your card
pomo test  [module]   # run test modules (room / toast / npc / layout)

Layout

pomo start auto-spawns a tmux session with a 4-pane layout:

┌─────────────────────────┬──────────────────────┐
│                         │  pomo room           │
│   pomo timer            │  (live, 4s refresh)  │
│                         ├──────────────────────┤
├─────────────────────────┤  cbonsai / pomo stats│
│   cava / pomo log       │                      │
└─────────────────────────┴──────────────────────┘

• Top-left — timer, progress bar, FOCUS SESSION header
• Top-right — live room view, refreshes every 4s. Toast notifications appear here
• Bottom-right — cbonsai (if installed), otherwise pomo stats
• Bottom-left — cava (if installed), otherwise pomo log

No tmux? pomo start creates the session for you automatically.

Virtual study room

NPCs trickle into your work sessions, update their statuses, go on tangents, and say goodbye when they leave. The room feels alive without being distracting.

╭─ liamnguyen ────────────────╮
│  ●  building something      │
│  🎵 forest-rain             │
│  🍅 session 3               │
╰─────────────────────────────╯

╭─ alex ──────────────────────╮    ╭─ mia ───────────────────────╮
│  ●  tracing a bug 40min     │    │  ◌  grabbing tea            │
╰─────────────────────────────╯    ╰─────────────────────────────╯

NPC events fire as toast notifications in the top-right pane — slide in, hold 3s, vanish.

Test the room with a short session:

POMO_NPC_SPEED=fast pomo start 3
# or
pomo test npc     # 120s NPC loop, no timer
pomo test layout  # 3-min full session, fast NPCs

POMO_NPC_SPEED=fast fires events every 2–8s instead of 8–15min.

Ambient sound

Drop audio files into ~/.local/share/pomo/sounds/. Supported formats: .mp3 .aiff .wav .m4a.

pomo shuffles them and loops automatically. No config needed — just drop and go. The currently playing track shows on your room card as 🎵 forest-rain.

Free CC0 sources:

• freesound.org — search "rain", "forest", "cafe" → filter CC0
• pixabay.com/music — royalty-free, no signup
• archive.org — public domain collections

tmux status bar

Add to ~/.tmux.conf:

set -g status-interval 5
set -g status-right '#(~/pomo/tmux/status.sh) | %H:%M'

Shows 🍅 24:32 while a session runs. Disappears between sessions.

Session log

Sessions are written to ~/.local/share/pomo/sessions.log:

2026-03-02T14:32:00,work,25,completed
2026-03-02T15:01:00,break,5,interrupted

interrupted when you Ctrl-C early — still logged, excluded from focus totals.

Testing

pomo test room     # render cards with mock NPC data — instant
pomo test toast    # fire 3 test toasts — verify animation
pomo test npc      # 120s fast NPC session + live room view
pomo test layout   # full 3-min session, fast NPCs, full tmux layout

Customization

Colors — edit the palette block at the top of lib/display.sh. 24-bit format: \033[38;2;R;G;Bm. Current theme is hot pink #FF69B4.

Default durations — edit the dispatcher in pomo:

start) _run_session work  "${1:-25}" ;;
break) _run_session break "${1:-5}"  ;;
long)  _run_session long  "${1:-15}" ;;

NPC personalities and activity pools — edit lib/npc.sh. Add new NPCs to NPC_ROSTER, add activities to any _pool_* function.

Tips

Chain a full Pomodoro block:

pomo start && pomo break && pomo start && pomo break && pomo start && pomo long

Set your mood before a session:

pomo mood "shipping before midnight"
pomo start

Kill a stuck ambient sound:

pomo stop

View raw log:

cat ~/.local/share/pomo/sessions.log

License

MIT