Claude Code writes every plan it makes in plan mode to a Markdown file in ~/.claude/plans, unless you set plansDirectory (All settings), and its cleanup sweep removes files there once they are older than 30 days by default (Explore the .claude directory).

After a few hundred plans that folder is hard to use, and Kamil Jiwa (kjiwa) shared his answer on Hacker News on November 10, 2026: Show HN: Pentimento – status and lineage for your coding agent’s plan files. Pentimento is an MIT-licensed Python CLI in the kjiwa/pentimento repository that writes a status, a parent plan and a project into each plan file and lists them as a table or a tree. What follows is what the author reports, next to what Anthropic documents about the files themselves.

On this page

Where Claude Code keeps plan files

Anthropic’s docs answer the location questions directly:

Question What the docs say
Default folder ~/.claude/plans, used while plansDirectory is unset (All settings)
Move them into the repo Set "plansDirectory": "./plans" in any settings file; the path resolves from the project root (All settings)
When the setting is ignored A path outside the project root, such as "../plans", or a path with a backslash on macOS, Linux and WSL; Claude Code then falls back to ~/.claude/plans (All settings)
File names Named after your prompt plus random words, such as fix-auth-race-snug-otter.md, since Claude Code 2.1.111 (changelog)
Automatic deletion ~/.claude/plans/ is on the list of paths Claude Code deletes once files are older than cleanupPeriodDays, which defaults to 30 days (Explore the .claude directory)
Edit a plan before approving it Press Ctrl+G to open the proposed plan in your default text editor (Permission modes)

On Windows, ~/.claude is %USERPROFILE%\.claude, and CLAUDE_CONFIG_DIR moves the whole folder (Explore the .claude directory). The latest fix in this area, in Claude Code 2.1.325 on November 13, 2026, saves an approved plan edit in the default plans folder, with a warning, when the plansDirectory folder can’t take it (changelog).

The deletion row matters if you want to keep months of plans. Anthropic’s sweep list names ~/.claude/plans/, not a plansDirectory inside your project, and cleanupPeriodDays sets the age cutoff for the sweep (All settings).

The problem the author describes

In his Hacker News post, the author writes that he plans with Claude Code a lot and has hundreds of plan files, from one-off fixes to infrastructure migrations iterated on for weeks, many with subplans and rejected alternatives. Because the names are generated, a file such as a-couple-of-things-splendid-tarjan.md does not tell him whether the work is complete, whether he still cares about it, or whether another plan replaced it.

The README names three kinds of plan worth finding again: a long plan that grew subplans and rejected branches, a finished plan whose findings you will act on later, and a plan from another project that already explains a past decision.

What pentimento writes into each plan

Pentimento reads the plans directory and adds a frontmatter block to each file. The fields, as the README lists them:

Field Values Set by
status not-started, partial, complete, superseded, unknown Derived from a ## Progress section, then checkboxes; superseded only by hand
intent active, queued, someday, abandoned, unset You, with pentimento set
tags Any list You; never derived
parent Another plan id Derived from a reference to another plan, or set by hand
project A project name Derived from the session’s working directory
created A date Derived once

The author treats a superseded plan as a decision record rather than garbage, which is why superseded is the one status no derivation produces or overwrites (README).

Commands from the README

The quick start installs from PyPI and points at the default Claude Code folder through AGENT_PLANS_DIR, which defaults to ~/.claude/plans:

pip install pentimento
pentimento list          # see the corpus; derived fields show without backfill
pentimento backfill      # persist derived fields so they outlive the transcripts
pentimento set some-plan-id --intent active
pentimento list --starred

To park a finished plan and find it again by tag:

pentimento set some-plan-id --add-tag auth --intent someday
pentimento list --tag auth

To pull one thread of subplans back out, and to search earlier decisions across projects:

pentimento tree some-plan-id
pentimento tree some-plan-id --ancestors
pentimento list --title 'github actions|\bGHA\b'
pentimento list --grep 'concurrency group' --status complete
pentimento show some-plan-id --full
pentimento list --status complete --since 1w

pentimento check validates the whole set and exits 1 on any finding, so the integrations guide shows it as a plain CI step. pentimento history <id> lists which Claude Code sessions authored, worked on or only read a plan.

Keeping it current with Claude Code hooks

The author’s integrations guide wires pentimento in with two hooks: a PostToolUse hook on Write|Edit that updates a plan as soon as it is written, and a SessionEnd hook that runs a full sweep. This is the settings snippet from the repository, for ~/.claude/settings.json or a project’s .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pentimento hook"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "pentimento backfill --quiet"
          }
        ]
      }
    ]
  }
}

The guide says pentimento hook always exits 0, so it never blocks a write, and suggests pentimento backfill --dry-run from a terminal to see what a sweep would change before it runs unattended. Anthropic’s hooks reference carries its own warning for any command hook: “Command hooks execute shell commands with your full user permissions”, so review and test each command before adding it (Hooks reference). How hook events and matchers work is covered in Claude Code hooks.

The repository also ships a /plans slash command and a prior-plans skill. The guide says the skill has Claude search every project’s plans with pentimento list --title and --grep before it proposes a change to CI, deploys, auth or cost, and cite the matches in the new plan. For where skills live and how they load, see Claude Code skills.

Limits the author lists

  • One person, one machine. The README says shared or multi-author planning is out of scope.
  • Private formats. project, lineage and modified come from Claude Code’s session transcripts in ~/.claude/projects, and from Cursor’s and Antigravity’s transcripts, all of which the author calls undocumented, private formats. If they change or are missing, these fields fall back to file times and plain references; the frontmatter stays hand-editable (README).
  • Rewrites drop your fields. When an agent rewrites a whole plan file instead of editing it, the frontmatter is replaced and intent, tags, pinned and a hand-set parent are lost (integrations guide).
  • Requirements. Python 3.9 or newer, standard library only (README). PyPI lists version 0.1.26, uploaded on October 28, 2026 (PyPI).

The same tool reads Cursor plans from ~/.cursor/plans and Antigravity plans from ~/.gemini/antigravity/brain by default, according to the reference. For every other folder Claude Code writes, see Where Claude Code stores sessions, settings and memory.