tap’s File-First Protocol for Claude–Codex Collaboration: Architecture, Evidence, and Limits

Running one coding agent as the implementer and another as the reviewer sounds straightforward until the tools live in separate terminals, use different configuration formats, and forget one another’s state. tap addresses that coordination problem with a deliberately modest contract: messages become files, notifications point back to those files, and each agent works in its own Git worktree.

That design is more interesting than another “AI team” demo because it treats reliability as a software-engineering problem. The protocol does not claim to make Claude, Codex, or Gemini smarter. It tries to make their handoffs durable, inspectable, and recoverable.

The evidence is promising but bounded. In its June 2026 paper, tap reports 27 days of self-application, 37 agent generations, 209 merged tap-related pull requests, and 717 operational artifacts. Its heterogeneous review pairs recorded at least one defect or requested change more often than homogeneous pairs. Those figures describe one evolving repository and one operational setup; they do not establish that mixed-model review is inherently superior.

This article explains what tap actually contributes, what its data supports, and what a team should verify before adopting it.

The core idea: preserve state before sending a signal

Many agent integrations start with a transport: a socket, message queue, callback, or shared chat service. tap starts with the durable record instead.

When an agent calls tap_reply, the protocol first writes a Markdown message with YAML metadata into an inbox/ directory. That file is the canonical message. A faster delivery mechanism may then alert the recipient, but the alert is not the source of truth. The receiving agent rereads the file before acting.

This ordering creates a useful invariant:

A notification may disappear, but the state needed to recover must already exist.

If a WebSocket disconnects, an MCP notification is missed, or an agent process restarts, the failure becomes a delay rather than immediate message loss. A replacement agent can inspect the same inbox and operational records without reconstructing the conversation from someone’s terminal scrollback.

The architecture has three separable responsibilities:

1. Durable communication: Markdown plus metadata records the original message.
2. Low-latency notification: runtime-specific channels tell an agent that new work exists.
3. Workspace isolation: Git worktrees keep concurrent edits out of one shared working directory.

Keeping these responsibilities separate is the protocol’s strongest idea. It avoids pretending that delivery, memory, and code isolation are one problem.

Two delivery tiers, with different guarantees

tap describes file inspection as Tier 1 and real-time notification as Tier 2.

Tier 1 provides the evidence trail. An agent or operator can list messages, inspect metadata, retry an unprocessed handoff, and perform a postmortem. This is also the path available to runtimes without a dedicated live adapter.

Tier 2 reduces waiting. In the paper’s reported configuration, Claude received channel-style MCP notifications and Codex used a delivery program over WebSocket. The notification tells the recipient to inspect the durable record; it does not replace that record.

This is close to a familiar distributed-systems pattern: store the state transition first, then emit a best-effort signal. But tap should not be mistaken for a transactional message broker. A local filesystem alone does not automatically provide exactly-once processing, global ordering, access control, replication, or safe multi-host consensus. Teams still need to define idempotency, ownership, retention, and recovery procedures.

Standardize configuration, not every runtime

Claude, Codex, and other coding agents expose different integration surfaces. The paper’s version of tap handled that mismatch through a common setup procedure: inspect the environment, plan changes, apply runtime-specific configuration, and verify the result. Claude might require .mcp.json; Codex might require config.toml; another client may need a different JSON file.

The important abstraction is therefore not “one universal agent API.” It is a repeatable configuration lifecycle with per-runtime adapters.

There is also meaningful version drift between the paper and the software available today. The paper records @hua-labs/tap v0.5.2. As of July 16, 2026, the npm registry lists v0.6.1, and the official repository labels the 0.6 line an “advanced operator preview.” Its public workflow is now dry-run-first:

npx @hua-labs/tap setup --profile codex-cli --dry-run --json
npx @hua-labs/tap setup --profile codex-cli --apply --json
npx @hua-labs/tap doctor --setup --profile codex-cli --json

The current README also says Codex App/Desktop live delivery is experimental and strictly gated by runtime health and route freshness, while Gemini CLI support is legacy/deprecated in that release line. Anyone evaluating tap should follow the installed version’s documentation rather than copying commands from the paper or an older article.

Git worktrees reduce collisions—but do not merge the work

Giving multiple autonomous processes write access to one checkout is an invitation to corrupt intermediate state. tap assigns agents separate Git worktrees and separates process IDs, logs, and state by instance identifier.

That is a sensible reuse of Git’s existing isolation model. An implementer can modify one branch while a reviewer examines another directory without both tools racing over the same index and uncommitted files.

Worktrees do not eliminate coordination costs. Branches can still diverge, generated files can conflict, migrations can be incompatible, and an agent can commit secrets or destructive changes. A production workflow still needs:

• explicit branch ownership and merge authority;
• tests that run against the integration target, not only an agent branch;
• protected paths and secret scanning;
• a human or trusted policy gate for merging into the default branch;
• cleanup rules for stale worktrees and orphaned processes.

In other words, worktrees isolate the editing surface. They do not decide which changes are correct.

Files as external operational memory

The paper groups reviews, findings, retrospectives, and handoffs as operational artifacts. These records let a new agent generation recover decisions after a previous session ends or reaches its context limit.

