LESS REPEATING. MORE PICKING UP.
New session.
Same momentum.
Your agent stopped halfway through. The next one should know what’s done, what’s left, and where to start.
Handoff keeps that context in one file in your repository.
Let’s take a small task all the way to your first handoff.
One task. A clear next step.
Document the main folders
Verify every listed path
The conversation ends. The record stays.
Release 1.25.0 complete and verified. Handed off to Viracocha for repository monitoring.
Standing by. Listening for task assignments or channel broadcasts...
[server exited] before halting.[server exited]
figure out what went wrong here
Private list of what I need:
1. Which viewer copy ran and what version it is.
2. Where plain codex resolves, and whether it starts.
3. Which PATH the wrapper builds for Codex.
4. Bragi 3's ledger entry on the Codex launch issue.
5. A ledger entry for this investigation, recorded before I dig in.
/upgrade to increase your usage limit.
Verified
[ui.status_line] type = "command" configuration hook.Handoff bar cached row returns instantaneous exit status 0 without spawning heavy subprocesses.
✓ Atomic lock check passed via
fcntl.flock
Terminal keeps its columns — swipe it sideways to read the full width.
Meet Your Multi-Agent Team
Give your agent the skill.
Use an existing Git repository you can edit. You’ll need your coding agent and Git; the helper and dashboard also need Python 3.9 or newer.
npx skills add divijshrivastava/handoff-skill --skill handoff -gThis uses the skills CLI and requires Node.js/npm. Select your agent in the installer, then open a new agent session in your project. The -g flag makes the skill available across projects.
Already installed, or prefer a plugin?
You can skip this command if your agent already has Handoff. Claude Code’s plugin commands are available above; Cursor also supports marketplace installation. A copied skill folder works too. Restart or reload the agent after installation.
In the new agent session, ask: “Can you find the installed handoff skill and read its instructions?” It should find SKILL.md. If it cannot, finish installation before going on.
Make the work visible.
First, open your agent in the repository you want to work on. Send this as a message to the agent, not as a shell command.
Initialise the handoff.This creates HANDOFF.md when needed, or audits the one already there. Initialising does not start a task. Now give the agent something small and concrete:
Use handoff. Create a short PROJECT_MAP.md describing this repository's main folders. Check every listed path against the repository, then record the verification result. If PROJECT_MAP.md already exists, review and improve it instead.Open HANDOFF.md in your editor. Before implementation, the task should have an owner, In progress checked, and steps for the work and verification. Once the paths are checked, the entry should record that evidence and completion.
Already have unfinished work? The agent audits it and may ask which task should go first. Give it that ordering. An existing ledger automatically activates Handoff in later sessions.
A checkbox is a clue.
The evidence tells the story.
Imagine the agent wrote the project map, then stopped before checking the paths. Explore the three moments below to see what the next agent inherits.
Write a project map
1 taskWrite PROJECT_MAP.md
Verify each path exists
Task recorded before editing. Next: inspect the repository and write the map.
A name alone is not progress. The task entry makes the planned work visible.
Your turn
The document exists, but verification is unchecked. What should the next agent do first?
Choose an answer to check your understanding.
How do the ledger checkboxes work?
| State | In progress | Completed |
|---|---|---|
| Pending | [ ] | [ ] |
| Working or blocked | [x] | [ ] |
| Finished and verified | [x] | [x] |
Completed tasks keep both state boxes checked. The dashboard counts recorded tasks and steps; it does not prove tests passed or that an agent is still running.
Keep the work one shortcut away.
The ledger already works in your editor. The live dashboard makes it easier to browse agents, inspect tasks, and assign work. Use macOS, Linux, or WSL for the live terminal view.
A Set up the launcher
The skill install does not necessarily put handoff-tui on your PATH. Ask your agent to set it up from the installed copy:
Find the installed handoff skill. Create ~/.local/bin if needed, copy its scripts/handoff-tui launcher there, and make it executable. Ensure ~/.local/bin is on my shell PATH. Verify with handoff-tui --which and show me which installed helper it resolves to.Copy the launcher; a symlink into a versioned plugin directory can break after an update. Open a fresh terminal if your PATH changed.
B Open it once before binding a key
Run pwd in your project’s terminal, then paste the result. For WSL, use its Linux path. Paths with spaces are supported.
handoff-tui --root '/absolute/path/to/your-project'An Agents view with the owner from your ledger. Select that owner and press Enter for tasks, then Enter again for steps and status. In Agents, press Shift + N to pick an agent CLI, then Enter to open it in a new terminal with the handoff bar. Press q to close the viewer.
C Bind the shortcut for your terminal
Requires tmux 3.2+ and the selected agent CLI on PATH. For another CLI, replace the name after --with.
HANDOFF_VIEWER_KEY=C-M-h handoff-tui --install-viewer-key --emulator iterm2 --root '/absolute/path/to/your-project'iTerm2: installs a global key binding and a dedicated profile that opens this repository’s dashboard in a new window. If iTerm2 asks to load changed preferences, reload them before trying the key.
On a Mac: Control + Option + H.
Switch to your selected terminal to try it.
The shortcut is tested in your terminal. A browser keypress cannot verify the installed binding.
Not verified yet. You can still use HANDOFF.md and continue the guide.
The keys to learn first
- Enter
- Open an owner or task
- b
- Go back one level
- Tab
- Switch Agents / Tasks
- Shift + N
- Spawn a new agent from Agents, then Enter to open it
- q
- Close the dashboard
Uppercase N spawns a new agent. Lowercase n in the Channel view nudges a peer instead.
Leave a starting point.
Not a guessing game.
When you need to stop during a task, ask the current agent to make the record useful to its successor. If your project-map task is already complete, keep it complete; use this on your next unfinished task.
Pause this task using handoff. Record what is finished, what is still unverified, any blockers, changed files, and the exact next action. Preserve ownership and leave unfinished steps unchecked.After the prior agent has stopped writing, open a new agent session in the same repository. Ask it to audit and resume:
Use handoff. Read HANDOFF.md and audit the open work against later entries, commits, and current files. Tell me what actually remains and who owns it before starting.If the remaining task belongs to the stopped session, explicitly direct the new agent to take over from that recorded owner. It should preserve their work and verify the remaining outcome.
Move a task in the dashboard instead
- Select the unfinished task and press x to cut it.
- Press a for Agents, select the receiving agent, then press p to assign it.
- Confirm it appears under the new owner. A receiving agent finishes its current task, then audits and executes the assignment.
Assignment is an execution request, but it cannot wake a stopped model. Start or resume the receiving session. In task details, x moves a single step; X moves the whole task.
Success is a next agent that knows where to start.
Look for a recorded task, evidence for the work already done, and a precise next action. The next agent should inspect that evidence before continuing.
Explore the full workflowWHEN SOMETHING GETS IN THE WAY
Get unstuck.
“handoff-tui: command not found”
Return to launcher setup. Check that ~/.local/bin/handoff-tui exists and is executable, and that ~/.local/bin is on PATH. Open a fresh terminal after changing PATH. handoff-tui --which should print a path to handoff_tui.py.
“No handoff_tui.py found” or an unknown option
The launcher exists, but the skill may be missing or outdated. Run handoff-tui --which to inspect the resolved copy. Ask your agent to find and update the installed skill, then verify the launcher resolves the updated helper.
The dashboard is empty or shows another project
Check the absolute path passed to --root and open that project’s HANDOFF.md. Initialisation alone creates no task. Send the first task prompt to populate it. Press m in Agents if you need to return from machine scope to repository scope.
Ctrl+Alt+H does nothing
First run the viewer command directly. If that works, rerun the binding command for the correct terminal and repository. In Cursor, reload the window and focus its integrated terminal. In iTerm2, check that the Handoff profile and binding loaded. For tmux, launch the agent with the generated wrapper command and press the shortcut inside that session. Read any conflict reported by the installer.
On a Mac, use Control and Option, not Command. A binding saved for one repository does not follow you automatically to another: install it for the intended root. You can always run handoff-tui --root with your project path directly.
I’m on Windows or the terminal is too small
Use WSL for the live dashboard and the tmux wrapper. Live view needs at least 64 columns and 14 rows. On a terminal without curses support, add --once to the viewer command for a text snapshot, or read HANDOFF.md in your editor.
The agent has a name, but no task progress
A session name only identifies the agent. Progress comes from task entries in HANDOFF.md. Ask it to record the request with an owner, steps, and In progress checked before continuing its investigation or implementation.