measure & optimize token use

[vMaroon]

From manual testing, token use seems to be moderate, but profiling & optimizing is a major northstar.
Innovation like compact agent-to-agent communication and languages can be helpful here.

[clubanderson]

Token optimization analysis from a supervised-agent operator

I run kubestellar/supervised-agent with Claude Code in a 24/7 /loop configuration. After profiling my token spend, I burned through a weekly budget in 4 days (~1.75× overspend). Here is what I found and how ClawdChan's existing primitives could help.

Root causes of token burn in supervised-agent setups

Factor	Impact	Detail
No context compaction	unbounded	One long-lived CC session runs for 7 days. Context grows linearly — day-4 iterations cost 3–5× day-1
Blind polling	96×/day	/loop 15m fires every 15 minutes even when nothing has changed
Policy re-read	~5 KB/iter	The full policy markdown is re-ingested every iteration
Coordination tool calls	+5–10/iter	Multi-agent beads (bd) commands add tool-call overhead per iteration
Model choice	~1.35×	Opus 4.7's tokenizer inflates code/structured data by up to 35% vs 4.6

The compounding effect is the killer: without compaction, each iteration ships the entire conversation history as context. By day 4, you're paying for days of accumulated tool outputs on every API call.

Where ClawdChan already helps

Two existing primitives map directly to the two biggest cost drivers:

1. ContentDigest envelopes → break context accumulation. At the end of each work iteration, the agent sends a fixed-size ContentDigest (title: work-item ref, body: what was done + pending queue) to a paired dispatcher node. On the next iteration (or after /compact), it reads the digest from clawdchan_inbox instead of relying on its growing conversation history. The digest is bounded by construction; conversation context is not.

2. Terse inbox responses → cheap idle checks. clawdchan_inbox returns {next_cursor, new: 0} when there's nothing new. That's a minimal-context tool response compared to re-scanning GitHub's API, re-reading the beads ledger, and re-parsing the policy file on every iteration. An agent can check inbox first and skip all the expensive logic when the queue is empty.

What ClawdChan cannot do (important caveat)

CC is reactive — a CC session cannot be woken from outside. ClawdChan delivers work items to the inbox, but the CC session must already be alive and polling to see them. The "event-driven wake" benefit comes from skipping expensive iteration logic when the inbox is empty, not from keeping the session asleep. A separate orchestrator (systemd, launchd, cron) is still responsible for the session lifecycle.

Concrete suggestions for #51

• Measure tool-response sizes. The inbox's terse {next_cursor, new: 0} pattern is great. Worth auditing clawdchan_toolkit and clawdchan_pair for similar opportunities — every byte of tool output stays in CC's context until compaction.
• include=headers mode on inbox is already excellent. Document it more prominently as the "lean polling" primitive for long-running sessions.
• Consider a notes_seen=true default after first call. The usage notes in inbox responses are helpful on first use but add context on every subsequent poll. Auto-suppressing after the first call would save tokens on every iteration.

I opened #53 with a use-case doc addition showing the supervised-agent pattern. Happy to iterate on it.