PTTM - Pomodoro Timer & Task Manager

PTTM is a terminal-based Pomodoro app built with Textual. It provides a timer, task tracking, and configurable work/break settings in a compact TUI.

Features

• Pomodoro timer with focus, short break, and long break modes
• Audible ding sound on every mode transition (synthesised at first launch, cached as ding.wav)
• Task list with per-task Pomodoro counts
• Persistent configuration stored as JSON
• Keyboard shortcuts for all timer and task actions
• In-app settings tab for adjusting timing values
• Auto-start next timer — optionally begin the next timer automatically when the current one ends
• Full keyboard navigation in the Tasks and Settings tabs (arrow keys, Escape)

Requirements

• Python 3.10 or newer
• aplay (ALSA/PipeWire) for audio — pre-installed on most Linux desktops

Installation

You can install the application globally from PyPI using pipx:

pipx install pttm

To install it locally for development, clone the repository and install it in editable mode:

git clone https://github.com/Shru-10p/pttm.git
cd pttm
pipx install -e .

Run

Start the app with:

pttm

Keyboard Shortcuts

Global

Tasks tab

Settings tab

Configuration

The app reads and writes a JSON config file. By default, the file is stored in your user config directory. You can override the location by setting PTTM_CONFIG_PATH before launch.

export PTTM_CONFIG_PATH=./pttm_config.json
pttm

Settings

The config also persists the completed focus session count and all task data across launches.

Audio

On first launch, PTTM synthesises a short bell-tone (ding.wav) using only Python's standard library and stores it next to the config file. From then on the cached file is reused directly — no re-synthesis, no network access, and no extra Python dependencies.