Tell your agents

Give each agent one instruction and one handle name, so it can pick up work from the relay.

The instruction

Handsoff has one standing instruction for agents. The tool prints it, and it needs no sign-in:

$ handsoff instructions
This machine uses Handsoff, a relay for agent work. When you are asked to continue a piece
of work named in the record, run `handsoff continue <name>` first and work from what it
prints: the baton and what it refers to. Save the baton as you work with `handsoff save`.
Before you stop, offer it to the next carrier with `handsoff offer` or end your leg with
`handsoff end`. Never ask for or read an earlier session's transcript.

Where to put it

Add the instruction where each agent reads its standing instructions:

Run the command from the project folder the agent works in. >> adds to the end of the file and keeps what is already there:

$ handsoff instructions >> CLAUDE.md
$ cat CLAUDE.md
This machine uses Handsoff, a relay for agent work. When you are asked to continue a piece
of work named in the record, run `handsoff continue <name>` first and work from what it
prints: the baton and what it refers to. Save the baton as you work with `handsoff save`.
Before you stop, offer it to the next carrier with `handsoff offer` or end your leg with
`handsoff end`. Never ask for or read an earlier session's transcript.

Install the adapter

For Claude Code and Codex, the tool can do this step for you, and more. Run it with the project folder named:

$ handsoff adapter install claude-code --project .
Installed hooks and permissions in …/.claude/settings.local.json; standing instruction in …/CLAUDE.md.
Interactive sessions run no project hook until you answer yes to the folder-trust question.

The adapter does three things:

• It adds the standing instruction to CLAUDE.md.
• It adds hooks to .claude/settings.local.json. The hooks run handsoff hook claude-code at session start, before and after each tool use, before the context is compacted, at stop, when a turn fails on a limit or an error, and at session end.
• It lets the agent run these commands without a permission question: continue, save, offer, end, baton, note, renew, block, status, history and instructions.

Run it again and nothing changes. If CLAUDE.md already holds the instruction, the adapter leaves the file alone. It keeps your other settings, and it never touches your global Claude Code settings.

For Codex, name the other runtime:

$ handsoff adapter install codex --project .
Installed hooks in …/.codex/hooks.json; standing instruction in …/AGENTS.md.
Trust the folder first: answer "Trust this folder?" in the interactive runtime, or set [projects."<dir>"] trust_level = "trusted" in the CODEX_HOME a runner uses.
…

The tool prints more lines after that. Read them. They say how to trust the hooks, and which sandbox settings the agent's own handsoff commands need.

Name the handle

An agent has to say which handle it acts as. It does this with HANDSOFF_HANDLE, and then it needs no --as flag.

To try it, give review-agent a piece of work to catch. Here build-agent opens BILL-44 and offers it. You can reuse baton.md:

$ handsoff open BILL-44 --title "Export the 2025 invoices" --as build-agent --baton baton.md
Opened BILL-44 at r1 (work 3)
Leg 5; lease expires 2026-10-04T21:33:22.062211+00:00
$ handsoff offer BILL-44 --as build-agent --to review-agent
Offered BILL-44 at r1 to review-agent until 2026-10-05T21:03:22.631798+00:00
$ handsoff end BILL-44 --as build-agent --reason clean
Ended BILL-44: clean

Now catch it as review-agent. Put the variable in front of the command, and it applies to that command only:

$ HANDSOFF_HANDLE=review-agent handsoff continue BILL-44
Caught BILL-44 at r1 from build-agent via offer

Attention
Warning: References: no work reference
This machine has no pending writes.

## True now
Invoices 1 to 4800 are copied. The v2 table holds 4,800 rows and so does the old table.
…

For an agent, set the variable once in the agent's environment, with export HANDSOFF_HANDLE=review-agent. Then ask the agent: "Continue the work named BILL-44." It runs handsoff continue BILL-44 first, as the instruction says.

In Codex's default interactive mode, a variable set when a window starts does not reach the session. The text the Codex adapter prints says what to do.

A person

A person has nothing to add. You catch work with continue, as the agents do. Your own handle is the default, so you need no --as flag and no variable. Here review-agent offers BILL-42 to any handle, and you catch it:

$ handsoff offer BILL-42 --as review-agent --any
Offered BILL-42 at r3 to any until 2026-10-05T21:03:23.301219+00:00
$ handsoff end BILL-42 --as review-agent --reason clean
Ended BILL-42: clean
$ handsoff continue BILL-42
Caught BILL-42 at r3 from review-agent via offer

Attention
Warning: References: no work reference
This machine has no pending writes.

## True now
Invoices 1 to 4800 are copied. The v2 table holds 4,800 rows and so does the old table.
…

Next, read the baton. It explains how to write a baton that the next carrier can work from.