Dispatch Protocol

The complete lifecycle of an aide dispatch — from task creation to memory sync.

Overview

aide dispatch <agent> "task"
  │
  ├─ 1. Create GitHub Issue (labeled with agent name)
  ├─ 2. Spawn background worker: `aide run-issue <repo>#<N>`
  │     │
  │     ├─ 3. Fetch issue body + labels from GitHub
  │     ├─ 4. Resolve agent directory from registry
  │     ├─ 5. Run task: `claude -p` with vault + budget
  │     ├─ 6. Post bounded summary as issue comment
  │     ├─ 7. Close issue (on success)
  │     ├─ 8. Sync memory to HQ
  │     └─ 9. Log telemetry
  │
  └─ Return immediately with issue ref

Step by step

1. aide dispatch — create issue

aide dispatch crossmem-rs "fix parser bug in src/lexer.rs"

What happens:

• Resolves crossmem-rs in ~/.aide/config.toml → /path/to/crossmem-rs
• Reads git remote get-url origin → crossmem/crossmem-rs
• Creates GitHub Issue via gh issue create:
  • Title: first line of task (truncated to 80 chars)
  • Body: full task wrapped in ## Task section
  • Label: agent name (crossmem-rs)
• Spawns a detached background worker: aide run-issue crossmem/crossmem-rs#42
• Returns immediately — the frontier session is not blocked

Output:

dispatched: crossmem/crossmem-rs#42
agent: crossmem-rs
budget: 250000 tokens
wait: aide wait https://github.com/crossmem/crossmem-rs/issues/42

2. aide run-issue — background worker

Runs in a separate process (stdout goes to ~/.aide/logs/dispatch-crossmem_crossmem-rs-42.log).

Steps:

1. Fetch issue — gh issue view 42 --repo crossmem/crossmem-rs --json title,body,labels
2. Resolve agent — first label = agent name → look up in registry → directory path
3. Run task — calls runner::run():
   • Parse Aidefile for budget, vault keys, hooks, workspace, output config
   • Decrypt vault secrets
   • Run on_spawn hooks
   • Wrap task with <aide-summary> instructions (forces sub-agent to emit bounded output)
   • Loop claude -p until success or budget exhausted
   • Run on_complete hooks
4. Post summary — gh issue comment with the bounded summary:

   STATUS: success
   TOKENS: 18432/250000
   RETRIES: 1
   CHANGED: src/lexer.rs, src/parser.rs
   NOTES: Fixed off-by-one in lexer token boundary detection.
   PR: none
   NEXT: none
   

5. Close issue — gh issue close (only on success)
6. Sync memory to HQ — see below
7. Log telemetry — tokens used, compression ratio, duration → SQLite + events.jsonl

3. Memory sync to HQ

After the worker posts the summary and closes the issue:

1. Check config — read hq from ~/.aide/config.toml. If not set → skip (backward compatible).
2. Read old memory — <hq>/memory/<agent>/context.md (may not exist yet)
3. Read shared memory — <hq>/memory/_shared/*.md (team-level context)
4. Distill — claude -p with a merge prompt:
   • Input: old memory + shared memory + new dispatch summary
   • Rules: merge (not append), deduplicate, remove stale info, keep concise
   • Output: updated context.md or NOTHING_NEW if nothing worth remembering
5. Write — overwrite <hq>/memory/<agent>/context.md
6. Git commit — git add memory/<agent>/ && git commit -m "memory: sync <agent> @ <timestamp>"

The HQ git log becomes the version history of agent memory:

e879c97 memory: sync crossmem-rs @ 2026-04-14 09:38
e9424c2 memory: sync crossmem-web @ 2026-04-14 09:38
40d664a memory: sync crossmem-chrome @ 2026-04-14 09:38

4. aide wait — frontier blocks on result

aide wait crossmem/crossmem-rs#42

Polls gh issue view every 5s (configurable). When the issue closes:

• Extracts the last comment (the bounded summary)
• Prints it to stdout — this is the only thing that enters the frontier session context
• Exit code: 0 (success), 1 (partial/failed), 2 (cancelled), 124 (timeout)

Cross-machine dispatch

GitHub Issues bridge machines. The dispatch and the worker don't need to be on the same host.

Machine A (your Mac):
  aide dispatch infra-guardian "check GPU queue"
  → creates GitHub Issue
  → aide wait (polls GitHub)

Machine B (formace-00):
  aide daemon polls gh issue list
  → picks up the issue
  → aide run-issue (local claude -p)
  → posts summary comment, closes issue
  → memory sync → git commit to storylens-hq

Machine A:
  aide wait returns with the summary

Requirements:

• Both machines have gh authenticated
• Both machines have the agent registered in ~/.aide/config.toml
• HQ repo is git-cloneable from both machines (push/pull for memory sync)

Issue lifecycle

Bounded summary format

The sub-agent's output is wrapped in an <aide-summary> block, enforced by prompt injection:

STATUS: success | partial | timeout | error
TOKENS: <used>/<limit>
RETRIES: <count>
CHANGED: <files> or (none)
NOTES: <one-line summary of what was done>
PR: <url> or none
NEXT: <optional redirect suggestion for coordinator>

This is controlled by [output] in the Aidefile:

• max_summary_tokens — cap on summary length (default: 500)
• narrative_schema — the template the sub-agent fills in

If the sub-agent doesn't emit the block, the runner falls back to a truncated tail of raw output.