The waggle documentation map

July 11, 2026 · View on GitHub

Four kinds of documents live here, for four kinds of readers. Start where your question is.

Why does this exist? (the case)

WHY.mdThe cornerstone essay: how resources actually pass between agents today (the four-boundary matrix), what it costs, why provider optimizations don't transfer, the bee that inspired the design — and how the substrate works at every radius.
The essayThe inspiration essay: the waggle dance, stigmergy, and the distributed-systems lineage (tuple spaces, named-data networking, capabilities, leases, the log) — why the design is shaped this way.

How do I use it? (the guides — in reading order)

Getting started

  1. Five minutes to a first token — install, mint, resolve, hand off
  2. waggle in Claude Code — the MCP wiring, waggle init, subagent handoffs

The core moves

  1. Variants & media — one token, per-consumer projections; attachments
  2. Lifecycle & query — revoke/supersede/expire; slicing documents by path
  3. The full lifecycle, illustrated — orchestrator → subagents → back, the URI taking shape end to end

The sharp edges

  1. Surgical content access — read/search through the token: the grep travels, the artifact stays
  2. Embedding in Rust — the crates as a library

Running it

  1. waggled & federation — lifecycle verbs, two-machine setup, strict vs eventual freshness
  2. The edge — deploy to Cloudflare in 5 minutes; waggle edge status|push|smoke
  3. The edge, walked through — every command against a real account, with diagrams
  4. The tmux switchboard — window-per-harness workspaces, the live board, agent-driven screen swaps; Fable ↔ Opus, Claude → Codex with lineage, the delegation chain, coverage proof, sealed handoffs

What exactly does it promise? (the reference)

The specificationNormative (RFC-2119): token, three-zone manifest, sealed matcher, log guarantees, storage contract, trust, resolution semantics
Conformance vectorsGenerated FROM the implementation, drift-checked in CI — the portable half of the spec
COMMANDS.mdEvery operation, every argument — generated from the catalog, drift-checked in CI
PERF.mdMeasured numbers with their benchmarks: 7.4 ns resolves to 2 ms edge round-trips

How was it designed? (the design docs — the contract)

The design corpus predates the code and governs it. By concern: