Persistent Planning
Persistent markdown-based planning for Claude Code -- the context engineering pattern pioneered by Manus AI.
A Claude Code plugin that uses on-disk markdown files as "working memory" for planning, progress tracking, and knowledge storage. Plans persist across sessions and support multiple concurrent tasks.
Why This Plugin?
Claude Code (and most AI agents) suffer from:
- Volatile memory -- in-memory task tracking disappears on context reset
- Goal drift -- after 50+ tool calls, original goals get forgotten
- Hidden errors -- failures aren't tracked, so the same mistakes repeat
- Context stuffing -- everything crammed into context instead of stored on disk
Persistent Planning solves all of these with the same approach that made Manus AI worth $2 billion: use the filesystem as external memory.
The 3-File Pattern
For every complex task, create three files:
.planning/[task-name]/task_plan.md -> Track phases and progress
.planning/[task-name]/notes.md -> Store research and findings
[deliverable].md -> Final output
The Loop
1. Create task_plan.md with goal and phases
2. Research -> save to notes.md -> update task_plan.md
3. Read notes.md -> create deliverable -> update task_plan.md
4. Deliver final output
Key insight: By reading task_plan.md before each decision, goals stay in the attention window. This is how Manus handles ~50 tool calls without losing track.
Installation
v1 → v2 breaking change: the hand-rolled persistent-planning install --scope ... flow was removed. Skills and slash commands are now placed automatically — either by the Claude Code plugin marketplace, or by npm's postinstall symlinking. See CHANGELOG.md for the full migration guide.
Option A: Claude Code Plugin Marketplace (Recommended)
/plugin marketplace add TheGlitchKing/persistent-planning
/plugin install persistent-planning@persistent-planning-marketplace
Option B: Project-level npm install
Pins the exact version in package.json, visible to teammates, CI, and LLMs reading the repo. Postinstall symlinks skills/persistent-planning/ into <project>/.claude/skills/, writes a default .claude/persistent-planning.json (update policy nudge), and registers a SessionStart hook in .claude/settings.json if one is present. Dedup: if the plugin marketplace version is already enabled in ~/.claude/settings.json, the npm hook registration is skipped.
npm install --save-dev @theglitchking/persistent-planning
Option C: Try it (no install)
npx @theglitchking/persistent-planning status
Update management
Each install ships with an update policy. By default the plugin checks npm at session start and prints a one-liner when a newer version is available — no changes made. Opt into automatic updates or silence the check entirely:
# Slash commands
/persistent-planning:policy auto # auto-update on session start
/persistent-planning:policy nudge # one-liner nudge only (default)
/persistent-planning:policy off # silent
# CLI equivalents
npx --no @theglitchking/persistent-planning policy auto
npx --no @theglitchking/persistent-planning status # installed, latest, policy, hook state
npx --no @theglitchking/persistent-planning update # runs npm update + relinks skills
npx --no @theglitchking/persistent-planning relink # re-symlink skills only
Policy resolution order: PERSISTENT_PLANNING_UPDATE_POLICY env var → <project>/.claude/persistent-planning.json → default nudge.
Usage
Quick Start
/start-planning "Your task name here"
This creates:
.planning/
└── your-task-name/
├── task_plan.md # Track phases and progress
└── notes.md # Store research and findings
Session Persistence
Session 1:
/start-planning "Complex feature"
[Work, update plans]
Session 2 (next day):
Read .planning/complex-feature/task_plan.md <- Plans are still here
Read .planning/complex-feature/notes.md <- Notes are still here
[Continue work]
Multiple Concurrent Tasks
/start-planning "Refactor authentication"
-> Creates .planning/refactor-authentication/
/start-planning "Fix memory leak"
-> Creates .planning/fix-memory-leak/
Each task gets its own directory. No conflicts, no overwrites.
Core Principles