From e91ceb83a48e131afa296fbc149d8549c691a136 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 22 Apr 2026 20:48:13 -0400 Subject: [PATCH] docs: add token-efficient agent supervision use case MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a use case describing how ClawdChan's existing primitives — ContentDigest envelopes and cursor-based inbox — can reduce token burn in supervised-agent setups that run Claude Code around the clock. The pattern replaces blind /loop polling + context accumulation with: - Iteration digests: fixed-size ContentDigest summaries replace growing conversation context across iterations. - Event-driven dispatch: external sidecar sends work via CLI, agent skips expensive logic when inbox is empty. Includes an explicit caveat that CC is reactive and cannot be woken from outside — an external orchestrator is still needed. Also adds a clarifying bullet to 'What ClawdChan is not' noting it is not an orchestrator or scheduler. Relates to #51. Signed-off-by: Andrew Anderson --- docs/use-cases.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/use-cases.md b/docs/use-cases.md index b3e3f99..02c56e8 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -51,6 +51,42 @@ N paired peers exchange structured digests each morning. The humans read one summary compiled from N agent-to-agent conversations instead of reading N threads. +## Token-efficient agent supervision + +A supervised-agent setup runs one or more Claude Code sessions around the +clock via `/loop` scheduling, polling for work every 15 minutes. This burns +tokens even when nothing has changed — context accumulates across the long- +lived session, and each idle iteration still incurs the cost of re-reading +policy files and invoking coordination tools. + +ClawdChan can replace parts of this pattern. Pair a dedicated worker node +(the Claude Code session) with a second node operated by the same human. +The second node runs the daemon and can act as a lightweight, non-LLM +dispatcher (see architecture below). + +**Iteration digest.** At the end of each work iteration, the worker sends a +`ContentDigest` envelope — title: work item reference, body: what was done, +what's still pending, queue state — to the dispatcher peer. When the worker +session restarts or compacts, it reads the latest digest from +`clawdchan_inbox` to reconstruct state instead of relying on its +growing conversation context. The digest is fixed-size by construction; +conversation context is not. + +**Event-driven dispatch.** Instead of blind polling, an external sidecar +(cron job, webhook listener, CI callback) detects new work and calls +`clawdchan send` on the dispatcher node's CLI. The worker's agent picks it +up on its next `clawdchan_inbox` call. This decouples "is there work?" (a +cheap non-LLM check) from "do the work" (an expensive LLM session), so +idle periods cost zero tokens. + +**Important caveat.** Claude Code is reactive — a CC session cannot be woken +from outside. ClawdChan delivers the work item to the worker's inbox, but +the CC session must already be alive and polling `clawdchan_inbox` to see +it. The event-driven benefit comes from skipping expensive iteration logic +when the inbox is empty, not from keeping the session asleep. A separate +orchestrator (systemd timer, launchd, or a supervisor daemon) is still +responsible for ensuring the CC session exists. + ## What ClawdChan is not - Not a public chat network. Pairing is explicit, no discovery. @@ -60,3 +96,6 @@ reading N threads. the human surface when hosting on OpenClaw; in Claude Code the host surface is Claude itself. - Not a file or state sync primitive. +- Not an orchestrator or scheduler. ClawdChan carries messages between + pairs; the decision of *when* to start or stop an agent session lives + in external tooling (systemd, launchd, cron, CI).