Connect the Scrape.ly MCP server to Claude Code, Cursor or any MCP client: your agent searches the Store, runs a scraper and reads structured results, without leaving the task.
OSS code review support Provided through CodeRabbit’s open-source program.
Contributors
Code, documentation, and issue contributors. Select a portrait to open a GitHub profile or archived credit. Full credits.
Forks & Extensions
Used in the Wild
Skill Registries & Hubs
Bundled snapshots & adaptations
Built something? Open an issue to get listed!
Full list of everyone who made this project better: CONTRIBUTORS.md.
Quick Install
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
All install methods: docs/installation.md.
Before and after /clear
Every coding agent loses its working memory when the context window resets. The plan does not have to die with it.
Built for long-running agent tasks
[!IMPORTANT] Most harnesses ship a to-do list that lives inside the context window. planning-with-files ships a plan that lives on disk, is re-injected every turn, is hash-attested, and can hold the agent's stop until the plan reports complete.
That is the difference between an agent that forgets after
/clear, compaction or a crash and one that resumes at the current phase. In the project's own measurements the plan on disk turned a 13.3-turn re-orientation into 5.0 turns, and the skill won 3 of 3 blind A/B comparisons (numbers and limits). Every mechanism below is a file on disk plus a hook, so it works the same on hour ten as on turn one.
The 3-file pattern
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
The skill keeps your plan, findings, and progress in your project:
your-project/
├── task_plan.md ← phases + checkboxes; the resume point after /clear
├── findings.md ← research notes and decisions, appended as you go
└── progress.md ← session log and test results
Parallel tasks get isolated directories instead: .planning/YYYY-MM-DD-slug/ with the same three files, selected via .active_plan (v2.36.0+). Plain markdown, gitignored by default, no runtime state anywhere else.
The pattern is the one Manus described before Meta acquired it for $2 billion on December 29, 2025, eight months and $100M+ of revenue after launch:
"Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables." — Manus AI
First-class hosts: native plugins
[!TIP] Native integrations load planning context, provide progress reminders and support a completion gate. Commands and model-callable tools depend on the host; Qoder CLI loads the skill and lifecycle hooks without the Claude-specific command prompts. The platform setup guides describe each integration and the standard Agent Skills routes.
🇸🇦 العربية / Arabic
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g
🇩🇪 Deutsch / German
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g
🇪🇸 Español / Spanish
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g
🇨🇳 中文版 / Chinese (Simplified)
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g
🇹🇼 正體中文版 / Chinese (Traditional)
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g
These are real translations, not an English body with a translated description: the SKILL.md prose, the templates, and the user-facing output of check-complete, init-session and session-catchup are all localized. The status tokens stay literal English (**Status:** complete) on purpose, because check-complete.sh matches them with grep -F, so translating them would disable the completion gate.
Since v3.10.0 the variants also ship the full script surface: attestation, the Stop gate, the ledger, phase status and plan-doctor used to be canonical-only, which quietly made every non-English install a subset install. Full details, including what changed on the plugin route in v3.11.0, are in docs/languages.md.
They live under skills/i18n/, one directory deeper than the canonical skill. The install commands above are unchanged, because npx skills add resolves --skill by skill name across the whole repository. The Claude Code plugin scan reads skills/*/SKILL.md without recursing, so the plugin route registers the canonical skill alone and no longer carries five extra descriptions in every session's system prompt. On that route the /plan-ar, /plan-de, /plan-es, /plan-zh and /plan-zht commands read the translated skill from disk instead of invoking it by name.
Note: If your IDE uses the legacy Rules system instead of Skills, see the
legacy-rules-supportbranch.
BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox, BoxLite's official Claude Code integration layer.
How do I stop my coding agent from losing its plan after /clear or a crash?
The plan lives on disk in task_plan.md, findings.md, and progress.md, not only in the context window. At the start of each turn the UserPromptSubmit hook re-injects selected active-plan context, and after a /clear or a new session the skill re-reads project files from disk. This automatic path does not inspect agent transcript stores.
What is the difference between planning-with-files and an agent memory tool?
Agent memory tools (vector stores, knowledge graphs) help an agent recall facts from past sessions. planning-with-files manages active execution state: the phases, status, dependencies, and completion check for the task the agent is working on right now. The problem it solves is planning continuity, not retrieval, and the two are complementary.
How does this prevent context rot?
Context rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected at the start of each turn from disk, the goals and phase status stay in the model's attention window as the conversation grows. This is an implementation of what Anthropic calls structured note-taking: write durable state to files outside the window, then read it back in when needed.
Which coding agents does this work with?
Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent, CodeBuddy, Factory, Mastra, and 70+ others via the SKILL.md open standard (the npx skills installer alone targets 71 agents). Since v3.7.0 the repo also ships the cross-tool .agents/skills/planning-with-files/ layout in-tree, so tools that read the Agent Skills standard path natively (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the current skill from a plain git clone with no per-tool setup. Installation is one command; see Quick Install above.
How does this work with Claude Code's plan mode?
They are complementary stages, not alternatives. Plan mode is where you design and approve the approach before execution. planning-with-files persists the live execution state (phase status, findings, errors, progress) on disk while the work runs and re-injects it every turn. The handoff is one step: after accepting a plan-mode plan, tell the agent to write it into task_plan.md as phases (or invoke /plan and let the skill create the files from it), then execute in normal mode. From that point the hooks keep the phases in the attention window, and the files survive /clear, compaction, and session death.
What happens to the plan files after a task is complete?
They are working memory, not a tracked deliverable. task_plan.md, findings.md, progress.md, and the .planning/ directory are gitignored by default and are not archived automatically: the next task overwrites the root plan, and a slug directory stays in .planning/. Anything worth keeping should be promoted into code, a commit, or a doc. To set a finished named plan aside, set-active-plan.sh --archive <slug> previews the move to .planning/.archive/<slug>/ and --yes applies it; --restore <slug> previews the move back and --yes applies it the same way. With one named plan left, hooks select it automatically again. See After Completion: What Happens to the Plan Files for the full lifecycle and how to retain a completed plan.
How fast are the hooks?
One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from 2.0 to 2.4 seconds before it, and the injected plan block is KV-cache stable by construction. The plan stays in the attention window every turn, and /clear stops being fatal.
Parallel plan isolation (
.planning/YYYY-MM-DD-slug/directories) and Codex session isolation shipped in v2.36.0. Theexperimental/isolated-planningbranch was the earlier prototype; master is now the canonical location.
Long-run safeguards
Everything in that table is opt-in per plan and byte-identical to the previous behavior when no mode marker is set. Details: v3 Long-Running Agent Features and docs/long-running-agent-tasks.md.
Installation routes
Claude Code, plugin route (ships everything: skill, hooks, slash commands):
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Every other agent, one line, 60+ agents via the Agent Skills standard:
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
npm, to pin an exact version into a project or vendor it:
npm install planning-with-files
The package carries SKILL.md, scripts/ and templates/, so this is the route for locking a version into a repo's dependencies or copying the skill in yourself. It does not register hooks on its own.
Pi Coding Agent, same npm package, wired up for you (skill, extension, status bar):
pi install npm:planning-with-files
Hermes Agent (Nous Research), native plugin plus skill bundle, CLI and Desktop:
hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins in