Cross-tool handoff
A handoff is two steps: capture context from a source session into a payload, then inject that payload into a target session or a new one — possibly in a different tool.
Every payload is content-addressed and lands in the context library, so the same capture can be reused, re-injected, or wired into a workflow.
The payload in the middle is the point: context stops being a copy-paste and becomes an object with an identity, a history, and a second life.
Capture
Section titled “Capture”| Kind | Endpoint | What it produces |
|---|---|---|
| distilled-summary | POST /api/context/distill | An AI brief written by an agent from the transcript |
| transcript-excerpt | POST /api/context/extract | The raw conversation rendered to markdown |
| files | POST /api/context/files | A manifest of touched files, optionally with contents |
Excerpt config
Section titled “Excerpt config”| Option | Values | Default |
|---|---|---|
| roles | user, assistant | both |
| tool calls | none · names only · full I/O | names |
| thinking | on / off | off |
| max chars | number | unlimited |
| range | message range, set by selecting in a transcript | whole thread |
Output is ## role — timestamp sections; over-long output gets a […truncated] tail.
Distill
Section titled “Distill”Distilling renders the thread with default excerpt settings (capped at 400k chars) and pipes it through claude -p --max-turns 1 (default model sonnet, override per node). The brief is asked for goal, current state, key decisions and why, files touched, unresolved issues, and exact next steps — markdown only. An outer ```markdown fence is stripped if the model adds one.
It runs as a job: progress and streamed assistant text arrive on /api/events, and cancelling aborts the child process.
The manifest is an operation | path table. With snapshot file contents on, each written file under 256 kB is appended verbatim; binaries and missing files are skipped but keep their row.
Inject
Section titled “Inject”POST /api/inject takes a payloadHash plus a target and runs as a job. Modes differ per provider:
| Provider | Mode | Mechanism |
|---|---|---|
| Claude Code | Fork this session (resume-fork) | claude --resume <id> --fork-session -p <preamble + kickoff> — new session with the old history and the context |
| Claude Code | New session in project dir (new-session) | Fresh --session-id, context passed via --append-system-prompt-file |
| opencode | Insert context silently (synthetic) | POST /session/:id/message with noReply: true and a synthetic text part — nothing is generated |
| opencode | Continue session with context (continue) | opencode run -s <id> |
| opencode | New session in project dir (new-session) | opencode run with optional --agent / -m |
| Cursor | Continue session with context (continue) | agent -p --trust --workspace <dir> --resume <id> |
| Cursor | New session in project dir (new-session) | agent create-chat pins the id, then the same run |
Injected text always opens with a preamble naming the source:
# Context handed off from another agent session
(source: claude-code session <id> — "<title>", payload kind: distilled-summary)Except in synthetic mode, the kickoff prompt is appended after a --- rule. Claude’s default kickoff, if you leave it blank, asks the target to summarise what it now knows and what it would do next — and not to start working yet.
Runs are capped at 10 minutes. On success threadle records the handoff in lineage and publishes sessions.changed so the new session appears.
Cursor’s agent mode is derived from the target agent name: plan and ask become --mode plan / --mode ask.
opencode’s silent insert needs an HTTP surface, so threadle spawns and reuses one opencode serve --port 0 with a generated password, single-flighted and backed off for 30s after a failed spawn. It is killed with the server.
One-step handoff
Section titled “One-step handoff”Sessions view → select a session → ⇄ hand off does capture and injection together:
- Pick the context kind — distilled summary or transcript excerpt.
- Pick the target provider, agent, and (optionally) model.
- Write the instruction for the target agent.
threadle captures the payload, runs the target agent with payload + --- + instruction in the source session’s project dir, then records the handoff with mode handoff. The result panel links straight to the new session, its blueprint, and lineage.
On the canvas
Section titled “On the canvas”The same pieces exist as nodes: wire a session into a context node, set its config, press Materialize, and wire the payload onward into an agent. A context node that already carries a payloadHash is pre-materialized — required for detached runs, which cannot materialize on the fly.
Related
Section titled “Related”- Context library — where payloads live
- Lineage — the session → payload → session graph
- Sessions — picking a source
- Providers — the CLIs behind each mode