Save an assignment or hand unfinished work to another session
brain_handoffSaves session handoffs and delegated assignments as project brain cards, letting another agent read, claim, and continue the work without copying context.
Instructions
Save delegated work immediately with {action:"write", reason:"assignment", for:"Codex", instructions:"", title, task, next, files, verify}, even while continuing your own work. Use the actual recipient client or role. Verify the returned card id, then notify a known recipient with brain_message; saving does not wake or launch agents. When asked for an assigned task, brain_sync the same project, list/read the addressed card and take it; never ask the human to copy the prompt. Assignments preserve the sender's separate task and use their saved brief, not the entire sender conversation. The session handoff. On hosts without native transcript access, call {action:"capture", turns:[{id,role,at,text}]} as user requests and replies arrive, before writing a handoff. Capture only observed text with stable ids and known timestamps; never reconstruct missing history. Captured evidence is local and does not establish full conversation coverage. Call {action:"write"} when you are stopping before the work is done — the human asked for a handoff, your context or usage limit is near, the day ends, you are blocked or switching tool — with the task, what is done, what is NEXT in order, the files and how to verify: it becomes a 🤝 card in the project brain that the human can see and correct, and the next session on this project (any agent — Codex, Claude Code, Cursor) sees it at its first brain_sync / session start. Call {action:"take", id} (a card) or {action:"take", session} (unfinished work a session left without a card — KLYPIX records every session's last reply, files and commits automatically) before continuing it, so peers see it is taken; {action:"done"} when it is finished (the card is archived); {action:"list"} shows every open handoff and every unfinished session. Never ask the human to paste a summary into the next session — write a handoff. Machine-local for the automatic layer; the card travels with the brain.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "brain_handoff"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | read / take / done / review: the handoff card id from brain_sync or list. | |
| for | No | write: recipient client or role, such as Codex, Claude Code or reviewer; required for assignment. Matching clients or roles see it first. list: filter to that recipient. A hint, not authorization, a reservation or an agent launcher. | |
| area | No | write: the brain area (titled box) the card goes into. Defaults to "Handoff". | |
| done | No | write: what is already finished (so it is not redone). | |
| next | No | write: the remaining steps IN ORDER, as the next session should do them. Required. | |
| open | No | write: questions still open, or decisions the human has to make. | |
| task | No | write: one or two sentences — what the work is and why. | |
| files | No | write: project-relative files the work touches (recorded as evidence anchors). | |
| title | No | write: the work, in a few words ("Drive upload: the Place-it-now chooser"). | |
| turns | No | capture: observed turns only, stable ids for retries and original timestamps in milliseconds. Never invent missing history. Stored locally outside the brain; full coverage remains unknown. | |
| action | No | write: save an assignment or session handoff. read: retrieve its complete saved brief by id. take/done: claim or finish that card. For ordinary session handoffs, review checks the source conversation; explicit assignments use their saved instructions. list: open cards, optionally filtered by for. capture: preserve observed turns without claiming full history coverage. | |
| canvas | No | Brain canvas filename/path. Defaults to the project brain ("brain"). | |
| cursor | No | review: nextCursor from the preceding page; omit to start. | |
| reason | No | write: assignment delegates only the saved brief while the sender may continue other work; the other reasons hand off the session's unfinished work. | |
| verify | No | write: how to check the state — a command or a visible result. | |
| project | No | Absolute project root containing brain.klypix. Defaults to this connection's project. | |
| session | No | take / done / review: the session id (or a unique prefix of 8+ characters) from the unfinished-work list, when the work has no card. Review creates a reviewable draft if needed. | |
| summary | No | done: what was finished. take: optional note. review acknowledgement: required account of completed and still-pending requests after reading all conversation pages. | |
| revision | No | review: exact transcript revision from the preceding page. | |
| continues | No | write: the id of an earlier handoff card this one continues — it is closed as "continued by" this one. | |
| reviewToken | No | review: acknowledge only AFTER reading every conversation page; supply the final token and a summary including outstanding requests. New source activity invalidates this token. | |
| instructions | No | write with reason assignment: the complete brief, including requirements, constraints, output paths and acceptance criteria. Required for assignments; preserves Unicode and newlines exactly. read/take returns it in full. |