Pomodoro CLI Timer

A terminal-based pomodoro timer. Nothing fancy — just a work/break cycle that runs in your terminal while you work.

I built it because every time I tried to use a pomodoro app, it became part of the distraction. Open the browser, load the app, click start — suddenly you’re checking notifications on three different tabs. A terminal timer stays exactly where you want it: in the same window as your code.

How it works

The timer cycles through work and break sessions. Four work sessions, then a long break. Otherwise short breaks between each round.

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case " ":
            m.isRunning = !m.isRunning
            if m.isRunning {
                return m, timerCmd()
            }
            return m, nil
        case "q", "ctrl+c":
            return m, tea.Quit
        case "r":
            m.resetTimer()
            return m, nil
        }
    case tickMsg:
        if m.isRunning {
            m.remaining -= time.Second
            m.progress = float64(m.totalDuration-m.remaining) / float64(m.totalDuration)
            if m.remaining <= 0 {
                // Cycle between work and breaks
                // ... session-switching logic ...
                return m, timerCmd()
            }
            return m, timerCmd()
        }
    }
    return m, nil
}

The whole thing follows the Bubble Tea architecture: a single Update function handles every message (keystrokes, ticks, quit requests), and returns the next model. No state to track across functions. No event listeners to debug.

Controls

• Space — pause or resume
• R — reset
• Q or Ctrl+C — quit

Why Go?

Two reasons. First, Bubble Tea is a Go framework, so Go was the obvious choice. Second, Go compiles to a single binary that runs on any machine — no Node, no Python, no dependencies. Download the binary, run it, it works. That’s the kind of simplicity I like in a tool meant to help me focus.

Build it yourself

go install github.com/spectari-code/pomodoro-cli@latest

Or just clone and run:

git clone https://github.com/spectari-code/pomodoro-cli.git
cd pomodoro-cli
go run .

---

github.com/spectari-code/pomodoro-cli