How Planning‑with‑Files Gives Claude Code Persistent Memory with 3 Files and 4 Hooks

What is planning‑with‑files?

planning‑with‑files is a Claude Code plugin that adds persistent “hard‑disk memory” by writing the task plan, research findings and operation progress to three Markdown files. Claude reads these files at the start of each new session, instantly recalling prior context.

Core idea

The context window acts like RAM—fast but limited and lost on restart—while the file system acts like a disk—slower but unlimited and permanent.

Context window = RAM: fast, limited, lost on restart
File system = Disk: slower, unlimited, permanent

Installation

Method 1 (recommended)

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Method 2 (manual)

mkdir -p .claude/plugins
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files

After installation start a planning session with /plan (or /planning).

Three‑file mode

task_plan.md – goal, staged checklist, current status, error log.

findings.md – knowledge base of code‑base analysis, API usage, pitfalls, technical decisions.

progress.md – log of commands run, files changed, test results.

Example task_plan.md snippet:

# task_plan.md
## 目标
重构用户认证模块，支持 OAuth2.0。
## 阶段
- [x] 阶段 1: 调研现有认证代码
- [x] 阶段 2: 设计新的认证架构
- [ ] 阶段 3: 实现 OAuth2.0 流程（当前）
- [ ] 阶段 4: 迁移现有用户
- [ ] 阶段 5: 测试和上线
## 状态
**当前在阶段 3** - 正在实现授权码流程
## 遇到的错误
Error: redirect_uri mismatch → 原因：配置文件里的回调地址和注册的不一致 → 解决：更新 OAuth 配置

Workflow steps

Create a plan – task_plan.md is mandatory; the plugin aborts if missing.

Enter work loop – before each write/edit/bash operation, the PreToolUse hook reloads the plan.

2‑operation rule – after every two read/search actions, the plugin forces an update to findings.md.

Error persistence – when an error occurs, Claude records the error and its fix in the “遇到的错误” section of task_plan.md.

Completion verification – when Claude tries to stop, the Stop hook checks that all stages are checked off; otherwise it prompts continuation.

Hook mechanism

SessionStart : runs when Claude Code launches, announcing the plugin is ready.

PreToolUse : triggers before any Write/Edit/Bash command, re‑reading task_plan.md.

PostToolUse : runs after a write/edit, reminding the user to update progress.

Stop : activates when Claude wants to end a session, verifying that every stage is completed.

Practical scenarios

Research task – analyzing micro‑service pros/cons, storing goal, findings and progress in the three files.

Bug fix – tracking a TypeError in a login flow, recording error details in task_plan.md and insights in findings.md.

Feature development – adding dark‑mode support, documenting design decisions in findings.md and implementation steps in progress.md.

Comparison with other tools

planning‑with‑files vs TodoWrite

Storage: persistent files vs volatile context.

Cross‑session: ✅ supported vs ❌ not supported.

Progress tracking: checkbox checklist vs basic list.

Error logging: dedicated error table vs none.

Research storage: findings.md vs none.

Auto reminders: hook‑driven vs none.

planning‑with‑files vs Manus AI

Manus AI is a commercial SaaS product; planning‑with‑files is open‑source.

Both use the “file‑system as memory” concept; the plugin implements it inside Claude Code.

planning‑with‑files vs oh‑my‑claudecode

oh‑my‑claudecode focuses on multi‑agent collaboration; planning‑with‑files targets single‑user persistent memory.

Command reference (Claude Code v2.11.0+)

/planning-with-files:plan

(alias /plan) – start a planning session. /planning-with-files:status (alias /plan:status) – view planning progress. /planning-with-files:start (alias /planning) – original start command.

Technical notes

Full hook functionality requires Claude Code v2.1.0 or newer.

Version v2.2.0+ adds automatic recovery after a /clear command.

All files are plain Markdown and can be version‑controlled with Git.

Repository

GitHub:

https://github.com/OthmanAdi/planning-with-files