handoff
End-of-session save and next-session resume. Triggers "ending session", "wrapping up", "context window", "running out of context", "done for today" (save mode); "continue where we left off", "pick up where", "last session", "previous work", "resume" (resume mode).
darkroomengineering · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add darkroomengineering/cc-settings --skill handoff技能说明
name: handoff argument-hint: "[save|resume]" description: End-of-session save and next-session resume. Triggers "ending session", "wrapping up", "context window", "running out of context", "done for today" (save mode); "continue where we left off", "pick up where", "last session", "previous work", "resume" (resume mode). context: fork
Session Handoff
Two-mode skill: Save state at end of session, Resume state at start of next session.
Product-aware runner and state
Claude uses the installed runner and state under ~/.claude:
HANDOFF_RUNNER="$HOME/.claude/src/scripts/handoff.ts"
CC_STATE_ROOT="$HOME/.claude"
Standalone Codex uses
${CODEX_HOME:-$HOME/.codex}/darkroom/source/src/scripts/handoff.ts, but the
plugin's stable handoff state is exposed only to hooks as $PLUGIN_DATA. In a
Codex plugin hook, set HANDOFF_RUNNER to that runner and
CC_STATE_ROOT="$PLUGIN_DATA". Outside that environment, do not guess a cache
path or write into ~/.claude: manual Codex create/resume/list/clean is
unavailable until the host exposes the same plugin-data path to the session.
Mode: Save
Save current session state for later resumption. This is the end-of-session boundary skill — for mid-task rollback points before risky operations, use /checkpoint.
Usage
CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$HANDOFF_RUNNER" create
Or use the native command:
/handoff
What Gets Saved
Every handoff — auto or manual — always captures real, git-derived data at creation time:
- Project: name, path, current branch
- Pending changes:
git status --porcelain(first 20 lines) - Key files: uncommitted paths union the files the session ledger observed being changed (see below)
- Recent commits: subjects of the last 3 commits
- Source:
manualorauto(see below)
In Claude, three additional sections are built purely from observed tool activity, not inference:
- Files Modified — every path a
Write/Edit/NotebookEdittouched - Files Read — every path a
Readtouched - Tool Failures — the exact tool name and error string, bounded and secret-redacted
These Claude-only sections come from the session ledger, a bounded JSONL at
~/.claude/tmp/session-ledger/<session_id>.jsonl written by the PostToolBatch
hook. It exists to fix a specific hole: git status forgets everything you
committed. A file edited at the start of a long session and committed an hour
later is invisible to a git status-only handoff, so the longer the session,
the more of its work disappears from the record. The ledger stores paths, tool
names, and error strings only — never file contents, prompts, or tool responses
— and never infers, so a Bash command's success is recorded as nothing
rather than as a guess.
Beyond that, what's actually filled in depends on how the handoff was created:
- Manual (
/handoff, orhandoff.ts create --summary "text") — the--summarytext becomes the Session Summary. Active Todos / Current Task / Notes for Next Session are placeholders (<!-- ... -->) for you (or the agent, before the turn ends) to fill in manually — the CLI has no way to know your in-progress todos, decisions, or learnings on its own. - Automatic (PreCompact/SessionEnd hooks call
create --from-hook,source: "auto") — Active Todos, Current Task, and Notes for Next Session stay as unfilled placeholders, but Session Summary is no longer blank on the compaction path: thePostCompacthook writes Claude Code's owncompact_summaryinto the handoff that the precedingPreCompactcreated, matched on session id. That summary is the one record of intent, decisions, and rationale; the ledger sections are the record of artifacts. They are stored separately and never merged, so nothing inferred is presented as observed.
Standalone Codex hooks capture the git-derived fields through the shared
runner, but Codex does not provide Claude's PostToolBatch session ledger or
PostCompact compact_summary backfill. Do not claim those sections were
observed in Codex.
On a Claude SessionEnd handoff (no compaction involved) Session Summary can still be
empty — pair it with the structured compaction template below, or run a manual
/handoff with --summary before ending a session.
GitHub Issue Sync
If the current branch is linked to a GitHub Issue (e.g., feat/123-description):
-
Post a progress comment on the issue:
gh issue comment 123 --body "## Session Update - Completed: [summary of work done] - Files modified: [list] - Next steps: [what remains]" -
Check off completed tasks in the issue body if any task checkboxes were resolved during this session.
This ensures project progress is visible to the whole team, not just in local handoff files.
Handoff Location
Handoffs are scoped per project (repo toplevel basename, or cwd basename
outside a git repo) — a handoff saved in one project never surfaces as
"latest" when you resume in another. Claude stores them below
~/.claude/handoffs; Codex plugin hooks store them below
$PLUGIN_DATA/handoffs:
~/.claude/handoffs/
└── <project-name>/
├── handoff_20260115_143000.md
├── handoff_20260115_143000.json
├── latest.md -> handoff_20260115_143000.md
└── ...
Handoffs saved before this per-project scoping existed live under the flat
~/.claude/handoffs/ directory; resume/list fall back to that legacy
directory exactly once, only when the current project has no scoped store of
its own yet.
When to Create Handoff
- End of work session - Before closing Claude Code
- Context at 65%+ - Before manual compaction or context quality degrades
- Taking a break - Preserve state for later
- Switching tasks - Save before context switch
- Before compacting - Auto-triggered by PreCompact hook
Auto-Handoff
Both products create git-derived handof
阅读完整来源 ↗