I replaced a paid pomodoro app with a 300-line Python script

Description and use

The author replaced a paid Pomodoro app with a 300‑line Python CLI that logs sessions to a CSV, supports Jalali and Gregorian calendars, and offers start, end, status, and aggregation commands.

Problem

Paid pomodoro apps restrict historical data and lack support for the Persian (Jalali) calendar, preventing long-term time analysis and custom calendar usage.

Outcome

The author achieved full control over Pomodoro logging, unlimited historical data, and calendar flexibility with a simple CLI script, eliminating the need for a paid app.

Workflow

• 1. Install the script from GitHub.
• 2. Run pomo start <task> to begin a session; a new CSV row is created with start time.
• 3. Run pomo end to finish the session; the same row is updated with end time and duration.
• 4. Run pomo status to see if a session is currently running.
• 5. Run pomo agg to aggregate and analyze session data over time.
• 6. Optionally set POMODORO_CALENDAR=gregorian to use the Gregorian calendar instead of the default Jalali.

Evidence

I replaced a paid pomodoro app with a 300-line Python script

Source

Each session is one row in a CSV: uuid, date, weekday, task, start_hour, start_minute, end_hour, end_minute, mins

Source