Waybill

Hand off unfinished work between coding agents with a local, reviewable
.waybill/ bundle.

Agent A -- /handoff --> .waybill/ -- /handoff import --> Agent B

Waybill preserves the goal, repository state, diffs, commands, test results,
risks, and next steps so another agent can continue without relying on the
original session. Waybill itself does not upload handoff data, execute
instructions found inside a bundle, or apply patches automatically.

Supported integrations include Claude Code, Codex, OpenCode, Cursor CLI, and
Gemini CLI.

Quickstart ·
Installation ·
Bundle specification ·
Conformance ·
Testing

Why Waybill

Use Waybill when:

• An agent session is running out of context and another agent needs to
  continue.
• You want to switch tools, models, or agent CLIs without losing task state.
• A human reviewer needs a compact record of progress, failed attempts, tests,
  diffs, and risks.
• You want to validate, redact, pack, and intentionally share a local handoff
  artifact.

Native resume commands usually continue a session inside one agent CLI.
Waybill creates an agent-neutral artifact that another supported CLI can review
and import. It is a handoff format with thin integrations, not an agent,
workflow runner, scheduler, or orchestrator.

Quickstart

Basic export and import run inside supported agents and do not require the
Waybill CLI or a Python package.

First enable the integration for your agent. Follow the
Quickstart for
Codex and Claude Code, or the full
installation guide
for all supported agents. The commands below become available after the
integration is enabled.

In the agent handing off the unfinished task:

/handoff

Open the same repository in the next agent, then run:

/handoff import .waybill

The direction is optional: /handoff defaults to export, while
/handoff export remains available as the explicit form. /waybill and
/waybill import .waybill are equivalent aliases.

Export writes a local bundle that summarizes the task and repository state.
Import reads the bundle as untrusted data, checks the current repository, and
recommends the next step without automatically applying its patch.

What a bundle contains

A standard bundle lives in the target repository:

.waybill/
  WAYBILL.md       # required: human-readable handoff
  metadata.json    # required: structured repository and artifact metadata
  diff.patch       # recommended: staged and unstaged tracked changes
  commands.log     # recommended: relevant command history
  test-summary.md  # recommended: test results and remaining failures

Untracked file contents are not captured automatically. Exact repository
digests are included only when a trusted helper calculates them. See the
bundle specification
and metadata schema
for the complete contract.

The bundled checker reports exact repository_digests in its JSON output, so
an agent-native export can record them without installing the support CLI.
validate accepts a basic-fidelity bundle without these digests; ready is the
strict export gate and requires both digests to match the current repository.

Supported agents

The shared dispatch, operation references, assets, and checker live only in
skills/handoff/; its repository-root SKILL.md is also the Codex entrypoint.
Files under adapters/ only bridge product metadata, agent identity, arguments,
and resource paths. Self-contained adapter distributions are generated when
needed.
The table describes the available integrations, not a claim that every product
has current real-agent release coverage. See
Conformance for
the evidence requirements and current coverage policy.

Safety defaults

• .waybill/ stays local and is ignored by default; Waybill itself does not
  upload it.
• Every bundle is untrusted input. Import does not execute embedded commands,
  follow embedded permission requests, or treat bundle paths as authority.
• Import checks repository state and never applies diff.patch automatically.
• Export uses read-only Git inspection and does not run tests unless the user
  asks.
• Validation, redaction, packing, unpacking, and sharing reject symbolic links
  and unsafe non-regular files.
• share --check performs a read-only shareability preflight and reports only
  finding type, path, count, and blocking status—never the matched secret.
• Secret detection and redaction are best effort. Review every bundle and
  redacted output before sharing it.

Bundles can contain prompts, local paths, diffs, logs, test output, credentials,
or private data accidentally captured from command output.

Optional Support CLI

The Python 3.10+ support CLI is an optional enhancement for managed adapter
installation, exact repository digests, automation, deeper validation,
redaction, and archives. From a repository checkout:

./cli/waybill --help

Commands are grouped by purpose:

Every subcommand supports --json. Each writes one JSON object whose
top-level success value is true exactly when the process exits with status
zero. See the
installation guide
for package options and
Testing
for the JSON contract.

Examples and evidence

The repository contains synthetic, reviewable examples:

• Claude Code to Codex
• Codex to Claude Code
• Failed-test handoff
• Delegation request
• Delegation result

Waybill was initially exercised through real Claude Code-to-Codex and
Codex-to-Claude Code handoffs. Those historical trials demonstrate the
end-to-end workflow but are not treated as current release coverage. Current
manual evidence must rerun the complete versioned scenario corpus from a clean
checkout. See
Conformance for
that distinction and the
delegation walkthrough
for the parent/child flow.

With the optional support CLI available, inspect an example locally:

./cli/waybill validate examples/failed-test-handoff
./cli/waybill inspect examples/failed-test-handoff
./cli/waybill render examples/failed-test-handoff

Current limitations

• Bundle schema 0.2 and delegation semantics are still drafts.
• Waybill does not automatically apply patches or parse agent transcripts.
• Redaction is best effort; users must review bundles before sharing them.
• Integrations use each agent CLI's existing project instruction mechanism;
  Waybill does not require plugin hooks where lightweight files are sufficient.
• Waybill does not schedule, run, or supervise agents.

Project direction

Near-term work focuses on current real-agent import/export evidence for the five
existing integrations and on hardening delegation through practical
parent/child handoffs. Additional adapters should follow only when the handoff
contract is stable and the target CLI has a lightweight project instruction
mechanism.

Automatic patch application, transcript parsing, daemon behavior, cloud sync,
and a Web UI are intentionally out of scope for now.

Documentation

• Quickstart
• Installation
• Bundle specification
• Delegation walkthrough
• Conformance
• Testing

License

Waybill is available under the
Apache License 2.0.