EPIC: RAGE Qtile control plane — Emacs workflows + Agent Zero without secrets in git #108

New issue

Open

opened 2026-08-22 22:01:10 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-22 22:01:10 +00:00

(Migrated from github.com)

Goal

Turn Qtile from a pile of launchers into a small desktop control plane. Workflow selection and Agent Zero interaction should happen through compact Emacs client frames while Qtile remains non-blocking.

Research baseline

Agent Zero's current external API documents POST /api_message for sending a message and authenticates external calls with X-API-KEY. Its current A0 CLI can also connect to a configured AGENT_ZERO_HOST. For a Qtile button, use the small external HTTP API rather than scraping the Web UI; keep host/key runtime-configurable.

Required pieces

Org desktop integration

Left-screen current-clock widget asks the running Emacs daemon for the active Org clocked heading.
TODO button opens a compact emacsclient frame with the user's agenda/TODO view.
Do not run synchronous emacsclient calls on Qtile's event loop.
Graceful emacs offline state; clicking may start/fall back through -a where appropriate.

Workflow automation

A Qtile action opens an Emacs completing-read style workflow picker in a small frame.
Workflow definitions are declarative data, not a giant chain of shell strings.
Selected workflow can route/move/focus existing windows and launch missing applications.
It must tolerate absent apps and changed screen counts.
Workflows address screen roles (left, center, right, aux) instead of hardcoded output numbers.

Ask Agent Zero

Bar button opens a compact Emacs client UI for the prompt.
Backend posts to Agent Zero /api_message with X-API-KEY.
AGENT_ZERO_HOST can be overridden without editing tracked code.
API key comes only from environment or a per-user ignored file.
Defaults are safe: localhost-ish/configurable host is okay; never commit credentials.
Network work is async/off the Qtile event loop; errors surface as a notification / compact status instead of freezing the bar.

Config contract

Tracked code may document these names but not values:

AGENT_ZERO_HOST
AGENT_ZERO_API_KEY
optional AGENT_ZERO_API_KEY_FILE

Provide an example config with placeholders and make the real local override ignored.

Tests / gates

Emacs command execution is asynchronous.
Org clock parsing handles no clock / daemon unavailable / weird quoting.
TODO and workflow frames have stable WM title/class so Qtile can float/dropdown them reliably.
Workflow screen-role resolution tested at N=1..4.
Agent Zero request unit test verifies endpoint and X-API-KEY header without using a real secret.
Agent Zero host override test.
No secret-shaped value added to git.
Qtile test suite and literate parity green.

RAGE rule

Do as much of the vertical slice as possible per pass: UI -> async bridge -> routing -> tests -> docs. Do not leave another half-wired button that only works on one monitor.

## Goal Turn Qtile from a pile of launchers into a small desktop control plane. Workflow selection and Agent Zero interaction should happen through compact Emacs client frames while Qtile remains non-blocking. ## Research baseline Agent Zero's current external API documents `POST /api_message` for sending a message and authenticates external calls with `X-API-KEY`. Its current A0 CLI can also connect to a configured `AGENT_ZERO_HOST`. For a Qtile button, use the small external HTTP API rather than scraping the Web UI; keep host/key runtime-configurable. ## Required pieces ### Org desktop integration - Left-screen current-clock widget asks the running Emacs daemon for the active Org clocked heading. - TODO button opens a compact `emacsclient` frame with the user's agenda/TODO view. - Do not run synchronous `emacsclient` calls on Qtile's event loop. - Graceful `emacs offline` state; clicking may start/fall back through `-a` where appropriate. ### Workflow automation - A Qtile action opens an Emacs completing-read style workflow picker in a small frame. - Workflow definitions are declarative data, not a giant chain of shell strings. - Selected workflow can route/move/focus existing windows and launch missing applications. - It must tolerate absent apps and changed screen counts. - Workflows address screen **roles** (`left`, `center`, `right`, `aux`) instead of hardcoded output numbers. ### Ask Agent Zero - Bar button opens a compact Emacs client UI for the prompt. - Backend posts to Agent Zero `/api_message` with `X-API-KEY`. - `AGENT_ZERO_HOST` can be overridden without editing tracked code. - API key comes only from environment or a per-user ignored file. - Defaults are safe: localhost-ish/configurable host is okay; **never** commit credentials. - Network work is async/off the Qtile event loop; errors surface as a notification / compact status instead of freezing the bar. ## Config contract Tracked code may document these names but not values: - `AGENT_ZERO_HOST` - `AGENT_ZERO_API_KEY` - optional `AGENT_ZERO_API_KEY_FILE` Provide an example config with placeholders and make the real local override ignored. ## Tests / gates - [ ] Emacs command execution is asynchronous. - [ ] Org clock parsing handles no clock / daemon unavailable / weird quoting. - [ ] TODO and workflow frames have stable WM title/class so Qtile can float/dropdown them reliably. - [ ] Workflow screen-role resolution tested at N=1..4. - [ ] Agent Zero request unit test verifies endpoint and `X-API-KEY` header without using a real secret. - [ ] Agent Zero host override test. - [ ] No secret-shaped value added to git. - [ ] Qtile test suite and literate parity green. ## RAGE rule Do as much of the vertical slice as possible per pass: UI -> async bridge -> routing -> tests -> docs. Do not leave another half-wired button that only works on one monitor.

lost-rob0t commented

2026-08-22 22:20:17 +00:00

(Migrated from github.com)

First control-plane slice landed in #109 (merged to master as 4a37779). Org TODO/clock integration, Emacs workflow picker, role-based workflow routing, async Agent Zero /api_message client, and gitignored host/secret configuration are merged. Keeping this epic open because richer workflow automation (for example launching missing apps) is still follow-up work.

First control-plane slice landed in #109 (merged to `master` as `4a37779`). Org TODO/clock integration, Emacs workflow picker, role-based workflow routing, async Agent Zero `/api_message` client, and gitignored host/secret configuration are merged. Keeping this epic open because richer workflow automation (for example launching missing apps) is still follow-up work.