session-context

Session Context Plugin

Session continuity and context recovery for Claude Code. Auto-tracks your work via hooks, survives autocompact, and generates rich continuation prompts.

Note: this is an experimental plugin born from my config. It does work pretty well, but beware of bugs.

Features

• Automatic Tracking: Hooks capture file edits, todos, plans, and user decisions as you work
• Session Handoffs: Create explicit checkpoints with /handoff for seamless continuation
• Autocompact Survival: Session markers survive context summarization for automatic recovery
• Rich Context Recovery: /start gathers project state and can restore from handoffs
• Optional Integrations: Enhanced context from beads, claude-harness, claude-mem, and agent-mail

Installation

# Add the marketplace (one-time setup)
/plugin marketplace add sethyanow/session-context

# Install the plugin
/plugin install session-context@sethyanow

Commands

/start - Session Startup

Gather project context and recover from previous sessions.

/start              # Normal session start
/start handoff=abc  # Restore specific handoff

/handoff - Create Checkpoint

Create an explicit checkpoint before ending a session or when context is low.

/handoff

This generates a continuation prompt you can paste into your next session.

How It Works

Pre-loaded Session Context

At session start, the plugin's SessionStart hook automatically gathers and injects session context directly into the conversation. This means:

• No MCP call needed - Session data is pre-loaded before /start runs
• Faster startup - Context is immediately available
• Token efficient - Eliminates round-trip to MCP server

The hook gathers:

• Git status (branch, uncommitted files, recent commits)
• Beads triage (if .beads/ exists)
• Harness state (if .claude-harness/ exists)
• Agent Mail status (if configured)
• Recovery checkpoint info (if available)

When you run /start, it uses this pre-loaded data directly instead of calling the MCP.

Automatic Tracking

The plugin installs hooks that capture your work:

Hook	Trigger	Captures
dot-start-handler.ts	SessionStart	Pre-loads session context
track-edit.ts	Edit, Write, NotebookEdit	Modified file paths
track-todos.ts	TodoWrite	Current todo list
track-plan.ts	ExitPlanMode	Full plan content
track-qa.ts	AskUserQuestion	User decisions

Data is stored in ~/.claude/session-context/handoffs/.

Handoff Flow

1. During work, hooks maintain a rolling checkpoint with your current state
2. When ready to end a session, run /handoff
3. Plugin generates a continuation prompt with:
   • What you were doing
   • Key decisions made
   • Next steps to take
4. Copy the prompt for your next session
5. New session detects the session marker and auto-recovers

Autocompact Survival

The continuation prompt includes a session marker:

<!-- session:abc123 -->

This marker survives Claude's context summarization. When detected after autocompact, the plugin automatically loads full context from storage.

MCP Tools

The plugin provides three MCP tools:

get_session_status

Gather session startup data with optional handoff recovery.

Note: Session data is typically pre-loaded by the SessionStart hook, making this call unnecessary for normal startup. Use this MCP tool as a fallback or when you need to restore a specific handoff.

get_session_status({
  level: "full",      // minimal | standard | full
  handoff: "abc123"   // Optional: restore specific handoff
})

Levels:

• minimal: project, harness, beads counts
• standard: + beads_triage, agentmail
• full: + skill_usage, claude_mem references

create_handoff

Create explicit checkpoint with continuation prompt.

create_handoff({
  task: "Implementing user auth",
  summary: "Added login endpoint, working on JWT",
  nextSteps: ["Add token refresh", "Write tests"],
  decisions: ["Using JWT over sessions"],
  blockers: []
})

update_checkpoint

Update rolling checkpoint (called by hooks).

update_checkpoint({
  files: ["src/auth.ts"],
  todos: [...],
  plan: { path: "...", content: "..." }
})

Integrations

The plugin auto-detects and enhances with optional integrations:

Integration	Detection	Enhancement
Git	Always	Branch, uncommitted, recent commits
Beads	.beads/ exists	Issue triage, actionable work
Claude Harness	.claude-harness/ exists	Features, memory, loop state
Agent Mail	MCP configured	Inbox status, file reservations
Claude-Mem	MCP configured	Observation ID references

Configuration

Create ~/.claude/session-context/config.json: