Pomodoro Timer TUI

A terminal-based Pomodoro timer with lofi music integration, built with Bun, Ink, and React.

Features

• Full-screen TUI with progress bar and session tracking
• Configurable work/break durations
• Lofi radio streaming during work sessions
• Collaborative group sessions for real-time multiplayer pomodoro
• Session history saved to JSON (for Obsidian/tool integration)
• Cross-platform notification sounds

Installation

Quick Install (Recommended)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/treepo1/pomodoro-tui/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/treepo1/pomodoro-tui/master/install.ps1 | iex

Manual Installation

Download the latest release from GitHub Releases and add it to your PATH.

Build from Source

Requires Bun runtime.

git clone https://github.com/treepo1/pomodoro-tui.git
cd pomodoro-tui
bun install
bun run build

Requirements

• For music playback (optional): mpv

Installing Audio Players (for music)

Linux (Debian/Ubuntu):

sudo apt install mpv

macOS:

brew install mpv

Windows:

# Install mpv from https://mpv.io/installation/
# Or use winget:
winget install mpv

Building a Standalone Executable

You can build a single-file executable that includes the Bun runtime and all dependencies:

bun run build

This creates a pomotui executable that can be distributed and run without requiring Bun to be installed:

# Run the executable directly
./pomotui

# With options
./pomotui --work 50 --short 10

The executable is platform-specific:

• Built on macOS → runs on macOS
• Built on Linux → runs on Linux
• Built on Windows → runs on Windows

To distribute to multiple platforms, build on each target platform or use cross-compilation tools.

Usage

# Start with default settings (25/5/15 minute sessions)
bun run start

# Custom durations
bun run start -w 50 -s 10 -l 30

# Disable music
bun run start -m off

# Custom history file (for Obsidian integration)
bun run start -d ~/obsidian/pomodoro.json

CLI Options

Option	Short	Description	Default
--work <min>	-w	Work session duration	25
--short <min>	-s	Short break duration	5
--long <min>	-l	Long break duration	15
--cycles <n>	-c	Pomodoros before long break	4
--data <path>	-d	History file path	~/.pomodoro/history.json
--music <mode>	-m	Music mode: radio, off	radio
--host		Host a group session
--join <code>		Join a group session
--name <name>		Your name in group sessions	User
--help	-h	Show help

Keyboard Controls

Key	Action
s	Start timer
p	Pause timer
r	Reset current session
n	Skip to next session
m	Toggle music on/off
> or .	Next radio station
q	Quit

Music

Lofi Radio (Default)

The app includes 8 curated radio stations:

• Lofi Girl
• ChillHop
• Box Lofi
• Lofi Cafe
• Study Beats
• Antena 1
• FM Sergipe
• Smooth Jazz

Group Sessions

Work together with friends in real-time collaborative pomodoro sessions:

# Host a session
pomotui --host --name "Alice"
# Output shows: SESSION: XYZ234

# Join a session (on another computer)
pomotui --join XYZ234 --name "Bob"

Features:

• Real-time timer sync across all participants
• Host controls the timer (start/pause/reset/skip)
• Automatic host transfer when host leaves
• Manual host transfer via [1-9] keys

History File

Completed sessions are saved to ~/.pomodoro/history.json:

{
  "entries": [
    {
      "id": "1705500000000-abc1234",
      "sessionType": "work",
      "duration": 25,
      "completedAt": "2024-01-17T10:00:00.000Z",
      "date": "2024-01-17",
      "pomodoroNumber": 1
    }
  ],
  "totalPomodoros": 1,
  "lastUpdated": "2024-01-17T10:00:00.000Z"
}

Obsidian Integration

Point the history file to your Obsidian vault:

bun run start -d ~/obsidian/pomodoro-data.json

You can then create Obsidian templates or dataview queries to visualize your pomodoro data.

Development

# Run in watch mode
bun run dev

# Type check
bun run tsc --noEmit

License

MIT