Nicholas Hopper

File handoff

A file handoff is a transfer of work between two AI agents in which the only thing passed is a file that both sides can validate. Nicholas Hopper uses file handoffs so that agents on different harnesses can share a workflow without sharing a conversation.

How Nicholas Hopper uses file handoffs

In one of Nicholas Hopper’s personal repositories, three agents on three harnesses (Grok, Claude Code and Codex) and one person share a single repository. The governing rule is one sentence: nothing moves between agents without a schema-valid file.

Each stage of the workflow writes one JSON file. A command-line tool validates that file against a JSON Schema and refuses to mark the stage done if it fails. When it passes, the tool drops a notification file in the next owner’s queue directory. The run’s state file is owned by the tool, and no agent edits it by hand.

An agent that cannot run a shell

One of the agents may have no shell access. Hopper’s fallback is that it writes its output file exactly to schema and adds a one-line handoff note. Any other agent that finds a valid but unmarked stage may advance it on the first agent’s behalf, and must say so in its commit or note.

Why a file and not a message

A file can be validated, diffed, versioned and re-read by an agent that was not present when it was written. A chat message can be none of those. Hopper’s rule that an approved artifact is never overwritten follows from this: re-running a stage writes a new version and updates the manifest.

Related skills