A curses-based Pomodoro timer for terminal people who want focus sessions, keyboard-driven menus, and logs they can grep later.

No accounts. No dashboards. No productivity gamification. Just: pick a task, run a timer, take a break, repeat.

PomoCLI is a terminal UI written in Python using curses. It is designed for people who already live in a terminal and want a Pomodoro tool that stays fast, local, and honest.

The application supports:

• Starting a Pomodoro session with an explicit task
• Displaying that task while the timer runs
• Loud, unmissable completion alerts
• Viewing past sessions from a plain-text log
• Editing work and break durations via an in-app settings menu

Everything runs locally. Nothing phones home.

• Curses-based TUI
  Menu-driven interface with keyboard navigation and a dedicated timer screen.

• Task visibility
  Whatever you enter for What are you working on stays visible during the active timer.

• Configurable durations
  Work and break lengths can be adjusted in-app and persist across runs.

• Completion alert
  Timer completion triggers a terminal bell and a full-screen flash, repeated five times.

• Plain-text logging
  Sessions are appended to a human-readable text file with timestamps and session state.

• Built-in log viewer
  Scroll and page through previous Pomodoros directly inside the terminal UI.

• Zero external dependencies
  Uses only the Python standard library.

• Python 3.9 or newer
• A terminal that supports curses

Note: Native Windows terminals have limited curses support. This tool is intended primarily for macOS and Linux environments.

Clone the repository and run the script directly:

git clone https://github.com/asyrewicze/pomocli.git
cd pomocli
python3 pomocli.py

Optional: make the script executable and run it directly:

    chmod +x pomocli.py
    ./pomocli.py

Launch the application:

python3 pomocli.py

You will be presented with a main menu that allows you to:

• Start a Pomodoro
• View previous Pomodoros
• Adjust settings
• Quit the application

Menus:

• Up and Down arrows to navigate
• Enter to select
• q to go back or quit

Timer screen:

• q to abort the active timer

Log viewer:

• Up and Down arrows to scroll
• Page Up and Page Down to move by page
• Home and End to jump to start or end
• q to exit the viewer

Configuration is stored locally in the following file:

~/.pomocli_config.json

Example contents:

    {
      "work_minutes": 25,
      "break_minutes": 5
    }

You may edit this file manually, but the recommended approach is to use the Settings option inside the application.

Pomodoro sessions are logged to a plain-text file:

    ~/pomocli_log.txt

Each entry includes a timestamp, session state, and task description. Example:

    2026-01-18 T=14:05 - START: Fix README formatting
    2026-01-18 T=14:30 - END: Fix README formatting

The log format is intentionally simple so it can be grepped, parsed, or archived without tooling.

PomoCLI is intentionally:

• Terminal-first
• Minimal
• Opinionated
• Text-file driven

If you want charts, cloud sync, or productivity gamification, this is not that tool.

If you want a Pomodoro timer that integrates cleanly into a terminal command center and stays out of your way, PomoCLI does exactly that.

As of 01/18/2026, pomocli is licensed under GPLv3 (GNU Public License v3.0)