What is session-capture?

The Session Capture skill is a powerful developer utility designed to preserve the complete state of an AI coding session into a structured STATUS.json file. It captures critical project metadata including Git context, active task progress, local service status, and strategic focus areas. This ensures a seamless transition between conversations, effectively bypassing context window limitations and allowing for instant project resumption without manual re-contextualization.

When should I use session-capture?

session-capture is useful in the following scenarios: • End-of-Day Handovers: Automatically archive the current workspace state, including running dev servers and pending tasks, to ensure a frictionless start the next morning. • Context Limit Management: When a conversation reaches its token limit, use this skill to snapshot the project state and migrate to a fresh session without losing momentum. • Multi-Tasking and Branch Switching: Document specific blockers, architectural decisions, and 'next actions' when pivoting between different feature branches or complex tasks. • Environment Auditing: Generate a comprehensive snapshot of project health, including test results, build status, and linting errors, to track progress across long-term development cycles.

name	session-capture
description	"Saves complete session state to STATUS.json for seamless continuation across conversations. Captures git context, in-progress tasks, service status, focus area, and next actions. Use at the end of work sessions, before context limits, or when switching to a different task. Do NOT use mid-task or for quick questions - the overhead is only worthwhile when you actually need to resume later."
- script	"${CLAUDE_PLUGIN_ROOT}/../../shared-py/hooks/auto-save-state.py"
once	true

Session Capture

Overview

Save current session state to STATUS.json for seamless continuation in future sessions.

Core principle: Future Claude should have everything needed to continue without asking.

Trigger: End of work session, major milestones, before context limits

STATUS.json Schema

{
  "lastUpdate": "2025-01-15T10:30:00Z",
  "project": "project-name",
  "sessionType": "Fresh | Resume | Continuation",
  "git": {
    "branch": "feature/current-work",
    "lastCommit": "abc123 - feat: add feature X",
    "uncommittedFiles": 3,
    "stagedFiles": 1
  },
  "tasks": {
    "inProgress": ["Task being worked on"],
    "completed": ["Recently completed task"],
    "blocked": ["Task blocked by X"]
  },
  "services": {
    "devServer": { "running": true, "port": 3000 },
    "database": { "running": true, "port": 5432 }
  },
  "context": {
    "focusArea": "Working on authentication flow",
    "blocker": "Waiting for API response format clarification",
    "nextAction": "Implement token refresh logic",
    "keyDecisions": ["Using JWT for auth", "Session expiry: 1 hour"]
  },
  "projectData": {
    "testStatus": "47 passing, 2 failing",
    "buildStatus": "passing",
    "lintErrors": 0
  }
}

Capture Process

Step 1: Gather Git State

# Get current branch
git branch --show-current

# Get last commit
git log -1 --format="%h - %s"

# Count uncommitted changes
git status --porcelain | wc -l

# Get staged files
git diff --cached --name-only | wc -l

Step 2: Gather Task State

From TodoWrite:

Tasks marked as in_progress
Recently completed tasks (last 3)
Any blocked tasks with reasons

Step 3: Check Services

# Check if dev server is running
curl -s http://localhost:3000/health || echo "not running"

# Check database
pg_isready -h localhost -p 5432 || echo "not running"

Step 4: Document Context

Capture:

What area of code you're focused on
Any blockers or decisions made
What should happen next
Key decisions made during session

Step 5: Run Project Checks

# Run tests
npm test 2>&1 | tail -1

# Check build
npm run build 2>&1 | tail -1

# Run lint
npm run lint 2>&1 | tail -1

Step 6: Write STATUS.json

Write to .claude/STATUS.json (or project root if no .claude directory)

When to Capture

Automatic triggers:

End of conversation (if hooks enabled)
Before Claude Code closes
After major milestone completion

Manual triggers:

Before switching to different work
When hitting context limits
Before complex operations

Example Output

{
  "lastUpdate": "2025-01-15T14:30:00Z",
  "project": "my-app",
  "sessionType": "Resume",
  "git": {
    "branch": "feature/user-auth",
    "lastCommit": "a7f3c2e - feat: add login form component",
    "uncommittedFiles": 2,
    "stagedFiles": 0
  },
  "tasks": {
    "inProgress": ["Implement password reset flow"],
    "completed": ["Create login form", "Add form validation"],
    "blocked": []
  },
  "services": {
    "devServer": { "running": true, "port": 3000 },
    "database": { "running": true, "port": 5432 }
  },
  "context": {
    "focusArea": "Authentication system",
    "blocker": null,
    "nextAction": "Add forgot password email template",
    "keyDecisions": ["Using nodemailer for emails", "Password reset expires in 1 hour"]
  },
  "projectData": {
    "testStatus": "45 passing, 0 failing",
    "buildStatus": "passing",
    "lintErrors": 0
  }
}

Integration

Pairs with:

session-resume - Reads STATUS.json on startup
context-restore - Loads previous context into working memory

Hook integration:

Can be triggered by session-end hook
Runs before Claude Code closes

session-capture

When & Why to Use This Skill

Use Cases