/start - Session Startup & Context Recovery

Gather project context and recover from handoffs automatically.

Data Source Priority

1. Pre-loaded (preferred): Check for "Pre-loaded Session Status" in the SessionStart hook output (appears in system-reminder tags at conversation start with additionalContext). If found, parse the JSON code block and use this data directly—no MCP call needed.

2. MCP fallback: If no pre-loaded data exists, call getsessionstatus with appropriate level.

Look for a section like this in the startup system-reminders:

# Pre-loaded Session Status

The following session context was gathered at startup...

{ "level": "standard", "integrations": {...}, "recovery": {...}, "project": {...}, "beads_triage": {...} }

The pre-loaded data has the same structure as the MCP response—format and display it the same way.

## Quick Start (MCP Fallback)

// Fresh session - full context getsessionstatus({ level: "full" })

// Context recovery mid-session getsessionstatus() // defaults to minimal

// Restore specific handoff getsessionstatus({ handoff: "h7k2m" })

## Output Levels

| Level | Use Case | Sections |
|-------|----------|----------|
| `minimal` | Context recovery | project, harness, beads counts |
| `standard` | Most session starts | + beads_triage, agentmail |
| `full` | Fresh session | + claude_mem references |

## Auto-Recovery

The plugin tracks your work automatically via hooks. If context is lost (autocompact, /clear), recovery options appear:

### Session Marker Detection

If you see a marker like `<!-- session:abc123 -->` in context but lack detailed memory:

1. This means autocompact occurred mid-session
2. Immediately call: `get_session_status({ handoff: "abc123" })`
3. The MCP returns full working context
4. Resume work without asking user - just continue

### Rolling Checkpoint

If no marker but a recent checkpoint exists (< 24h), the response includes:

{ "recovery": { "available": true, "id": "abc123", "age": "2h" } }

Offer to restore: "Found recent work checkpoint. Resume?"

## Display Format

### Restored Session

┌─────────────────────────────────────────────────────────────────┐ │ SESSION RESTORED: {id} │ ├─────────────────────────────────────────────────────────────────┤ │ Task: {context.task} │ │ Last active: {age} │ ├─────────────────────────────────────────────────────────────────┤ │ RESTORED CONTEXT │ │ • Plan: {plan.path} (cached) │ │ • Files: {files.length} modified │ │ • Decisions: {userDecisions.length} │ │ • Todos: {todos.length} items │ ├─────────────────────────────────────────────────────────────────┤ │ FRESH STATE │ │ • Branch: {branch} ({uncommitted} uncommitted) │ │ • Integrations: {detected integrations} │ ├─────────────────────────────────────────────────────────────────┤ │ Continuing from: "{nextSteps[0]}" │ └─────────────────────────────────────────────────────────────────┘

### Normal Session Start

┌─────────────────────────────────────────────────────────────────┐ │ SESSION START │ ├─────────────────────────────────────────────────────────────────┤ │ Project: {project.root} │ │ Branch: {branch} ({uncommitted} uncommitted) │ ├─────────────────────────────────────────────────────────────────┤ │ Integrations: {list available} │ │ Harness: {if present, show status} │ │ Beads: {open} open | {actionable} actionable │ ├─────────────────────────────────────────────────────────────────┤ │ {recommendations based on state} │ └─────────────────────────────────────────────────────────────────┘

## Session Tracking

After completing significant work, append a session marker to enable auto-recovery:

<!-- session:{handoff_id} -->

This marker survives autocompact summarization and enables seamless recovery.

## Integrations

The plugin auto-detects and enhances with:

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

## Recommendations Logic

Based on state, recommend next action:

1. **Handoff recovered** → Continue from `nextSteps[0]`
2. **Loop in_progress** (harness) → Resume implementation
3. **Feature failing** (harness) → Fix failing verification
4. **Issue in_progress** (beads) → Continue that issue
5. **Actionable work** (beads) → Show top picks
6. **No tracked work** → Suggest adding work

## Related Commands

- `/handoff` - Create explicit checkpoint for session end
- `/session-context:handoff` - Same as above (full name)