Planning With Files
Planning With Files is an open-source framework that provides persistent, file-based planning for AI coding agents and long-running agentic tasks. It addresses the challenge of context loss in LLM-based agents by storing agent plans as markdown files on disk, ensuring that progress survives crashes, context windows resets, or commands like /clear. The core idea is to give an agent a structured set of files (typically plan.md, status.md, and completion gates) that act as external memory, allowing deterministic recovery and continuation of complex multi-step tasks. The system implements a deterministic completion gate using JSON files with check-fields that must be explicitly passed to mark a task as done, preventing false completions. This makes the agent's workflow auditable and reliable. The framework is designed to be agent-agnostic via the SKILL.md standard, which has been adopted by over 60 different AI coding assistants including Claude Code, Codex, OpenCode, and Continue.dev. It includes plugins and skill definitions for seamless integration into various coding environments. Key technical features include non-blocking stop signals, PreCompact parity to optimize context usage before compactions, and robust handling of control characters in gate JSON. Version 3.1.0 introduced significant stability improvements such as stop_hook_active detection and refusal of unattested plan injection in autonomous modes. The project is actively maintained with a large community (23.2k GitHub stars, 2k forks) and receives frequent updates. The framework is particularly suited for autonomous coding agents that need to execute long sequences of operations—such as refactoring, code generation, or multi-file edits—without human intervention. It also supports multi-agent coordination by providing a shared, file-based planning layer that agents can read and update, enabling complex orchestrations of agentic workflows.
- Category
- AI Agents
- Pricing
- Open Source
Problem solved
AI coding agents frequently lose their context when sessions are reset, leading to incomplete tasks or repetitive work. This is especially problematic for autonomous agents that must operate over extended periods without human oversight. Planning With Files solves this by providing a crash-proof, file-based planning mechanism. The agent's plan, progress, and completion state are stored in simple markdown and JSON files, which survive context clears, crashes, and even agent restarts. A deterministic completion gate ensures that tasks are not mistakenly marked as finished, making long-running agentic workflows robust and trustworthy.
Use cases
- Resuming interrupted agentic tasks after a context window overflow or accidental /clear command.
- Building autonomous coding agents that reliably perform multi-step refactoring across dozens of files over several sessions.
- Coordinating multiple AI agents in a shared workspace where each agent reads and updates a common plan file to divide work.
- Implementing audit trails for AI-assisted development by recording every planned step and its completion status in version-controlled files.
- Training or tutorial scenarios where an AI coding assistant demonstrates incremental problem solving that persists across learner sessions.
- Running AI coding agents in CI/CD pipelines where context is ephemeral but the plan must evolve across pipeline stages.
Audience
- Developers
- ML Engineers
- Researchers
- Enterprise
Pros
- Crash-proof persistence: plans survive context loss, crashes, and /clear commands.
- Deterministic completion gate prevents false task completions, ensuring reliable execution.
- Broad compatibility with 60+ AI coding assistants via the SKILL.md standard.
- Simple, human-readable markdown + JSON file structure that is auditable and version-controllable.
- Active community and frequent updates (23.2k stars, 274 commits, v3.1.0).
Cons
- Requires file system access, which may not be available in all agent deployment environments (e.g., some cloud sandboxes).
- The deterministic gate can be too rigid for highly creative or exploratory tasks where success criteria are fuzzy.
- Concurrent access by multiple agents without proper locking might lead to file corruption, though the framework includes some mitigations.
Official website: https://github.com/OthmanAdi/planning-with-files
Canonical LambdaBase page: https://www.lambdabase.com/tools/planning-with-files