Agent Skills
Bundle OKF 0.2 · 2 conceitos · mailhexu/qtile-pomodoro
Open source Repository Open in the app JSON README (API)
About
# Agent Skills
* [Usage Skill](qtile-pomodoro-usage/SKILL.md) - Consumer guidance for supported Project interfaces.
* [Development Skill](qtile-pomodoro-development/SKILL.md) - Contributor guidance for implementation and development infrastructure.
Details
- Kind
- OKF bundles
- Topic
- Cloud & DevOps
- Publisher
- mailhexu
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Last push
- 2026-09-08T21:27:29Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-09-08 02:20:20
- Updated
- 2026-09-08 02:20:20
- Origin id
mailhexu/qtile-pomodoro:memnotes/Projects/qtile-pomodoro/skills/index.md
README
# Qtile Pomodoro
A Qtile-specific X11 Pomodoro service: persistent timer state, Qtile bar status, all-screen break overlays, local history, and CLI controls.
## Install
Install into the Python environment that launches Qtile so `config.py` can import the widget. For a UV-managed Qtile installation:
```bash
uv pip install --python /path/to/qtile/bin/python .
```
On this workstation the interpreter is:
```bash
uv pip install --python ~/.local/share/uv/tools/qtile/bin/python .
```
This is deliberately not a `pipx` installation: pipx isolates its packages from Qtile's Python environment.
The desktop must provide `notify-send` (libnotify). Create `~/.config/qtile-pomodoro/config.toml` to override defaults:
```toml
[timer]
focus_minutes = 25
short_break_minutes = 5
long_break_minutes = 15
long_break_after = 4
```
State and completed-session history live in `$XDG_DATA_HOME/qtile-pomodoro/timer.sqlite3`. The configuration reload command changes only future phases.
## Qtile integration
Add this to `config.py`:
```python
import subprocess
from libqtile import hook, widget
from qtile_pomodoro.task_widget import TaskCount, TaskOverlay
@hook.subscribe.startup_once
def start_pomodoro():
subprocess.Popen(["qtile-pomodoro", "daemon"])
# Add Pomodoro() and TaskCount() to a bar's widgets list; bind Mod+N:
Key([mod], "n", lazy.function(lambda qtile: TaskOverlay.toggle(qtile)))
```
The widget is display-only. Bind Qtile keys to these commands:
```text
qtile-pomodoro start | pause | reset | skip | reload | stats
```
`start` resumes or starts focus. A completed focus interval starts a break and shows a full-screen overlay on every X11 screen. Clicking its single **Skip Break** control starts focus immediately. A completed or reset break enters **Ready to work**; press Space in the resume surface or invoke `qtile-pomodoro start`.
## Task overlay
A daemonless, Qtile-native task list: `Mod+N` (or clicking `Tasks:N` in the
bar) opens a centered popup with **Today** and **Inbox** lists.
- Type to add; `Tab` picks the target list; `Enter` commits.
- `j`/`k` move the highlight, `d` completes, `m` moves between lists;
clicking a row completes it.
- A dimmed **Done (N)** section shows the 5 most recent completions.
- `Esc` backs out of typing, then closes.
Tasks persist in `$XDG_DATA_HOME/qtile-pomodoro/tasks.json`; completions are
retained (hidden) as history. Independent of the Pomodoro daemon.
**Todoist sync** (optional): add a Todoist API token to the config:
```toml
[tasks]
todoist_api_token = "…"
```
The overlay then becomes a Todoist client — Today = tasks due today
(overdue included), Inbox = the Todoist Inbox project, with add /
complete / move writing through to Todoist. The JSON file is a cache:
the overlay opens instantly offline and queued changes replay on
reconnect (`↻N` shows pending writes; `r` forces a refresh). Without a
token, everything stays purely local.
## Semantics
- Only focus intervals reaching zero count in statistics.
- Notifications are emitted only when a focus or break completes.
- Pausing preserves remaining time; resetting focus aborts it to Idle.
- Timer elapsed time follows wall-clock time, including suspend and service restart. Recovery processes only the interrupted phase transition.
- `qtile-pomodoro stats` reports local-day and ISO-week totals plus retained local history.