planning-with-files
Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx sk
planning-with-files is a persistent file-based planning AI sub-agent designed for coding agents and long-running tasks. It maintains three markdown files (task_plan.md, findings.md, progress.md) on disk that survive context resets, crashes, and /clear commands, ensuring agents can resume work without losing their place. The sub-agent re-injects plan data at every turn and includes an optional completion gate to prevent premature stops, following Manus-style working memory patterns.
Key Features
Use Cases
- 01Maintaining plan continuity across context window resets during multi-hour coding sessions
- 02Resuming work after agent crashes or forced context clears without manually re-explaining the task
- 03Tracking research findings and decision rationale in findings.md for complex refactoring projects
- 04Running long-running autonomous agent tasks with deterministic completion gates in gated mode
- 05Coordinating parallel tasks using isolated planning directories with .active_plan selection
- 06Preventing goal drift and repeated errors by persisting failures and decisions to disk
Related Agents
View moreunsloth
Local UI to run and train LLMs and diffusion models, including Qwen3.8, Kimi K3, MiniMax-H3, Gemma 4, DeepSeek-V4, FLUX and more.
codegraph
Pre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent — fewer tokens, fewer tool calls, 100% local
claude-code-best-practice
from vibe coding to agentic engineering - practice makes claude perfect
system_prompts_leaks
Extracted system prompts from Anthropic - Claude Fable 5, Opus 5, Claude Design, Claude Code. OpenAI - ChatGPT GPT-5.6-Sol, Codex. Google - Gemini 3.5 Flash, 3.1 Pro, Antigravity. xAI - Grok, Cursor, Copilot, VS Code, Perplexity, and more. Updated regularly.
planning-with-files — FAQ
What is planning-with-files?+
It's an AI sub-agent that implements persistent file-based planning for coding agents. It stores task plans, findings, and progress in three markdown files on disk so agents can resume work after context resets or crashes without losing their place.
How do I install planning-with-files for Claude Code?+
In Claude Code, type /plugin marketplace add OthmanAdi/planning-with-files then /plugin install planning-with-files@planning-with-files. For other agents supporting the Agent Skills standard, run npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g. For Pi, use pi install npm:planning-with-files.
Which AI clients work with planning-with-files?+
Enhanced support with hooks works in Claude Code, Cursor, GitHub Copilot, Mastra Code, Gemini CLI, Codex, Kiro, Hermes, and others. Standard Agent Skills discovery works in Continue, Pi, OpenClaw, Autohand Code, and 10+ additional platforms for a total of 60+ supported agents.
Do I need API keys or prerequisites to use planning-with-files?+
No API keys are required. You only need npm or npx installed for most installation methods, and an AI agent that supports either plugins (Claude Code) or the Agent Skills standard. The skill itself has no external service dependencies.
Is planning-with-files free to use?+
Yes, it is released under the MIT license and is completely free to use, modify, and distribute. The source code is available on GitHub.
How does session recovery work after running /clear?+
When you run /clear, the skill's session-catchup feature checks the IDE's session store (such as ~/.claude/projects/ for Claude Code), finds when planning files were last updated, extracts potentially lost conversation context, and shows a catchup report. The agent then resumes at the current phase using the persistent files on disk.
How do I install planning-with-files?+
Open the source repository on GitHub and follow its README. planning-with-files is a agent — MCP Agents Market links you directly to the official repo.
Is planning-with-files free?+
planning-with-files is an open-source project hosted on GitHub. Check the repository for its license and any usage requirements.