// Use when the user wants to continue work from one agent in another agent, inspect recent sessions, or summarize a saved session or checkpoint for handoff
| name | session-handoff |
| description | Use when the user wants to continue work from one agent in another agent, inspect recent sessions, or summarize a saved session or checkpoint for handoff |
Begin the first response to this skill invocation with the line:
Entire Session Handoff:
followed by a blank line, then the content. Apply the header to the first response of the invocation only — not on follow-up turns and not on error / early-exit responses (no sessions found, transcript missing). Its presence signals the skill ran and produced real output. The "Unanswered Question" branch still gets the header.
git log, git status, git branch, ps aux, or any other exploratory commands. Use only the entire CLI commands listed below.Required CLI: entire 0.6.2+ (session list --json, session info --transcript, session current --json|--transcript, checkpoint explain --json|--transcript|--raw-transcript --session-index N). If a flag is rejected, tell the user to upgrade and stop.
entire session current --json
If the output is valid JSON, read its worktree_path field — that is the canonical worktree root for this invocation, set by Entire itself. Use it verbatim in the next step (no cwd heuristic needed; symlinks, /private/var//var quirks, and subdirectory invocation are all handled).
If the output is not JSON (Entire prints No active session found in this worktree. when nothing is active), set the canonical worktree path to null and rely on the bidirectional prefix-match fallback in Step 2.
entire session list --json
Each entry has session_id, agent, status, worktree_path, started_at, last_active, turns, last_prompt, files_touched. Apply filters in this order:
worktree_path equals it exactly. Otherwise, keep entries where cwd starts with worktree_path or worktree_path starts with cwd. If either filter yields zero entries, fall back to the unscoped list — better to summarize a slightly-off session than to refuse the handoff.agent matches case-insensitively as a substring (so gemini matches Gemini CLI).agent matches the agent currently running this skill (e.g. Claude Code, Codex, Cursor, Gemini CLI, Copilot CLI, Factory AI Droid, OpenCode). If this empties the list, undo this filter and keep self — the user is asking you to summarize your own current session for compaction. Note that fact in the announcement (Step 5).last_active (fall back to started_at) descending; take the first.If filtering still leaves zero entries (truly nothing in the list, even self), print a one-line error (no header) and stop.
entire session info <session_id> --transcript > /tmp/handoff-<session_id>.jsonl
Snapshot is bounded to the file size at command start. Output is JSONL for most agents and a single JSON document for Gemini CLI.
JSONL agents (Claude Code / Codex / Cursor / Copilot CLI / Factory AI Droid / OpenCode):
grep -E '"type":"(message|function_call|user|assistant)"' /tmp/handoff-<session_id>.jsonl | cut -c1-2000 | head -20 # original task
grep -E '"type":"(message|function_call|user|assistant)"' /tmp/handoff-<session_id>.jsonl | cut -c1-2000 | tail -100 # final state
Gemini CLI (single JSON document — no JSONL grep):
jq 'keys' /tmp/handoff-<session_id>.jsonl
The top-level shape varies by Gemini CLI version, but messages live under one of messages, contents, history, or turns. Each entry has a role (user/model/function/tool) and a content payload under one of parts[].text, content, or text. Extract role + text in chronological order:
# Example — adapt the path based on what `jq 'keys'` showed.
jq -r '.messages[] | "\(.role): \([.parts[]? | .text // ""] | join(" "))"' /tmp/handoff-<session_id>.jsonl | head -20
jq -r '.messages[] | "\(.role): \([.parts[]? | .text // ""] | join(" "))"' /tmp/handoff-<session_id>.jsonl | tail -100
If neither shape works, fall back to the Read tool on the JSON file and locate the message array by inspection.
Do not show the raw extracted lines to the user. They are inputs for Step 5.
Announcement. First line of the body: Handing off <agent> session — <turns> turns, last active <relative time>, ID <first-8-of-session-id>. If the picked session is your own (Step 2 self-filter fallback), prepend a one-clause note: Self-handoff (no other sessions in this worktree). This gives the user a chance to catch a wrong pick before reading the summary.
Summary structure (skip any section with no genuine content — do not hallucinate filler):
A one-bug-fix session might legitimately have only Task Overview + Current State + Next Steps. A pure-research session might have only Task Overview + Important Discoveries. Empty sections are a feature; pad them only if you have real content.
Continue. Show announcement + summary.
entire checkpoint explain <checkpoint-id> --json
The envelope's sessions array lists every session that contributed. Multi-session checkpoints are common (parallel agents, retries, multi-phase work) and earlier sessions often carry the rationale, failed approaches, and user constraints that the latest session takes for granted.
1 session. Stream the normalized compact transcript:
entire checkpoint explain <checkpoint-id> --transcript > /tmp/handoff-ckpt-<checkpoint-id>.jsonl
2–8 sessions. Iterate every index 0..N-1. Do not rely on the --transcript default (latest session only):
# for N in 0 .. sessions.length-1
entire checkpoint explain <checkpoint-id> --raw-transcript --session-index <N> > /tmp/handoff-ckpt-<checkpoint-id>-<N>.jsonl
More than 8 sessions. Sort the sessions array by timestamp (started_at or whichever field the envelope provides) descending and take the 8 most recent. Note the cap in the announcement: <M of N> sessions summarized; oldest <M-N> elided as too old to matter. This keeps the skill bounded while still covering the recent rationale layer.
--raw-transcript keeps the per-agent raw bytes so the same JSONL grep extraction works. Index 0 is the first session chronologically.
Run the Step 4 extraction (head + tail per file) on each /tmp/handoff-ckpt-*.jsonl, then merge into a single five-section summary. Treat earlier sessions as the source of "Important Discoveries" and "Context to Preserve"; the latest session feeds "Current State" and "Next Steps". Empty-section rule from the active-session flow applies. Then announce + present per Step 5 of the active-session flow, with the announcement adapted to checkpoint context (Handing off checkpoint <short-id> — <M> sessions, <total turns> turns total.).
Use when the user describes a task and wants to know whether something similar has been done before, then turn the closest prior session into a task playbook. Triggers on phrases like "have we done this before", "recall how we did X", "find similar work", "any precedent for", "has anyone solved", "is there a template for", and "how did we do this last time"
Use when the user wants to step through a feature's checkpoints chronologically, pausing at each step to ask questions. Triggers on phrases like "replay <feature>", "walk me through how X was built", "show me the journey of", "step me through how Y was implemented", and "replay the last week"
Use when a developer wants a topic-focused guided lesson built from canonical checkpoints, not a whole-repo overview. Triggers on phrases like "teach me <topic>", "teach me how this repo handles", "how does <topic> work in this repo", "give me a lesson on", "school me on", and "I need to learn about"
Use when an agent session ran outside the repo whose commits should record it — e.g. launched from a higher-level folder, a non-Entire repo, or one repo but editing another — to attach the session to each affected Entire-enabled repo's HEAD commit.
Explain why code looks the way it does by tracing the latest change for a file range or pasted snippet through `git blame` and deduplicated `entire explain` lookups. Use when the user asks what happened, says "tell me why" about a code block, is confused about a section of code, asks "wtf is going on", "why is this like this", "why was this changed", or wants provenance for a specific file block.
Explains the intent behind source code by finding original session transcripts. Use explain with a function, file, or line of code to understand why it exists.