AgentArmorHQ
Sign in
  • AgentArmor teamTeam3d agoNeeds helpSolved

    How do I store Claude Code plan files inside my repo instead of ~/.claude/plans?

    Claude Code writes plan files to a hidden folder in the home directory with random names, outside the project. Users want plans stored in the repo with meaningful, predictable file names. Is there a setting for the location, and can the names be controlled?

    Originally asked on GitHub: https://github.com/anthropics/claude-code/issues/12619

    6 answers

    • Best answerAgentArmor teamTeam3d ago

      Partly fixed. The location is configurable since Claude Code v2.1.9 via the plansDirectory setting, which the maintainer confirmed. The naming scheme is still not configurable and the issue remains open for that part.

      To keep plans in the repo, add this to the project's .claude/settings.json:

      json
      { "plansDirectory": "./plans" }

      The path is relative to the project root. The default is ~/.claude/plans. A commenter on v2.1.62 confirmed that using "plansDirectory": "./.claude/plans" places plans inside the project.

      File names are still random. Workarounds reported in the thread:

      • A PostToolUse hook on Write that copies plans from ~/.claude/ into the repo, renaming them to PLAN-NNNN-<slug>.md based on the first heading. It tracks the source path with a comment so later edits overwrite the same copy. This is community code and was not verified by the maintainers.
      • A hook that appends a <!-- mirror-plan-to: ... --> marker so later edits keep the same target name.

      These hooks copy files rather than rename them, so the repo may end up with duplicate plans. Review the hook code before running it, since it executes shell commands on every write.

      Did this work for you?
    • AgentArmor teamTeam3d ago

      What a GitHub user tried on GitHub (Didn't work)

      Reporter wanted plans stored in the repo at plans/ with names like PLAN-xxxx-description.md, configured via .claude/settings.json, instead of the random home directory location.

      Source: https://github.com/anthropics/claude-code/issues/12619 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam3d ago

      What @bcherny tried on GitHub (Worked)

      Maintainer set "plansDirectory": "./plans" in project .claude/settings.json; relative to project root. Directory setting shipped in v2.1.9; naming scheme not yet configurable.

      Source: https://github.com/anthropics/claude-code/issues/12619#issuecomment-4042990995 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam3d ago

      What @Perlover tried on GitHub (Worked)

      Commenter on v2.1.62 used "plansDirectory": "./.claude/plans" in .claude/settings.json and reported plans were written into the project.

      Source: https://github.com/anthropics/claude-code/issues/12619#issuecomment-3972163185 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam3d ago

      What @yurukusa tried on GitHub (Outcome unclear)

      PostToolUse hook on Write that copies ~/.claude plan files into ./plans as PLAN-NNNN-slug.md, taking the slug from the first heading and tracking the source with a comment.

      Source: https://github.com/anthropics/claude-code/issues/12619#issuecomment-4147612094 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam3d ago

      What @dolphinspired tried on GitHub (Outcome unclear)

      Bash PostToolUse hook that appends a timestamped mirror-plan-to HTML comment to new plans and copies them into the project plans folder on each edit.

      Source: https://github.com/anthropics/claude-code/issues/12619#issuecomment-4089988950 (opens external site)

      Did this work for you?

    Add your answer or comment