This is better understood as external memory than model memory. The system is not preserving a hidden internal state. It is preserving explicit, inspectable artifacts that a later agent can read.

That distinction has practical benefits. Operators can review why a change was requested, identify repeated failures, and separate a current task from the accumulated narrative of the project. But file-backed memory also needs governance. Without schemas, retention limits, and summarization, the archive can become a second codebase full of stale instructions and contradictory decisions.

A robust deployment should attach at least four fields to important artifacts: the originating task or commit, authoring agent and runtime, creation time, and current disposition. Superseded decisions should remain traceable but clearly marked as obsolete.

What the 27-day self-application run demonstrated

The reported operation is useful because it lasted longer than a staged demo and generated concrete failure records. At commit 563d859c, dated April 15, 2026 in the paper, the project reported:

• 27 days of operation;
• 37 agent generations;
• 209 merged tap-related pull requests;
• 104 package source files with 26,404 lines of code;
• 76 test files with 19,406 lines of code;
• 717 operational artifacts;
• real-time paths for Claude and Codex, with experimental MCP polling for the generic path.

These numbers support a narrow but valuable claim: the file-first protocol was used to coordinate real development and review activity over multiple agent turnovers. They do not show how tap compares with alternative orchestration systems on cost, latency, correctness, or operator workload.

The paper also notes that humans intervened frequently during early message delivery and progress checks. Later direct delivery improved, but major decisions and final approval remained with the operator. That is not a weakness to hide; it is an important description of the actual control boundary.

Operational failures became protocol changes

The self-application run surfaced ordinary infrastructure defects: a Windows path-prefix problem that caused a CLI hang, a bridge log path that produced zero-byte logs, and an agent-name collision that misdelivered messages. The reported fixes normalized the working directory, separated logs per instance, and introduced canonical names.

This is a good example of why observability belongs in the protocol. A failed handoff should leave enough evidence to distinguish “the reviewer disagreed,” “the reviewer never received the task,” and “the bridge delivered it to the wrong instance.” Treating all three as an agent-quality problem would lead to the wrong fix.

The review-rate result is a signal, not a winner’s podium

Across 375 review and re-review artifacts, heterogeneous model pairs recorded at least one defect or requested change in 183 of 262 artifacts, or 69.8%. Homogeneous pairs did so in 60 of 113 artifacts, or 53.1%.

The distinction in that caption matters. A review with one minor requested change and a review with several critical defects both count as positive. Re-reviews of the same pull request may be counted more than once. The assignment was not randomized, and 245 of the artifacts were Codex reviewing Claude-authored work. Later Codex reviewers often ran headlessly on a separate Linux server, so model identity, reviewer role, time, operating system, and execution environment are entangled.

The paper itself acknowledges these limitations. It also manually identified 12 security or security-adjacent cases, including six candidates for runtime vulnerabilities, but correctly avoids turning that small set into a quantitative claim about security-review superiority.

The defensible conclusion is therefore modest: in this operation, mixed model-and-environment review produced a broader pattern of requested changes. A stronger causal test would give the same pull requests to balanced reviewer pairs, randomize assignment, deduplicate re-reviews, grade severity, and measure accepted fixes as well as comments.

A practical adoption checklist

Before using tap—or any file-based agent protocol—in a production repository, validate the operating model rather than only the happy-path demo:

1. Define the canonical record. Specify when a message is considered written, acknowledged, processed, and superseded.
2. Make handlers idempotent. A recovered or polled message may be observed more than once.
3. Separate notification health from task state. A green socket does not prove a task was processed; a broken socket does not prove the task was lost.
4. Protect the shared directory. Agent messages can contain repository context, commands, findings, and potentially secrets. Apply least-privilege filesystem permissions and keep the directory out of unintended publication paths.
5. Review generated configuration. Use the current release’s dry-run plan, inspect every proposed change, and verify runtime readiness afterward.
6. Constrain worktrees. Give agents scoped branches and tools, then require tests and an approval gate before integration.
7. Measure operator load. Count retries, manual routing interventions, stale routes, and recovery time—not only pull requests and review comments.
8. Plan for version drift. The paper’s v0.5.2 architecture and the current 0.6.x preview are related but not operationally identical.

The real value is a cleaner human control boundary

tap’s most credible promise is not autonomous software development. It is reducing the amount of fragile, low-value state copying required to coordinate heterogeneous tools.

Files provide durable evidence. Notifications reduce latency. Worktrees isolate edits. Operational artifacts let replacement agents inherit explicit context. Humans still decide direction, approve risky changes, and authorize the final merge.

That division of labor is less dramatic than an “AI engineering team,” but it is much closer to a system that can be inspected and improved. The next step for tap is not a louder autonomy claim. It is broader, controlled validation across repositories, balanced reviewer assignments, and measurable recovery behavior under failure.

Sources

• Minseo Kim, “tap: A File-Based Protocol for Heterogeneous LLM Agent Collaboration”, arXiv:2606.14445, June 2026.
• HUA-Labs/tap official repository, current release documentation and preview-status notes.
• @hua-labs/tap on npm, current package version and metadata.
• 七牛开发者, original WeChat article (Chinese), used as the source-image sequence and as a secondary explanation of the paper.