Skip to main content
subagent CX Codex

engine_handoff — Claude Code subagent: what it does, how to install

engine_handoff — a subagent for Claude Code managing session handoffs and context synchronization between engines. Runs when switching engines during an active development session.

MIT ★ 395 updated 2026-11-16

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/engine_handoff.md
Open on GitHub

What engine_handoff does

The subagent handles context and conversation history transfer when switching between different coding engines. The prompt template compiles a summary of changes, modified files, recent commands, and previous turns while keeping references to full session transcripts.

Before making any changes, the subagent verifies state against the actual repository using git status or file reads. The workspace state always overrides historical records if a discrepancy occurs.

For older logs, the instruction directs targeted keyword searches using grep instead of dumping large transcript files directly into the active conversation.

What it helps with

  • transfer conversation context between engines
  • synchronize session history
  • verify actual repository workspace state
  • search transcript logs using keywords

Example prompts for the agent

  • Handle session handoff with engine_handoff
  • Synchronize context after switching engines
  • Check workspace state before making changes

How to install engine_handoff

Manually: put the files in place

.claude/agents/engine_handoff.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about engine_handoff

How to install engine_handoff in Claude Code?

Place the file at .claude/agents/engine_handoff.md.

What does engine_handoff do?

It manages session handoff and context transfer when switching between different coding engines.

How does the subagent handle conflicts with history?

When conversation records conflict with the actual workspace state, the workspace always wins.

Source text

engine_handoff.md · MIT
[Session handoff · internal context]
{{if .Delta -}}
You ({{ctx .To}}) worked on this conversation before; it was handed over to the {{ctx .From}} engine for a while, and now it is switching back to you. Your memory of the conversation from before you left should still be valid; below is a record of what happened while you were away. Merge it into your understanding and continue naturally in the first person. Do not mention this handoff note to the user, and do not mention the engine switch. Before making any change, check the actual workspace state (e.g. git status / git diff / reading the relevant files): when the record, your own memory, and the workspace disagree, the workspace always wins; when you are unsure about something from while you were away, read the real files and code to confirm rather than guessing from the summary.
{{- else -}}
This conversation was previously driven by the {{ctx .From}} engine; from here on you ({{ctx .To}}) continue it. Below is the prior record of this conversation — it is the same conversation between you and the user, so continue naturally in the first person. Do not mention this handoff note to the user, do not mention the engine switch, and do not say things like "according to the handoff summary/record". Before making any change, check the actual workspace state (e.g. git status / git diff / reading the relevant files): when the record conflicts with the workspace, the workspace always wins; when you are unsure about an earlier detail, read the real files and code to confirm rather than guessing from the summary.
{{- end}}
{{- with .Ledger}}{{if or .Files .Commands .Failed}}

== Work ledger (auto-extracted) ==
{{- if .Files}}
Files changed:
{{- range .Files}}
- {{ctx .}}
{{- end}}
{{- end}}
{{- if .Commands}}
Commands (most recent):
{{- range .Commands}}
- {{template "agents/engine_handoff_command" .}}
{{- end}}
{{- end}}
{{- if .Failed}}
Failed attempts:
{{- range .Failed}}
- {{template "agents/engine_handoff_command" .}}
{{- end}}
{{- end}}
{{- end}}{{end}}
{{- if or .Index .Omitted}}

{{if .Delta}}== Earlier progress while you were away =={{else}}== Earlier conversation index (hints only, not a verified summary) =={{end}}
{{- if .Omitted}}
(earlier content omitted)
{{- end}}
{{- range .Index}}
{{if .Reply}}  Reply: {{else}}- {{template "agents/engine_handoff_speaker" .}}: {{end}}{{ctx .Text}}
{{- end}}
{{- end}}
{{- if .Recent}}

{{if .Delta}}== Conversation while you were away =={{else}}== Recent conversation =={{end}}
{{- range $i, $turn := .Recent}}
{{- if $i}}
---
{{- end}}
{{- if or .Text .Images}}
[{{template "agents/engine_handoff_speaker" .}}]
{{- if .Text}}
{{ctx .Text}}
{{- end}}
{{- if .Images}}
({{.Images}} image{{if gt .Images 1}}s{{end}} attached, not carried over)
{{- end}}
{{- end}}
{{- range .Lines}}
{{if eq .Kind "assistant"}}[Assistant]
{{ctx .Text}}
{{- else if eq .Kind "tool"}}[Tool] {{ctx .Tool}}{{if .ID}} (id={{ctx .ID}}){{end}}{{if .Text}}: {{ctx .Text}}{{end}}
{{- else if eq .Kind "result"}}[Tool result{{if .ID}} id={{ctx .ID}}{{end}}; {{if .Failed}}failed{{else}}recorded; verify outcome from result{{end}}]
{{if .Text}}{{ctx .Text}}{{else}}(no text result retained){{end}}
{{- else}}({{.Omitted}} tool calls omitted)
{{- end}}
{{- end}}
{{- end}}
{{- else if .Delta}}

== No new messages while you were away ==
{{- end}}
{{- if .Transcripts}}

== Retrieving earlier verbatim history (use when needed) ==
{{if .Delta}}What happened while you were away{{else}}This conversation's earlier record{{end}} is kept word for word in {{if gt (len .Transcripts) 1}}these transcript files{{else}}this transcript file{{end}} on this computer:
{{- range .Transcripts}}
- {{ctx .Engine}} session {{ctx .Session}}: {{ctx .Path}}
{{- end}}
The record above is only a hint. Retrieve earlier verbatim text only when an earlier detail is actually needed: search the file for keywords and read only around a hit. Each line is one JSON record and some are very long, so print only part of a matching line (e.g. `grep -o '.\{0,200\}<keyword>.\{0,200\}' <file>`). Never read or print a whole file, and never dump the history into the conversation. Retrieved original text outranks this note; when it conflicts with the current workspace, the workspace wins.
{{- end}}

== End of handoff note; the user's new message follows ==

© nwverse · MIT · nwverse/persona

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set61

The whole set →
worker_supervise worker_supervise — a subagent for Claude Code supervises background workers launched with task_plan. It checks submitted evidence against completion criteria and updates worker status via task_review. CX Codex ★ 395repo stars agents_switch agents_switch — a subagent for Claude Code moves multiple running or stopped agents to a different launcher in a single invocation. Executes when requested to manage subscription usage quotas. CX Codex ★ 395repo stars standing_actions Claude Code subagent standing_actions classifies the operations authorized by an agent confirmation card. CX Codex ★ 395repo stars agent_send This Claude Code subagent sends messages to another agent and can assign it supervised work. It can resume a stopped agent with its context when the recorded stop reason allows it. CX Codex ★ 395repo stars agent_start This Claude Code subagent starts an agent in a project directory on one of the user's machines. It hands off development work and returns the new session ID. CX Codex ★ 395repo stars frontend-motion The frontend-motion subagent for Claude Code handles UI layout, components, transitions, and animations. It runs during scoped frontend tasks with a defined brief. CX Codex ★ 395repo stars task_review task_review — a subagent for Claude Code reviews completed delegated tasks and records a verdict. It can accept the work, return gaps to the same agent, or ask the owner to decide. CX Codex ★ 395repo stars task_plan The task_plan subagent for Claude Code builds and hands users a task plan for running agents on their computers. Runs on any work that takes an agent or more than a few tool calls. CX Codex ★ 395repo stars

Project sponsors

Companies that keep this analytics open