# modiqo/waggle: an MCP handoff token for agent harnesses

> waggle turns a pasted artifact into a roughly 30-byte attributed token that each consuming agent resolves into its own projection. It is for teams already running multi-agent harnesses who need read accounting, versioning and reach across machines.

**modiqo/waggle** — Attributed, resolvable artifact references for agent handoffs — a ~30-byte token instead of pasted context. MCP-native; the reference layer for the agent-harness world.

- Repository: https://github.com/modiqo/waggle
- Website: https://waggle.sh
- Stars: 648 · Forks: 69
- Language: Rust
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/modiqo-waggle

## The handoff seam waggle is aimed at

The README frames the problem as the seam between agents, not the agents themselves. When an orchestrator fans out subagents, the usual move is to paste the plan or the artifact into every prompt. The README attributes a figure of roughly 15x token consumption for multi-agent systems versus a chat session to the vendor's own description of "duplicating context across agents... and summarizing results for handoffs," and states that about 37% of multi-agent failures trace to that seam. Those numbers are the project's framing, not an independent measurement.

The target user is someone running Claude Code orchestrators, Codex sessions or cross-vendor agents that discover each other over open protocols. The README is explicit that the competitor is not another protocol. It is a line like "Here's /tmp/analysis.md. Use it." A path is already a small reference, and the README concedes that instinct is correct. What a path lacks, in its account, is attribution, per-consumer adaptation, lifecycle, telemetry and reach past the machine boundary. Whether you need those five things is the actual adoption question.

## Token, manifest, matcher and append-only log

A token is described as a roughly 30-byte attributed name for an artifact, minted in one call. Behind it sits an attribution manifest recording who minted it, for which channel, and from which parent, so delegation forms a lineage tree. The README states the manifest is Ed25519-signed when the host holds an identity, which means attribution is only cryptographic when an identity is configured; otherwise it is a record, not a proof.

The mechanism that makes per-consumer shaping work is a sealed, deterministic matcher. An agent resolving a token presents its context, and the matcher returns that consumer's projection from the variants stored with the manifest. The README's one hard rule is enforced by type: the token travels, the artifact never auto-expands, and resolve, read and search return only the projection or slice requested, under byte budgets. Everything after the mint is an event in an append-only log that is payload-free by construction, so funnel counts exist without the log holding your data.

