handoff

handoff

A pre-/clear task snapshot for Claude Code. Designed as a narrow complement to Claude Code's auto-memory: memory holds durable facts (preferences, feedback, project context); this plugin holds the ephemeral task frame memory avoids — what you were doing right now, what decisions are still open.

Setup

Install the plugin:

/plugin marketplace add ddaanet/claude-plugins
/plugin install handoff@ddaanet

That's it. No per-project setup step. A SessionStart(startup|clear) hook assembles the handoff frame in memory at session start — reading ./.claude/handoff-task.md and scraping the prior session transcript — and injects the result into the fresh agent's context. No generated file is involved.

Migrating from v0.2.x: if your project's CLAUDE.md contains a ## Handoff section with @.claude/handoff.md (added by the old /handoff:setup skill, removed in v0.3.0), delete it. Leaving it in place is harmless but causes the content to load twice (once via the SessionStart hook, once via the @-ref).

Usage

Before /clear, ask the agent to save a handoff:

• "save handoff"
• "before I clear"
• "prepare handoff"
• "wrap up"
• "I'm done"

Or invoke explicitly with /handoff:handoff.

To name the session without a handoff — a /btw side conversation, or any session worth a title while the main thread stays live — invoke /handoff:autoname. It derives a title from the conversation and renames the session (via the same tmux send-keys-when-idle path as handoff, or a /rename line to paste outside tmux); it writes no task file and touches no memory.

A PreToolUse(Skill) hook wipes any prior handoff files the moment the skill activates, so the slate is always clean — and tells the agent so it doesn't redundantly verify. The agent then updates auto-memory with any durable learnings, and in a single turn writes a short task snapshot (if anything is outstanding) and a session title to .claude/autorename. A PostToolUse(Write|Edit) hook stages handoff-task.md for commit and records the session pointer to .claude/handoff-session. A second hook picks up autorename and renames the session via tmux send-keys once the prompt goes idle (or emits a /rename line to paste if not in tmux). Guards prevent the agent from reading or writing .claude/handoff-task.md outside the handoff flow. After /clear (or in a fresh session), the SessionStart hook assembles and injects the handoff frame into the new agent's context automatically. Auto-memory restores independently.

In a gitlore-managed repository, handoff also offers to commit your memory: when the memory submodule has uncommitted changes, it summarizes them, asks you to approve (or edit) the summary, and commits via gitlore — so durable learnings land instead of waiting for your next commit.

Staleness and cleanup

The artifact carries its own timestamp in its first heading. When the task is finished, invoke the skill again with nothing outstanding — the activation hook wipes prior files and the agent writes nothing new, so the next session starts clean.

handoff-task.md is staged automatically by the PostToolUse hook and rides your next commit — it is the durable task trail. The .claude/handoff-session pointer and .claude/handoff-error.log are machine-local; add them to .gitignore. A useful .gitignore snippet:

.claude/handoff-session
.claude/handoff-error.log

gitlore auto-memory is the complement for durable context that outlives tasks.

Scope

Concern	Handled by
Durable facts, preferences, feedback	auto-memory
Conversation transcript, resume	session JSONL + claude -c
In-session compaction	Claude Code /compact, Session Memory
Code state	the repo
Current task + open decisions across /clear	this plugin

See DESIGN.md for the research and analysis behind this split.

Choosing a handoff provider

This is the lightweight, local pre-/clear snapshot. A separate plugin, ddaa-handoff (and its French ddaa-passation), provides a heavier end-of-session summary delivered to Notion when available. They share the same trigger phrases on purpose, so the same words work whichever you pick — therefore enable exactly one handoff provider per project. Enabling both reloads the collision this split was made to remove.

Requirements

• Claude Code (depends on session JSONL format and plugin hooks)
• python3 in $PATH
• jq in $PATH

Files touched on your system

Per project, under ./.claude/. The PostToolUse hook runs git add -f on handoff-task.md so it appears staged for your next commit.