macOS Pomodoro timer with a CLI-first workflow
Project description
mb-pomodoro
macOS-focused Pomodoro timer with a CLI-first workflow. Work intervals only — no break timers.
- CLI is the primary interface.
- Optional GUI integrations (tray icon, Raycast extension) invoke CLI commands as subprocesses with
--json. - Persistent state and history in SQLite.
- Background worker process tracks interval completion and sends macOS notifications.
Configuration
Optional config file at <data_dir>/config.toml:
[timer]
default_duration = "25" # same formats as CLI: "25", "25m", "90s", "10m30s"
Data Directory
Default: ~/.local/mb-pomodoro. Override with --data-dir flag or MB_POMODORO_DATA_DIR env variable.
| File | Purpose |
|---|---|
pomodoro.db |
SQLite database (intervals + events). |
timer_worker.pid |
PID of the active timer worker. Exists only while a worker is running. |
pomodoro.log |
Rotating log file (1 MB max, 3 backups). |
config.toml |
Optional configuration. |
Documentation
Detailed docs in docs/:
- Timer Design — state machine, time accounting, crash recovery, database schema
- CLI Commands — command reference with examples and JSON output format
- CLI Architecture — mm-clikit patterns and project structure conventions
- Raycast Integration — Raycast script commands setup
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mb_pomodoro-0.1.3.tar.gz.
File metadata
- Download URL: mb_pomodoro-0.1.3.tar.gz
- Upload date:
- Size: 32.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a06e536acdc28a60ead69870e94b56a6be52c00060a0055121aeff4db3875436
|
|
| MD5 |
69ebcde43f19a1cf6555566cf9907c59
|
|
| BLAKE2b-256 |
158b5f064455ddd3fbf26d8a41d7bd8bd548ab49e18174aa35ec165322dfb810
|
File details
Details for the file mb_pomodoro-0.1.3-py3-none-any.whl.
File metadata
- Download URL: mb_pomodoro-0.1.3-py3-none-any.whl
- Upload date:
- Size: 31.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c56457315f7460d15feec01ac2637e2c8435a21e525be8a96342892b17fb7fb8
|
|
| MD5 |
754361f6ae9d57f10e610325a19da467
|
|
| BLAKE2b-256 |
a2a8f7768122f19cbad7e2f0953a9c99c12acf12ffca2100e51b9bc1cec177a7
|
