flow

A focus-protecting triage agent. You brain-dump at a cheap, dedicated flow session ; it captures everything into the Thurbox task list, dispatches real work to worker sessions (each on its own git worktree), monitors them quietly, grooms the backlog, and ends every reply with the single next thing to focus on.

Overview #

flow is agent-agnostic , like Thurbox itself. The triager and workers are plain agents.toml aliases ( flow , flow-worker , flow-worker-heavy ), so each can be claude, codex, antigravity, opencode, vibe, … The behavior lives in a plain context file, FLOW.md , surfaced to whichever CLI runs it via symlinks ( CLAUDE.md / AGENTS.md / GEMINI.md → FLOW.md ). All orchestration goes through thurbox-cli — the core binary has no flow-specific code.

Install #

flow is a Thurbox extension (a declarative extension.toml manifest):

thurbox-cli extension install flow      # or ./extensions/flow from a checkout
thurbox-cli extension uninstall flow    # --purge also deletes ~/.config/thurbox/extensions/flow

Installing lays down the flow home ( ~/.config/thurbox/extensions/flow ; override with --home ), registers the agents, and activates the dedicated flow session — self-healed by Thurbox, so deleting it is a no-op until you deactivate . Flow is event-driven (worker pushes over the mailbox queue wake it); there is no scheduled automation.

Use #

• Open the flow session and type at it — anything that isn't tick / status / clean is treated as a brain-dump.
• Dispatchable items spawn a worker immediately (a task-<id>-<slug> session on a flow/<slug> worktree branch when the repo is git).
• status for a one-screen report; clean to groom the backlog.
• Plan-first, with a relay: before writing any code each worker asks ≥3 clarifying questions and waits, then sends a written plan and waits for your approval, then builds. It hands these to the flow session over the message queue ( message send --kind questions|plan|result ); flow surfaces them under “Needs you,” you answer / approve naturally, and flow relays your reply straight back to the worker — a pure pass-through.
• Workers self-report: they mark their task done and send a --kind result message, which wakes the flow session so the next task dispatches immediately.

How it works #

Dispatch is eager : capture creates the task and spawns its worker in one atomic helper call. Worker↔flow coordination is event-driven over the inter-session message queue ( thurbox-cli message ): a worker pushes a structured questions , plan , or result message (which also wakes flow), and flow drains its inbox with message inbox --for flow --claim — clean JSON, never scraped from a rendered terminal. Flow ships no scheduled automation — a manual tick is the safety net you type at the flow session: it drains anything a missed wake left queued, catches crashed workers, and grooms stale state.

Files #

See extensions/flow for the FLOW.md behavior spec, the extension.toml manifest, and the helper scripts ( create-task.sh , flow-snapshot.sh , parse-result.sh ). The Features page covers the design rationale.