I use Claude Code heavily, and every non-trivial task leaves a markdown plan file in ~/.claude/plans. I currently have hundreds of them, spanning one-off bugfixes to multi-month infrastructure migrations:
$ ls ~/.claude/plans | head -5
1-at-16-51-pst-wobbly-grove.md
a-couple-of-things-splendid-tarjan.md
a-previous-plan-noted-wiggly-peach.md
a-recent-commit-to-rosy-umbrella.md
a-recent-exploration-helped-kind-storm.md
Disclosure: I am the author of pentimento, which I cover at the end of this post. Before building it, I surveyed existing tools to see if this gap was already filled—here is what I found.
These are genuinely useful documents — a plan file is often the clearest record of why a piece of work exists. But generated names like a-couple-of-things-splendid-tarjan.md say nothing about whether the work finished, whether you still care about it, or whether a later plan superseded it. At a few dozen files you can hold that state in your head. At a few hundred you can't.
There is also the problem of deferred findings. When executing a task broken across a parent plan and ten subplans, Claude frequently uncovers subtle bugs, architectural gaps, or follow-up ideas at the end of a run. You often want to log those findings without interrupting execution to fix them immediately. But once you move on to subplan 6 or 7, those notes get buried inside completed files, making them nearly impossible to recover later.
What Already Exists
A few adjacent tools exist, but none solve this specific post-hoc organizational problem:
planning-with-files gives an agent a crash-proof way to track its plan while actively working — handling session recovery after /clear or compaction and per-turn plan re-injection. It owns the files it writes during execution. It has nothing to say about a directory of plan files from past sessions.
claude-log-viewer (and similar utility scripts) renders Claude Code's raw JSONL transcript logs. Useful for reading conversation history, but orthogonal to organizing plan files.
dela lists markdown todos via CLI. It's the right shape of tool, but lacks plan lifecycle concepts: no status derived from checkboxes, no concept of plan supersession, and no lineage. It tells you a todo exists, not what happened to it.
I also looked for generic tools under names like "cc-plan-mode" or "plan-files". If a relevant tool exists under another name, I haven't found it yet.
The Gap
None of the above reads a directory of unmanaged plan files after the fact to derive status, lineage, and project context across the whole corpus.
Doing this effectively means treating plain markdown-plus-checkboxes as the interface: never requiring files to have been authored a specific way, and being useful on day one against months of pre-existing files.
What Pentimento Does
pentimento scans a directory of plan markdown files, derives metadata (status from ## Progress checkboxes, intent, parent/child relationships, and project location), and prepends a small YAML frontmatter block to each file.
---
pentimento:
status: partial
intent: active
project: platform
created: 2026-09-01
---
To be explicit about file safety: pentimento mutates your markdown files in-place by inserting this frontmatter block. It uses atomic writes to prevent file corruption and includes a --dry-run flag so you can inspect proposed changes first. It does not create automatic backups, so run it against a clean git state if you want an easy rollback.
Once indexed, it gives you a CLI over the result:
$ pentimento list --intent active
STATUS INTENT PROJECT PLAN TITLE UPDATED
partial active platform auth-rollout Roll out the new auth API 2w
not-started active billing relevance-tuning Tune search relevance 5d
$ pentimento tree
platform
├─ Roll out the new auth API
│ auth-rollout partial active 2026-08-30 2w
│ └─ Auth rollout, take two after the token-refresh bug
│ auth-rollout-v2 not-started active 2026-09-10 3d
The tree view is the most useful part in practice: lineage across supersession answers the questions I ask most often — not just "which plan about this topic is current," but "where did those deferred findings from last week's subplans actually end up?" By grouping subplans under their parent hierarchy, you can audit the full execution chain for unaddressed notes without digging through raw directory listings.
There is no LLM in the runtime loop. It's a zero-dependency Python tool—stdlib only, fully unit-tested, and runs locally against your files.
Where It's Fragile
To figure out which sessions touched which plans, pentimento inspects ~/.claude/projects/*.jsonl — Claude Code's undocumented, unstable transcript logs. This is strictly an enrichment layer: if transcript files are missing or modified, pentimento falls back to file mtimes. You lose exact session history, but status and lineage parsing keep working. The frontmatter remains plain markdown, leaving your files human-readable regardless of tool state.
How are you handling plan drift, session lineage, or stale context across long-running agent projects? If you have a different CLI pattern or a tool I missed, let me know below.
Top comments (0)