{
  "markdown": "# Qtile Pomodoro\n\nA Qtile-specific X11 Pomodoro service: persistent timer state, Qtile bar status, all-screen break overlays, local history, and CLI controls.\n\n## Install\n\nInstall into the Python environment that launches Qtile so `config.py` can import the widget. For a UV-managed Qtile installation:\n\n```bash\nuv pip install --python /path/to/qtile/bin/python .\n```\n\nOn this workstation the interpreter is:\n\n```bash\nuv pip install --python ~/.local/share/uv/tools/qtile/bin/python .\n```\n\nThis is deliberately not a `pipx` installation: pipx isolates its packages from Qtile's Python environment.\n\nThe desktop must provide `notify-send` (libnotify). Create `~/.config/qtile-pomodoro/config.toml` to override defaults:\n\n```toml\n[timer]\nfocus_minutes = 25\nshort_break_minutes = 5\nlong_break_minutes = 15\nlong_break_after = 4\n```\n\nState and completed-session history live in `$XDG_DATA_HOME/qtile-pomodoro/timer.sqlite3`. The configuration reload command changes only future phases.\n\n## Qtile integration\n\nAdd this to `config.py`:\n\n```python\nimport subprocess\nfrom libqtile import hook, widget\nfrom qtile_pomodoro.task_widget import TaskCount, TaskOverlay\n\n@hook.subscribe.startup_once\ndef start_pomodoro():\n    subprocess.Popen([\"qtile-pomodoro\", \"daemon\"])\n\n# Add Pomodoro() and TaskCount() to a bar's widgets list; bind Mod+N:\nKey([mod], \"n\", lazy.function(lambda qtile: TaskOverlay.toggle(qtile)))\n```\n\nThe widget is display-only. Bind Qtile keys to these commands:\n\n```text\nqtile-pomodoro start | pause | reset | skip | reload | stats\n```\n\n`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`.\n\n## Task overlay\n\nA daemonless, Qtile-native task list: `Mod+N` (or clicking `Tasks:N` in the\nbar) opens a centered popup with **Today** and **Inbox** lists.\n\n- Type to add; `Tab` picks the target list; `Enter` commits.\n- `j`/`k` move the highlight, `d` completes, `m` moves between lists;\n  clicking a row completes it.\n- A dimmed **Done (N)** section shows the 5 most recent completions.\n- `Esc` backs out of typing, then closes.\n\nTasks persist in `$XDG_DATA_HOME/qtile-pomodoro/tasks.json`; completions are\nretained (hidden) as history. Independent of the Pomodoro daemon.\n\n**Todoist sync** (optional): add a Todoist API token to the config:\n\n```toml\n[tasks]\ntodoist_api_token = \"…\"\n```\n\nThe overlay then becomes a Todoist client — Today = tasks due today\n(overdue included), Inbox = the Todoist Inbox project, with add /\ncomplete / move writing through to Todoist. The JSON file is a cache:\nthe overlay opens instantly offline and queued changes replay on\nreconnect (`↻N` shows pending writes; `r` forces a refresh). Without a\ntoken, everything stays purely local.\n\n## Semantics\n\n- Only focus intervals reaching zero count in statistics.\n- Notifications are emitted only when a focus or break completes.\n- Pausing preserves remaining time; resetting focus aborts it to Idle.\n- Timer elapsed time follows wall-clock time, including suspend and service restart. Recovery processes only the interrupted phase transition.\n- `qtile-pomodoro stats` reports local-day and ISO-week totals plus retained local history.\n",
  "bytes": 3375,
  "sha": "d9fcaa1872edbe98f13fa7867953b3d0bd9d75aadd7f3f68503bfb02eff5785f",
  "repo_slug": "mailhexu/qtile-pomodoro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_mailhexu_qtile_pomodoro_memnotes_project_d5437c92/readme"
}