Terminal Pomodoro Timer in C++ docs

A terminal-based Pomodoro productivity timer written in modern C++. Features an ASCII-rendered iMac workstation frame, ANSI truecolor themes, non-blocking keyboard controls, interval audio alerts, and automated local session logging to disk.

Overview

The Pomodoro Technique structures work into focused intervals separated by short restorative pauses. This C++ utility brings structured timeboxing into developers’ terminal workflows, rendering countdown progress inside an ASCII hardware display frame while tracking completed focus intervals over time.

Key Features

ASCII Terminal Frame: Renders an iconic iMac hardware frame surrounding countdown digits and status indicators.
Interval Management: Pre-configured for deep work intervals (50-minute focus periods followed by 10-minute breaks) or customizable Pomodoro cycles.
Session Logging: Automatically appends completed focus sessions, start/end timestamps, and duration records to session_log.txt.
Non-Blocking Control: Intercepts keyboard input via POSIX termios without blocking execution, enabling pause, resume, and skip shortcuts.
Terminal Aesthetics: Employs 256-color ANSI palettes including Space Gray, Midnight, Aluminum, and Copper highlight tones.

Requirements

C++17 compatible compiler (g++, clang++)
POSIX terminal environment (macOS Terminal, Linux shell)

Compilation

Compile with optimization:

g++ -std=c++17 -O2 pomodoro.cpp -o pomodoro

On macOS:

clang++ -std=c++17 -O2 pomodoro.cpp -o pomodoro

Usage

Start the timer from your terminal:

./pomodoro

Controls

Space: Pause or resume current countdown.
s: Skip current interval (transition focus to break).
q: Quit timer and write session summary to log.

Session History

Completed sessions are automatically preserved in session_log.txt:

==================================================
Date: 2026-03-08 14:30:00 | Duration: 50 min | Focus
Date: 2026-03-08 15:20:00 | Duration: 10 min | Break
==================================================

Project Status

Stable and operational. Used as a daily terminal productivity tool.

Authors and Acknowledgment

Developed by Adam Anwar. Designed for distraction-free terminal focus.

License

MIT License.

Support

Submit issues, questions, or bug reports to the GitHub issue tracker: https://github.com/ADM1SH/pomodoro-timer/issues

Roadmap

Done: Core architecture and baseline implementation.
Done: Functional verification and test coverage.
To do: Add sound notification via native terminal bell or system audio
To do: Add persistent task logging to SQLite

Contributing

Contributions are welcome.

Fork the repository.
Create a feature branch: git checkout -b feature/improvement.
Commit your changes: git commit -m "feat: enhance functionality".
Push to the branch: git push origin feature/improvement.
Open a Pull Request.