[FEATURE] Allow setting plan naming scheme per-repo

I've run into this issue several times and I'm honestly shocked about the architectural choice to store project/repo-specific state globally. Sometimes Claude Code creates a total mess and you're happy to have git, so that you can git reset --hard. Obvious user expectation would be: we're starting fresh again. But no, your old, totally opaque plan.md files, with dead-end thought traces, still haunt you and lead Claude again astray. Please add at least the storage setting for plan files, as many others have requested.

Much required feature.

Oh i've been fighting claude code for two weeks now to keep the plans inside the local .claude/plans folder of the repo. It fits perfectly with code review/audit hooks on commits, having the plan.md included in the commit.

Pardon... Multiple GH issues here _asking for plan names to be semantic_ instead of random have been auto-closed as duplicates ultimately leading to this one issue, which seems to be the only one that was NOT auto-closed.

But this issue is about a different thing, concerning locations rather than naming. So, @bcherny et al, what would be the proper way to address this?

I imagine the solution to be dead-simple by just providing Claude with a "slug" argument to "EnterPlanMode" tool — you can even make it optional if you want full backwards compatibility.

But I feel the fact that there’s at least a dozen issues to the same, ALL auto-closed due to a duplicate chain which ultimately leads to a non-related issue, makes this one in sort of a blind zone for the team.

Thanks for your attention.

Just posted a workaround that has zero-friction operation here: https://github.com/anthropics/claude-code/issues/21342#issuecomment-3853266585

Features:

1. Session plan file naming convention can be anything (I use my project folder name, can be constructed to a predictable pattern)
2. Manages session plan name changes between Claude restarts, while consistently writing to a common plan location for the project
3. Stored in Project Repo
4. Built with Serena MCP usage (but not required, can target any folder - including team-shared folder locations)
5. Automatically "Takes out the trash" (deletes session plan files from previous sessions)

Hope it helps someone else like it helped me (I run multiple worktree projects simultaneously, so Claude can work on one problem while I create a new prompt for a different problem in a different worktree - reduces downtime)

I suggest we close this ticket because, for example, I am currently using the latest version (v2.1.62), and everything is working as intended. I have the following settings in Claude Code Settings for the project ("plansDirectory": "./.claude/plans" in .claude/settings.json), and the plans are being placed within the project.

I believe the bug no longer exists.

Your naming discipline is exactly right — plans should be meaningful artifacts, not throwaway temp files. But even with configurable paths and names, the core gap remains: plans have no status, no awareness of each other, and no way to survive context compression. What's needed alongside a plansDir setting is a lightweight registry that tracks plan state (draft/approved/completed) and lets new plans reference old ones. I wrote up the full picture in #29445 — naming is one piece, but lifecycle and chaining are what make plans actually persistent across sessions.

The directory half of this shipped in v2.1.9 — use the plansDirectory setting:

~~~json
// .claude/settings.json (project-scoped)
{ "plansDirectory": "./plans" }
~~~

Path is relative to the project root. Default is ~/.claude/plans.

The naming scheme part isn't configurable yet. Leaving this open to track the naming-scheme request specifically — retitling accordingly.

While the official solution being developed, I've shared my own solution here that anyone is welcome to use: https://github.com/dolphinspired/claude-plan-mirror

tl;dr - It's a bash script that hooks into the Write/Edit tools. If the directory is ~/.claude/plans, it determines a timestamped filename and appends it to the file, like this:

<!-- mirror-plan-to: {project_dir_name}_{timestamp}.md -->

The script then copies that plan to Claude's current working directory in the "plans" subfolder. Claude always calls Write for new plans, which will overwrite the global session plan file, causing a new filename to be generated. Plan revisions always call the Edit tool, which will leave the HTML comment marker intact, so the script will write to that filename rather than generating a new one.

Best of all, this is a deterministic, zero-token way to ensure your plans are copied to the project folder. No extra context added for Claude. 🎉

Until this gets built natively, you can achieve most of what you're describing with a PostToolUse hook that auto-syncs plan files into your repo with meaningful names.

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
[[ "$TOOL" != "Write" ]] && exit 0
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
[[ -z "$FILE" ]] && exit 0
if ! echo "$FILE" | grep -qE "$HOME/\.claude.*(plan|PLAN)"; then
    exit 0
fi
git rev-parse --git-dir &>/dev/null || exit 0
PLAN_DIR="plans"
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
[[ -z "$REPO_ROOT" ]] && exit 0
mkdir -p "$REPO_ROOT/$PLAN_DIR"
if [ -f "$FILE" ]; then
    TITLE=$(grep -m1 '^#' "$FILE" 2>/dev/null | sed 's/^#\+\s*//' | head -c 60)
    [ -z "$TITLE" ] && TITLE=$(grep -m1 '.' "$FILE" 2>/dev/null | head -c 60)
    SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' \
         | sed 's/[^a-z0-9-]//g' | sed 's/--\+/-/g' | sed 's/^-\|-$//g' | head -c 40)
    [ -z "$SLUG" ] && SLUG=$(basename "$FILE" .md)
    LAST_NUM=$(ls "$REPO_ROOT/$PLAN_DIR"/PLAN-*.md 2>/dev/null \
             | sed 's/.*PLAN-\([0-9]\+\).*/\1/' | sort -n | tail -1)
    NEXT_NUM=$(printf "%04d" $(( ${LAST_NUM:-0} + 1 )))
    DEST="$REPO_ROOT/$PLAN_DIR/PLAN-${NEXT_NUM}-${SLUG}.md"
    EXISTING=$(grep -rl "<!-- source: $FILE -->" "$REPO_ROOT/$PLAN_DIR" 2>/dev/null | head -1)
    if [ -n "$EXISTING" ]; then
        cp "$FILE" "$EXISTING"
        echo "<!-- source: $FILE -->" >> "$EXISTING"
    else
        cp "$FILE" "$DEST"
        echo "<!-- source: $FILE -->" >> "$DEST"
    fi
fi
exit 0

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{ "type": "command", "command": ".claude/hooks/plan-repo-sync.sh" }]
    }]
  }
}

Or one-liner install: npx cc-safe-setup --install-example plan-repo-sync
Every time Claude writes/updates a plan file in ~/.claude/, this hook automatically copies it to ./plans/PLAN-0001-descriptive-name.md in your repo. The name is derived from the plan's first heading. Subsequent updates to the same plan overwrite in place (tracked via a source comment).
This gives you exactly the workflow you described — plans versioned in your repo with meaningful names you can reference across sessions.