waggle: a 30-byte handoff token that replaces pasted context between agents
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.
At a glance
- What is it?
- waggle is an MCP-native Rust project that mints short, signed, resolvable references to artifacts so each agent pulls its own projection instead of receiving a pasted copy. The README is candid that a shared filesystem path is often enough, which makes the interesting question when it is not.
- Who is it for?
- Adopt waggle if your handoffs cross a machine or container boundary, if you need to prove which agent read which slice of an artifact, or if a file can change mid-task and two consumers must not see different bytes. Do not adopt it if your agents are local, your tasks are short, and no one needs an audit trail: the README itself says the path arm of its benchmark scores 90% against waggle's 96%, and calls waggle overhead in that case.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 57 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The seam waggle is aimed at: handoffs that lose context
The problem waggle names is not retrieval and not storage. It is the moment one agent hands work to another. The README states that multi-agent systems consume roughly 15 times the tokens of a chat session, and attributes that overhead to a vendor description of duplicating context across agents and summarizing results for handoffs, with the summary line that each handoff loses context. It also states that roughly 37% of multi-agent failures trace to that seam. Those numbers come from the README, not from independent measurement, and the README does not link the underlying study in the excerpt available.
The intended user is someone running an orchestrator that fans out subagents, or delegating across vendors over an open protocol. The README frames the real competitor as the instinct to write "Here's /tmp/analysis.md. Use it." and concedes that the instinct is correct about size: a path is already a 30-byte reference. What a path lacks, in the README's framing, is attribution, per-consumer adaptation, lifecycle, telemetry and reach. That list is the product.
Token, manifest, variants: the three objects behind a resolve
A token is described as a roughly 30-byte attributed name for an artifact, minted in a single call. Behind it sits an attribution manifest: who minted it, for which channel, from which parent, with variants for different consumers. The README says the manifest is Ed25519-signed when the host holds an identity, which means the signing is conditional rather than guaranteed, and you should check what happens when no identity is configured.
Variants are the per-consumer projections. When an agent resolves a token it presents its context, and a sealed, deterministic matcher returns that agent's projection. The README does not describe the matcher's rules in the excerpt, so the practical question of how a small-context model and a frontier model end up with different projections is answered only at the level of intent. Everything after resolution is an event in an append-only log, described as payload-free by construction, so counts can be aggregated without the log containing the artifact.
Delegation forms a lineage tree through the parent field. That is what makes supersede and revoke meaningful: a correction has a set of holders to travel to, and the README describes revocation propagating to every replica.
The one hard rule: the token travels, the artifact does not
Only the string enters the consumer's context. The README is explicit that the artifact never auto-expands, and that resolve, read and search return only the projection or slice the consumer asked for, under byte budgets. This is enforced by type rather than by convention, which is a stronger claim than a style guide and worth verifying in the source if you plan to depend on it.
The README's own illustration of the payoff is a result it reports from its benchmark: regions read produced 99% correct answers, regions skipped produced 20%. That result exists, per the README, only because reads go through the token, since reading a file records nothing. Treat that as the project's reported benchmark, not an independent one. The mechanism it demonstrates is real in the design: an append-only, payload-free event log can answer which subagent read its input and which stalled, and a bare path cannot.
Getting it running: one MCP config line, one binary, one SQLite file
The README describes consumption as protocol-shaped: waggle is an MCP server, wired in with one config line in Claude Code, Codex, Cursor, or anything MCP-speaking. It states there is no SDK, no language bindings and no accounts. Locally the footprint is one binary and a SQLite file.
The README's table of contents names the install section as Install, the harness wiring as Harness setup, and there are sections titled By file type, Reach, and The tmux switchboard. The excerpt does not include the literal commands or the config keys, so this review cannot give you the exact line to paste. The repository also ships docs/design/essay.md and a paper/ directory, which are the places to look for the matcher rules and the benchmark methodology the README cites. If you need the precise MCP server name and argument form before adopting, read the Install and Harness setup sections in the repository rather than any summary, including this one.
Reach is the part a path genuinely cannot do
The README splits reach into three radii and says the same token resolves unchanged across all three. A file:/// reference means nothing to an agent in another container or at the edge, and that is the strongest argument in the document. If your subagents all live on one box, the reach argument does not apply to you.
The tmux switchboard section suggests the project also targets interactive multi-agent setups on a single machine, which sits in tension with the reach pitch. That is not a contradiction so much as a sign the tool is trying to cover both the local orchestration case and the distributed one. The README does not explain, in the excerpt, how the same token is transported between radii, or what serves as the resolution endpoint when the consumer is not on the minting host. A URL, the README notes, needs a server; waggle claims to need neither. How that holds across a container boundary is the first thing to test.
Where waggle is the wrong tool, by the project's own account
The README devotes a section to the objection that subagents already share a filesystem. It concedes the point: a path is not a copy, and its benchmark's reference arm is exactly a local path plus ls, grep, open and pdftotext. That arm scores 90%, described as competitive with waggle's 96%. The README then says plainly that if your agents are local, the task is short, and you never need to audit anything, you should use the path and waggle is overhead.
That is an unusually direct limitation statement, and it should be taken at face value. The three questions the README says a location cannot answer are the actual purchase: whether it was read and which parts, which version, and reachable from where. If none of those three matters for a given pipeline, the token adds a mint call, a resolution step and an event log for no return. The 90 versus 96 gap also means the reference approach is not a strawman; it is close.
The versioning point deserves separate weight. A path names mutable bytes, so a correction mid-task can leave agent A holding the old copy and agent B the new one, with nothing distinguishing them. Waggle snapshots at mint, content-addressed and immutable, and provides supersede and revoke with lineage. If your artifacts never change during a task, that whole category of failure is absent.
What it replaces, and what the difference actually is
The obvious alternative is the plain filesystem path, and the difference is not copy versus reference. Both point at the same bytes. The difference is that a path is a location with no server-side identity, so nothing can be counted, versioned or corrected after the fact. Waggle adds an indirection layer whose whole job is to answer those questions.
The second alternative is a URL or an object-store link. The README's distinction is that a URL requires a server, while waggle claims to require neither a server nor a copy. Whether that holds depends on how resolution works when the consumer is remote, which the excerpt does not settle. The third alternative is simply pasting the artifact into each prompt, which the README treats as the default it is arguing against.
A reasonable reading is that waggle is not competing with retrieval systems or vector stores at all. It is competing with the string you type into a subagent's prompt.
Maintenance, versioning and licence
The project is licensed Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence; it is not legal advice, and if you are embedding waggle in a distributed product you should read the NOTICE and attribution requirements yourself.
The release cadence visible in the supplied material is tight: v0.5.1, v0.5.2 and v0.5.3 all landed within roughly a day of each other in mid-July 2026, with the last push to main a few days after. Pre-1.0 version numbers plus same-day patch releases usually mean the wire format and manifest schema are still moving. The README does not state a compatibility policy for tokens across versions, and since a token is meant to outlive the session that minted it, that is the maintenance question to raise before you depend on long-lived tokens. The local footprint, one binary and a SQLite file, keeps operational cost low, but the append-only log and the SQLite file are state you will have to back up and eventually migrate.
Editorial conclusion
Adopt waggle if your handoffs cross a machine or container boundary, if you need to prove which agent read which slice of an artifact, or if a file can change mid-task and two consumers must not see different bytes. Do not adopt it if your agents are local, your tasks are short, and no one needs an audit trail: the README itself says the path arm of its benchmark scores 90% against waggle's 96%, and calls waggle overhead in that case. Before committing, verify the two things the README does not fully specify: the exact contents of the attribution manifest fields it names (minted-by, channel, parent, variants), and whether the sealed deterministic matcher's variant selection rules are documented well enough that you can predict which projection a given consumer receives.
Community notes