The architecture is visible in the workspace layout. Cargo.toml declares a workspace over crates/*, edge-worker, xtask and bench, with named crates for core, tree, ops, agent, social, store and store-sqlite. Rust 1.85 is the declared minimum. The README says the local shape is one binary and a SQLite file, which matches the rusqlite dependency with the bundled feature in the workspace manifest.

## Installing waggle and minting a first token

The README points at the install section of its own page and at waggle.sh; the checkout also carries a justfile whose dev-install recipe builds the CLI from source. That recipe runs cargo install against the CLI crate with --locked and --force, then attempts a daemon restart. Run it from the repository root.

```bash
just dev-install
```

The same result without just is the cargo command underneath it.

```bash
cargo install --path crates/waggle-cli --locked --force
```

The README says consumption is protocol-shaped: waggle is an MCP server, and wiring it into Claude Code, Codex, Cursor or anything MCP-speaking takes one config line, with no SDK, no language bindings and no accounts. The README does not print that line, so take the exact server entry from the harness setup section of the project's own documentation rather than guessing at keys. With the server registered, the first real use is the sequence the README describes: mint a token for an artifact, hand the token to a subagent, and let that subagent resolve it. The reader should see a short token string in the orchestrator's context and the resolved projection in the consumer's, not the artifact itself.

There is also a full-lifecycle demo that the justfile runs against a throwaway store.

```bash
just demo
```

That recipe calls scripts/demo.sh, which the justfile comment ties to guide document 06. It is the cheapest way to see mint, resolve and the log without touching a real store.

## Where a shared filesystem already wins

The README argues against its own product in one section, and that section is the most useful part of the page. If subagents share a filesystem, a path is already share-by-reference. The project's benchmark includes a reference arm that is exactly a local path plus ls, grep, open and pdftotext, and the README reports that arm scoring 90% against waggle's 96%. Those are the project's own numbers for its own benchmark, and the README's conclusion is blunt: if your agents are local, the task is short, and you never need to audit anything, use the path, because waggle is overhead.

The three questions a path cannot answer are the real boundary. First, reads: reading a file records nothing, so the check of whether a subagent actually read its input is impossible with a bare path rather than merely inconvenient. The README cites a result where regions that were read produced 99% correct downstream work and skipped regions produced 20%, and notes that result exists only because reads go through the token. Second, version: a path names mutable bytes, so a mid-task correction leaves one agent on the old copy and another on the new one with nothing to distinguish them. Waggle snapshots at mint, content-addressed and immutable, and offers supersede and revoke with lineage. Third, reach: a file URL means nothing to an agent in another container or at the edge, while the README states the same token resolves unchanged across all three radii.

So the failure mode is not that waggle breaks. It is that on a single machine with a short task, you pay a store, a daemon and a protocol hop for accounting you never query.

## Reach, the edge worker and the tmux switchboard

Reach is where waggle diverges most from a path, and it is also where the operational surface grows. The workspace includes an edge-worker member, and the justfile's edge-test recipe boots wrangler dev on port 43811, deletes edge-worker/.wrangler/state for a fresh hive on each run, and provisions a dev tenant token in the gitignored edge-worker/.dev.vars if one is missing. It then waits on the /health endpoint before running the Miniflare test suite with WAGGLE_EDGE_TESTS=1 and WAGGLE_EDGE_EXTERNAL_PORT set to that port. The recipe comments note that Durable Object storage persists, which is why the state directory is wiped per run.

That recipe is a fair picture of the cost of the reach feature. A local-only deployment never touches wrangler, node or a tenant token. The moment you want the third radius, you are running an edge worker with its own secret slot and its own persistence semantics. The README also mentions a tmux switchboard in its navigation, which suggests a way to drive several agent sessions from one place, but the excerpt does not describe its behaviour, so treat that as something to read up on rather than assume.

## Alternatives and the difference in approach

The honest alternative is the one the README names: a shared filesystem with a path plus ordinary shell tools. The difference is not copy versus reference, since both point at the same bytes. It is that a location cannot report reads, cannot distinguish versions after a correction, and stops at the machine boundary. If none of those three matter for your workload, the path wins on setup cost and on the number of moving parts.

A second alternative is a plain URL to an internal artifact service. The README's objection is that a URL needs a server, while a token needs neither a server nor a path. That is only partly true in practice: the local shape is a binary and a SQLite file, but the cross-machine shape involves the edge worker. If you already run an artifact service with authentication and audit logs, you may be duplicating capability by adding waggle, and the README does not compare itself to that case.

A third option is to keep pasting context and accept the token cost. The README's whole argument is that this is what everyone does today and that it loses context at each hop, but pasting has one property no reference layer has: it always works, with no store to lose and no daemon to be down.

## Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-07-20, and the most recent release in the list is v0.5.3 from 2026-07-14, with v0.5.2 and v0.5.1 arriving the day before. That is a project publishing patch releases in quick succession, which is normal for a 0.x line and also a signal that the surface is still moving. The workspace version and the crate versions are pinned together at 0.5.3, so upgrading one waggle crate means upgrading the family.

The licence situation needs a careful read rather than a summary. The repository carries both LICENSE-APACHE and LICENSE-MIT, and the workspace manifest declares license = "MIT OR Apache-2.0". The repository metadata supplied for this page lists Apache-2.0 alone, so the two sources disagree on scope. If you redistribute waggle or ship it inside a product, read both licence files in the checkout and confirm which terms you are relying on. That is a factual discrepancy to resolve, not a legal question I can settle here.

Upgrade cost is dominated by the store. The local shape is a SQLite file, and the README does not document rollback or store migration between versions. The justfile's release path is tag-driven, publishing binaries, a Homebrew formula and the crates together, which means a version bump is easy to pull and hard to reverse if the store format moved. Back up the SQLite file before upgrading. For a first evaluation, run the demo against a throwaway store so nothing you care about is in the path of a version change.

## Conclusion

Adopt waggle if your agents already cross machine or container boundaries, or if you need to prove which subagent read which slice of an artifact after the file changed. Do not adopt it for a single local agent on a short task: the README says the path arm of its own benchmark is competitive and that waggle is overhead in that case. Before wiring it in, check that your MCP client can hold a server config, confirm where the SQLite store lives and how it is backed up, and read COMMANDS.md for the mint, resolve, supersede and revoke verbs, since the README does not document rollback or store migration.

## FAQ

### How do you use modiqo/waggle with an agent harness?

The README says waggle is an MCP server, so consumption is one config line in Claude Code, Codex, Cursor or anything MCP-speaking, with no SDK, language bindings or accounts. After that you mint a token for an artifact and hand the token to the consumer, which resolves it into its own projection.

### How do you set up modiqo/waggle from a checkout?

The justfile's dev-install recipe runs cargo install against the CLI crate with --locked and --force, then attempts a daemon restart. The same command can be run directly as cargo install --path crates/waggle-cli --locked --force from the repository root.

### What is modiqo/waggle?

It is an MCP-native reference layer for agent handoffs. A roughly 30-byte attributed token stands in for pasted context, and resolving it returns the projection or slice the consumer asked for under byte budgets, with every read recorded as an event in an append-only, payload-free log.

## Sources

- [License: Apache-2.0](https://github.com/modiqo/waggle/blob/main/LICENSE)
- [modiqo/waggle on GitHub](https://github.com/modiqo/waggle)
- [Project website](https://waggle.sh)
- [README](https://github.com/modiqo/waggle/blob/main/README.md)
- [Releases](https://github.com/modiqo/waggle/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/modiqo-waggle