Claude Code Save Plan Hook

February 20, 2026

I’ve been using Claude Code enough that I now default to Plan before I let it touch anything. The downside is obvious the moment you start running multiple threads of work in parallel: you end up with several plans in flight, each mid-groomed, each representing real time spent nudging the model toward something you’d actually approve.

And then a run hangs, or the agent crashes, or the terminal gets into a weird state.

Anthropic (and, frankly, most agent runtimes) still have enough instability that “just restart the session” is a normal troubleshooting step. That’s fine until you realize you just lost the plan you carefully shaped into a crisp set of steps.

So I wired up a small hook that snapshots the latest Claude plan into the repo the moment Claude transitions from Plan -> Edit. It’s a pure quality-of-life upgrade, but one that very quickly becomes “how did I live without this?”

The problem: plans persist, but not where you need them#

Claude Code helpfully persists plans to a common location, ~/.claude/plans/{random_name}.md.

That’s useful, but in practice it becomes a single bucket across all repos and sessions on your machine. If you’re hopping between projects (or juggling multiple plans), it gets messy fast.

What I actually wanted was:

“When a plan is about to result in edits, save a copy inside this repo.”
Name it something human-readable (based on the plan header).
Make it safe to run repeatedly and safe across multiple tool invocations.

The solution: snapshot on PreToolUse#

Claude Code exposes hooks. A PreToolUse hook is the perfect place to do this because it runs right as Claude is about to invoke an editing tool.

The flow looks like this:

Claude creates/tunes a plan (persisted under ~/.claude/plans/).
Claude is about to call Write, Edit, MultiEdit, or Bash.
Our hook runs:
- Finds the most recently updated plan file.
- Derives a slug from the plan’s # Heading.
- Copies it into docs/plans/{descriptive_name}.md in the current repo.
- Exits silently if there’s nothing to do.

From that point on, you’ve got a stable, repo-local record of the intent before implementation begins.

And because the file lives in your repo, it becomes easy to reference later in Claude prompts -- @docs/plans/{descriptive_name}.md.

Why is this valuable?#

Plans capture something that’s often missing in the final code, intent. Having that intent preserved inside the repo pays dividends well beyond simply avoiding lost work. It makes writing a strong PR description straightforward because you’re not reconstructing context from scattered code changes. It gives you a clean paper trail when debugging regressions, showing what you originally meant to implement. And it creates high-signal “why” documentation that stands apart from the implementation itself.

Instead of ephemeral agent chatter, plans become lightweight, versionable engineering artifacts that travel with the code.

Hook implementation#

Below is the exact setup: a settings.json hook plus a small Node script.

Save plan hook#

json

// ./claude/settings.json
{
  "permissions": {
      "defaultMode": "plan",
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/save-plan.js"
          }
        ]
      }
    ]
  }
}

Save plan script#

// .claude/hooks/save-plan.js
import fs from 'fs';
import path from 'path';
import os from 'os';

const input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
const { session_id, permission_mode } = input;

if (permission_mode !== 'acceptEdits') process.exit(0);

const lockFile = path.join(os.tmpdir(), `claude-plan-saved-${session_id}`);
if (fs.existsSync(lockFile)) process.exit(0);
fs.writeFileSync(lockFile, '1');

const plansDir = path.join(os.homedir(), '.claude', 'plans');
if (!fs.existsSync(plansDir)) process.exit(0);

const latest = fs.readdirSync(plansDir)
  .filter(f => f.endsWith('.md'))
  .map(f => ({ f, mtime: fs.statSync(path.join(plansDir, f)).mtimeMs }))
  .sort((a, b) => b.mtime - a.mtime)[0];

if (!latest) process.exit(0);

const content = fs.readFileSync(path.join(plansDir, latest.f), 'utf8');
const title = content.match(/^#\s+(.+)$/m)?.[1]
  ?.trim()
  .toLowerCase()
  .replace(/[^a-z0-9]+/g, '-')
  .replace(/^-|-$/g, '');

const outName = title ? `${title}.md` : latest.f;

const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
const outDir = path.join(projectDir, 'docs', 'plans');
fs.mkdirSync(outDir, { recursive: true });

fs.copyFileSync(
  path.join(plansDir, latest.f),
  path.join(outDir, outName)
);

process.exit(0);