Skip to main content
Session lifecycle hooks help maintain continuity between Claude Code sessions by preserving context, learning patterns, and detecting project configuration.

​
SessionStart Hook

Runs when a new Claude session starts. Loads the most recent session summary into Claude’s context.

​
What It Does

Searches for recent session files (last 7 days) and injects the most recent session summary into Claude’s context via stdout.
const recentSessions = findFiles(sessionsDir, '*-session.tmp', { maxAge: 7 });
if (recentSessions.length > 0) {
  const content = readFile(latest.path);
  output(`Previous session summary:\n${content}`);
}
Checks for learned skills in the learned skills directory and reports how many are available.
const learnedSkills = findFiles(learnedDir, '*.md');
if (learnedSkills.length > 0) {
  log(`[SessionStart] ${learnedSkills.length} learned skill(s) available`);
}
Reports available session aliases that can be loaded with /sessions load <alias>.
const aliases = listAliases({ limit: 5 });
if (aliases.length > 0) {
  log(`[SessionStart] ${aliases.length} session alias(es) available: ${aliasNames}`);
}
Automatically detects the package manager (npm, pnpm, yarn, bun) and reports it to Claude.
const pm = getPackageManager();
log(`[SessionStart] Package manager: ${pm.name} (${pm.source})`);
Identifies project languages and frameworks (TypeScript, React, Next.js, Python, Go, etc.).
const projectInfo = detectProjectType();
if (projectInfo.languages.length > 0 || projectInfo.frameworks.length > 0) {
  output(`Project type: ${JSON.stringify(projectInfo)}`);
}

​
Hook Configuration

hooks.json
{
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start.js\""
        }
      ],
      "description": "Load previous context and detect package manager on new session"
    }
  ]
}

​
SessionEnd Hook

Runs when a Claude session ends. Persists session state for the next session.

​
What It Does

Saves the current session summary, including tasks completed, decisions made, and context to preserve.
Analyzes the session to identify extractable patterns and learnings that can be saved as skills.This enables continuous learning—the system gets smarter over time by capturing recurring patterns.

​
Hook Configuration

hooks.json
{
  "SessionEnd": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-end.js\""
        }
      ],
      "description": "Persist session state on end"
    },
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/evaluate-session.js\""
        }
      ],
      "description": "Evaluate session for extractable patterns"
    }
  ]
}

​
Session Persistence Flow

​
Session Storage

Session files are stored in:
  • Sessions directory: ~/.claude/sessions/
  • Session files: YYYY-MM-DD-session.tmp
  • Learned skills: ~/.claude/learned-skills/
  • Compaction log: ~/.claude/sessions/compaction-log.txt

​
Benefits

Continuity

Pick up where you left off without repeating context

Learning

System learns from patterns and improves over time

Configuration

Automatic detection of package manager and project type

History

Track compaction events and session evolution