planning-with-files gives a coding agent a memory that outlives its context window. It keeps three plain Markdown files in your project, task_plan.md for phases and checkboxes, findings.md for research and decisions, and progress.md for the session log, and uses the agent's lifecycle hooks to re-inject the current plan every turn. After /clear, a compaction or a crash, the agent picks up at the current phase instead of re-reading the whole project.
It goes further than a to-do list: parallel tasks get their own .planning folders, plans can be hash-attested so the agent cannot quietly rewrite them, and an optional completion gate can hold the agent's stop until the plan reports done. It installs into Claude Code as a plugin and into Codex, Cursor, Gemini CLI, Copilot, OpenCode, Kiro and dozens more through native plugins or the standard skills folders, with full translations in five languages.
The idea is the file-based planning pattern Manus described, packaged so any agent can use it. It is MIT-licensed, at about 27,700 stars and v3.25.2 when scanned. For a short task it is overhead; it pays off on long, multi-session work.
- Repository: github.com/OthmanAdi/planning-with-files
- Licence: MIT (MIT License)
- Language: Python. Stars: 27.7K. Forks: 2,300. Last push: Oct 24, 2026.
- Scan: safe, Oct 26, 2026, commit dcdfb27
Who it is for
Developers who run Claude Code, Codex or Cursor on long tasks and keep losing progress to context resets, and anyone who wants an agent's plan in files they can read and edit.
Getting started
1. Claude Code: add the marketplace
/plugin marketplace add OthmanAdi/planning-with-files2. Claude Code: install the plugin with its hooks
/plugin install planning-with-files@planning-with-files3. Other agents, through the Skills CLI
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -gThe /plugin commands are typed inside Claude Code, not a shell. Per-agent guides for Cursor, Codex, Gemini CLI, Copilot, OpenCode and the rest are in the repository's docs folder.
Safety scan
We cloned OthmanAdi/planning-with-files at commit dcdfb27 on Oct 26, 2026 and ran the checks described on the GitHub Tools page: credential patterns, decode-and-execute code, install-time scripts, committed binaries, risky CI workflows, every host the code talks to, known vulnerabilities in pinned dependencies, and project hygiene. A person read every hit. This is what we found.
- No secrets, no pattern hits, no committed binaries and no bare-IP URLs across 769 files and about 218,000 lines, most of them copies of the same scripts for each supported agent. The only outside host in the code is github.com.
- Installing the Claude Code plugin registers hooks that run hooks/claude-hook.sh on session start, on every prompt and before Write, Edit, Bash, Read, Glob and Grep calls, each with a 10-second timeout. They read the plan files and print context for the agent; they do not fetch anything.
- scripts/session-catchup.py can read your agent's own session records (for Claude Code, ~/.claude/projects) to recover where a session left off. The plugin says this only happens on explicit request and stays on the machine, which matches the code: it has no network code.
- The 58 known advisories (3 critical) are in the lockfiles of three optional host packages, for DeepSeek Harness, OpenCode and Pi, and are mostly test tooling (Vitest, Tinypool, Vite). Nothing in the core skill has dependencies.
- 3 workflows, none using pull_request_target, and both third-party actions are pinned to commits. Security policy, licence and contributing guide present; no Dependabot or CodeQL.
What the scanner counted
| Check | Result |
|---|---|
| Secrets | None found. |
| Suspicious code | None found. |
| Install-time code | 1 npm lifecycle script. 3 installer scripts |
| Committed binaries | None. |
| CI workflows | 3 workflows. None use pull_request_target. 0 of 2 third-party actions pinned to a tag rather than a commit. |
| Network hosts | 1 distinct host referenced from source; most often github.com. No URLs to bare IP addresses. |
| Known vulnerabilities | 58 advisories across 560 pinned packages: 3 critical, 24 high, 27 moderate, 4 low. .dsh/packages/dsh-planning-with-files/package-lock.json: 124 packages, 16 advisories; .opencode/packages/opencode-planning-with-files/package-lock.json: 395 packages, 27 advisories; .pi/skills/planning-with-files/extensions/planning-with-files/package-lock.json: 233 packages, 46 advisories. |
| Project hygiene | Has security policy, licence file, contributing guide. Missing automated dependency updates, CodeQL. |
| OpenSSF Scorecard | Not scored: the project is not in Scorecard's weekly index. |
The raw findings
Every hit the scanner wrote out, with a link to the exact line at the scanned commit. Secrets candidates are redacted.
npm lifecycle scripts (1)
.pi/skills/planning-with-files/package.jsonprepack:node scripts/verify-shell-line-endings.mjs
Installer scripts (3)
Worst known vulnerabilities (24 of 58)
| Advisory | Severity | Package | Summary |
|---|---|---|---|
| GHSA-5gmw-xhrv-c9v3 | critical | tinypool@1.1.1 | Tinypool: Prototype Pollution gadget in worker options leads to Remote Code Execution |
| GHSA-85c8-ppgw-ccpr | critical | tinypool@1.1.1 | Tinypool: Prototype Pollution Gadget to RCE in run() options |
| GHSA-5xrq-8626-4rwp | critical | vitest@2.1.9 | When Vitest UI server is listening, arbitrary file can be read and executed |
| GHSA-587h-7wmj-h5pm | high | vite@5.4.21 | launch-editor: `fs.existsSync()` existence check can be bypassed on Windows |
| GHSA-fx2h-pf6j-xcff | high | vite@5.4.21 | vite: `server.fs.deny` bypass on Windows alternate paths |
| GHSA-mrhx-c7xc-m3w5 | high | zod@4.6.5 | Zod can exhaust memory while validating oversized constrained collections |
| GHSA-xjj6-f33q-929c | high | undici@8.11.2 | undici vulnerable to Denial of Service via unhandled error on excessive content-encodings |
| GHSA-ch52-4w7c-c8xp | high | http-cache-semantics@4.2.0 | http-cache-semantics max-stale handling can disclose cross-user cached responses |
| GHSA-68fv-2mgg-jv7q | high | source-map-js@1.2.1 | source-map-js allows event-loop denial of service through indexed source-map section offsets |
| GHSA-4qx8-w7c3-pj3p | high | toml@4.3.0 | toml-node: Quadratic-complexity DoS via many array-of-tables headers in toml.parse() |
| GHSA-9j65-hcg3-gc64 | high | toml@4.3.0 | toml-node: Quadratic-complexity DoS via long dotted keys or table paths in toml.parse() |
| GHSA-9qmh-m7c6-f92p | high | toml@4.3.0 | toml-node: Uncontrolled resource consumption (CPU DoS) via unbounded-length integer literals in toml.parse() |
| GHSA-xjj6-f33q-929c | high | undici@6.29.0 | undici vulnerable to Denial of Service via unhandled error on excessive content-encodings |
| GHSA-mrhx-c7xc-m3w5 | high | zod@4.1.8 | Zod can exhaust memory while validating oversized constrained collections |
| GHSA-3jxr-9vmj-r5cp | high | brace-expansion@5.0.6 | brace-expansion: DoS via exponential-time expansion of consecutive non-expanding {} groups |
| GHSA-6j4f-fj2g-mc7p | high | brace-expansion@5.0.6 | brace-expansion: DoS via uncontrolled recursion in parseCommaParts causing stack exhaustion |
| GHSA-mh99-v99m-4gvg | high | brace-expansion@5.0.6 | brace-expansion: DoS via unbounded expansion length causing an out-of-memory process crash |
| GHSA-qhr7-859c-m2p7 | high | brace-expansion@5.0.6 | brace-expansion: DoS via uncontrolled recursion on nested brace groups causing stack exhaustion |
| GHSA-rgw5-rvv9-x895 | high | brace-expansion@5.0.6 | brace-expansion: DoS via unbounded intermediate arrays, bypassing the CVE-2026-14257 mitigation |
| GHSA-4cwx-7wf7-3272 | high | undici@8.5.0 | undici vulnerable to cross-user information disclosure and parse-time crash via degenerate private cache directives |
| GHSA-rfgv-xxqx-mfg5 | high | undici@8.5.0 | undici vulnerable to Denial of Service via unrequested WebSocket subprotocol |
| GHSA-w293-vg96-wgc3 | high | undici@8.5.0 | undici vulnerable to TLS certificate validation bypass via dropped connect options in BalancedPool |
| GHSA-xjj6-f33q-929c | high | undici@8.5.0 | undici vulnerable to Denial of Service via unhandled error on excessive content-encodings |
| GHSA-mrhx-c7xc-m3w5 | high | zod@3.25.76 | Zod can exhaust memory while validating oversized constrained collections |
By the numbers
| Stars | 27.7K |
|---|---|
| Forks | 2,300 |
| Contributors | 67 |
| Commits | 565 |
| Open issues | 8 |
| Open pull requests | 3 |
| Releases | 123 |
| Latest release | v3.25.2 |
| Licence | MIT |
| Main language | Python |
| Project age | 9 months |
| Last push | Oct 24, 2026 |
| Tracked files | 769 |
| Lines of code | 217.6K |
| Checkout size | 32 MB |
Lines by language: Python 74.2K, Shell 69.4K, PowerShell 35.4K, Markdown 29.3K, TypeScript 7,594, JSON 934.
Questions
Is planning-with-files free?
Yes. It is MIT-licensed and free in every supported agent. The only cost is the small amount of extra context the re-injected plan uses each turn.
Where does planning-with-files store my plans?
In your project folder, as task_plan.md, findings.md and progress.md, or under .planning/ for parallel tasks. They are plain Markdown, gitignored by default, and nothing is stored anywhere else.
Does it work outside Claude Code?
Yes. It has native plugins for OpenCode, Hermes Agent and DeepSeek Harness, hook-based setups for Cursor, Codex, Gemini CLI, Copilot and others, and works as a standard skill in any agent that reads skills folders.
This post is part of GitHub Tools, where every repository is cloned and scanned before it is written up. The scan is a snapshot of one commit on one day; the repository has moved on since, so check it before you install.