Handover between sessions

When a Claude Code session gets long, your agent can save notes for its next session in the same folder. You start the fresh session yourself; it picks the notes up on its own.

How it works

1. Your agent saves its notes with the handover_put tool: the goal, the branch and its state, what it found, what failed, the next step and how to check it. You can also save notes yourself with hawl handover write.
2. Hawl answers "stored" with a revision number once Hawl has the notes.
3. You type /clear, or open a new Claude Code session in the same folder.
4. The new session starts with one line: "A handover is waiting. Call handover_get." It calls handover_get and reads the notes. Who sees that line is explained under "When the line shows".

Step 3 is yours unless you turn on automatic handover (below) for the folder.

Automatic handover

With automatic handover on, your Claude Code agent types the /clear itself after it saved its notes. It is off by default, per folder and per machine.

Terminals differ, so your own agent sets it up and proves it works:

1. Run hawl handover setup in the folder. It prints a prompt.
2. Paste the prompt to your agent. It finds which terminal it runs in, saves the matching clear command with hawl handover config --on, and runs hawl handover test.
3. The test types a harmless plain-text marker (hawl-handover-test-…) into the agent's terminal and sends it as an ordinary prompt. When Hawl sees it arrive, the agent tells you PASSED. This causes one short extra agent turn: the agent replies ok (or nothing) and carries on. Nothing is cleared by the test.

From then on, a handover ends with hawl handover write (or handover_put) and then hawl handover clear as the agent's very last step. The clear step waits until that Claude Code session's turn has ended (its Stop hook, up to 2 minutes; another session in the same folder does not count), then 1.5 seconds more, then types /clear into the agent's own terminal. It only ever types /clear; any other text is refused. If a new turn starts first, or the turn does not end in time, it types nothing. On Windows it also reads the screen first and types nothing while a dialog is open (a permission prompt, "Enter to confirm", "Esc to cancel").

What each terminal supports:

• tmux: tmux send-keys into the agent's own pane. Tested in a real pane.
• WezTerm: wezterm cli send-text. The command comes from WezTerm's docs; it has not been run in WezTerm yet.
• kitty: kitten @ send-text, with allow_remote_control and listen_on in kitty.conf. From kitty's docs; not run in kitty yet.
• iTerm2: an AppleScript write text to the agent's own session; macOS may ask to allow automation. From iTerm2's docs; not run in iTerm2 yet.
• Windows: Windows Terminal, Git Bash's window (mintty), the VS Code terminal and plain consoles. Hawl's own step [["hawl:windows-console","{text}"]] writes the keys straight into the console Claude Code reads from. It finds that console from the process tree (the nearest claude.exe above the command, which Claude Code 2.x runs for both the native and the npm install) and refuses when there is none. Tested with real Claude Code 2.1.301 in a plain Windows console (conhost), Git Bash's window (mintty) and Windows Terminal; the VS Code terminal is untested (it uses the same pseudo console as Windows Terminal, but was not run). mintty needs Claude Code to run on a console there (Git for Windows' pseudo console support).
• The VS Code terminal on macOS or Linux: no program can type into it from outside today. Writing and picking up handovers still work; you type /clear yourself.
• Codex: not supported. Codex blocks /clear while a task runs, so automatic handover is for Claude Code only.

Whatever the terminal, hawl handover test must pass in it before hawl handover clear types anything.

What keeps it safe

• The only text Hawl ever types is the fixed /clear (or the test marker). Your notes, other agents' messages and anything from the relay never reach the clear command.
• The clear command is a list of program arguments run without a shell. It may only use {text} and these terminal variables: TMUX, TMUX_PANE, WEZTERM_PANE, KITTY_WINDOW_ID, KITTY_LISTEN_ON, ITERM_SESSION_ID, TERM_PROGRAM, WT_SESSION. Anything else is refused.
• It aims at the terminal named by the agent's own environment, so it cannot reach another window or pane.
• It runs once per saved handover. A second hawl handover clear for the same notes does nothing and says so.
• hawl handover clear refuses, and types nothing, unless automatic handover is on, the clear command passed hawl handover test since it last changed, the notes were stored, and the terminal variables it needs are present.
• Any change to the clear command, or turning it off and on, needs a new test. A failed or interrupted test turns automatic handover off.
• The setting lives in Hawl's folder on your machine, not in the project, so a repository cannot ship one.

Turn it off with hawl handover config --off. hawl handover status shows whether it is on and when it last passed its test.

For example, the tmux clear command is:

[["tmux","send-keys","-t","${TMUX_PANE}","{text}","Enter"]]

When the line shows

The line shows only when the session starts fresh (a new session, after /clear, or after the context was compacted) and the notes are still unread. A resumed session does not get it. Once handover_get has read the notes, the line stops.

The line is meant for the session that saved the notes. Other sessions in the same folder do not get it while that session is still open, so a long session that compacts does not pick up notes meant for another. A fresh session gets the line when the session that saved the notes is closed, or when you saved the notes yourself from a plain shell with hawl handover write. Any session can still read the notes by asking its agent to call handover_get.

One handover per agent: saving again replaces the earlier notes.

Safety

• The notes go through the same security scan as every message. Notes the scan stops are not stored. Leave secrets and tokens out.
• At most 20000 characters.
• The session-start line is always the same fixed sentence. The notes themselves reach the agent only when it asks for them with handover_get.

From the command line

hawl handover write Goal: finish the import. Next step: run the tests.
hawl handover write --file notes.md
hawl handover status
hawl handover setup
hawl handover config --on --template-file clear.json
hawl handover test
hawl handover clear

hawl handover status says whether a handover is waiting and shows the last one this machine saved. On Windows, use --file or pipe the text in when it holds quotes, % or &, so the shell does not change it.

Handover needs a site: it is not available in hawl local.