Planning with Files
Persistent disk-backed plans for coding agents that must survive context loss.
- Source repo
- OthmanAdi/planning-with-files
- Stars
- ★ 28k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- Shell
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Claude Code user refactoring authentication middleware who needs to resume unfinished regression tests after /clear.
- Not a fit if
- Teams requiring full lifecycle hooks on every platform
- Teams needing plans automatically archived and version-controlled
- Users seeking long-term cross-session knowledge retrieval
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
Planning with Files is a persistent planning skill for AI coding agents and long-running engineering tasks. It maintains task_plan.md, findings.md, and progress.md in the working project to hold phases, research, execution logs, and test results outside the context window. Enhanced integrations use lifecycle hooks to re-inject plan state each turn and to prompt for progress or evaluate completion around compaction and stopping. The repository also includes session recovery, SHA-256 plan attestation, isolated parallel-plan directories, and optional autonomous or gated modes. It ships as a Claude Code plugin or through the Agent Skills installer; platforms without enhanced hooks can still use the file pattern but may not receive the same automation.
For qualifying multi-step work, the skill creates task_plan.md, findings.md, and progress.md. It records phases and checkboxes in task_plan.md, appends research and decisions to findings.md, and logs actions and test results in progress.md. The UserPromptSubmit hook injects the on-disk plan inside an ===BEGIN PLAN DATA=== block; documented Claude Code hooks also include PreToolUse, PostToolUse, Stop, and PreCompact, while Codex configures SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, and Stop. session-catchup examines the active IDE's session store, compares planning-file updates, and produces a catchup report. /plan-attest locks task_plan.md with SHA-256, /pwf --autonomous and --gated enable long-running modes, and .planning/YYYY-MM-DD-slug/ plus .active_plan isolate parallel plans.
- A Claude Code user refactoring authentication middleware who needs to resume unfinished regression tests after /clear.
- A Codex CLI user running a long task with research, code changes, and verification who wants the current phase placed back into context each turn.
- A developer handling several unrelated workstreams who needs .planning/YYYY-MM-DD-slug/ directories to keep each task's state separate.
- A team using Cursor, GitHub Copilot, or Kiro that wants to add documented plan injection and completion checks where host hooks are supported.
- An engineer returning after a crash or compaction who needs a coding agent to reconstruct the active task from disk-based phases, findings, and logs.
How do you install or deploy this agent?
For the Claude Code plugin route, run /plugin marketplace add OthmanAdi/planning-with-files, then /plugin install planning-with-files@planning-with-files. For other Agent Skills-compatible agents, run npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g in a shell; this route needs working npx and network access. The plugin route ships slash commands and hooks. The skill route can be hook-less when project trust is not accepted or frontmatter hooks do not register.
How do you use this agent?
In Claude Code, run /plan or /pwf to create the planning files and start a session; asking the agent to “plan this task” is also documented as a trigger. During work, append findings to findings.md, write actions and test results to progress.md, and check completed phases in task_plan.md. Use /pwf --autonomous or /pwf --gated for the documented long-running modes, and /plan-doctor to diagnose installation and injection. On Pi, the skill creates the files first, then /plan-execute explicitly activates its hooks.
What are this agent's strengths and limitations?
- The three-file workflow keeps active execution state on disk and re-injects it per turn, directly addressing loss after /clear, crashes, and compaction.
- It documents concrete lifecycle-hook integrations for Claude Code and Codex rather than relying only on planning prompts.
- Long-running-task features include session catchup, SHA-256 plan attestation, an append-only JSONL run ledger, and isolated parallel plans.
- It offers both a Claude Code plugin and an Agent Skills route, alongside mirrored integrations for multiple coding environments.
- Full automation depends on host lifecycle hooks; the standard Agent Skills route may provide only the file pattern, and installs can silently lack hooks.
- Planning files are gitignored by default and are not automatically archived; a subsequent root-level task can overwrite the previous plan.
- Session recovery depends on each IDE's local session store and path handling; release notes document past portability issues across platforms and unusual paths.
- The reported 96.7% pass rate and recovery-turn results are author-run internal evaluations of file-pattern fidelity and re-orientation cost, not independent evidence of long-run task success.
How does this agent compare with similar options?
The repository distinguishes this from memory tools: vector stores and knowledge graphs retrieve facts from past sessions, while Planning with Files manages the active task's phases, dependencies, errors, and completion state. It is also positioned as complementary to Claude Code Plan Mode: Plan Mode designs and approves an approach, while this skill persists live execution state after work begins.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Planning with Files This agent | 73 · Some gaps | Agent plugin / skillFree | ★ 28k | 2d ago | Shell | Codex · Claude Code |
| jev-axi Judgment CLI | 90 · Good | CLIFree + model costs | ★ 47 | 13d ago | TypeScript | Claude Code |
| Elephant-Goldfish Model (EGM) | 75 · Good | Agent plugin / skillFree + model costs | ★ 13k | today | Python | Codex · Claude Code |
| Finding-Unknowns Skills | 76 · Good | Agent plugin / skillFree | ★ 364 | 1mo ago | Python | Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: scripts run with least privilege, no network calls, file operations limited to project directory; user confirmation mechanisms (e.g., Pi's /plan-execute); data flow transparency (documented injection format and hooks); sensitive data handling with SHA-256 verification and path isolation; no external dependencies; external effects limited to local file writes; rollback limited (no automatic rollback, but manual recovery possible); source attribution clear (MIT license, author attribution). Deductions: rollback mechanism incomplete, no automatic rollback or backup provided.
Evidence shows: script logic consistent, tests cover sync and cross-project protection; dependency availability high (no external dependencies, uses system tools); failure messages clear (e.g., plan-doctor). Deductions: no obvious flaws, but static review cannot verify runtime behavior.
Evidence shows: targets multiple AI agents and scenarios, provides detailed tiered support; capability boundaries clear (e.g., hook limitations); trigger precision (e.g., /plan command); environment fit broad (supports multiple IDEs and OS). Deductions: some platform support may not be fully verified.
Evidence shows: information architecture clear (README, docs, tests); install notes detailed; naming stable (versioned commands); examples and FAQ rich; known limitations documented; MIT license clear; versioning changelog present; maintenance responsibility clear (author maintains). Deductions: changelog may be incomplete.
Evidence shows: output usability high (clear plan file format); marginal value high (solves context loss problem); cost-benefit reasonable (simple install, low performance overhead). Deductions: cost-benefit not quantified, lacks performance benchmarks.
Evidence shows: claims traceable (README references docs and tests); cross-source corroboration limited (mainly relies on own docs); fact-inference separation (internal benchmarks clearly labeled). Deductions: cross-source corroboration insufficient, lacks independent verification.
- Static review cannot verify runtime behavior; actual testing is recommended.
- Rollback mechanism is incomplete; consider backing up plan files before critical operations.
- Cross-source corroboration is insufficient; consider independent evaluations or community feedback.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v3.28.0 v3.28.0 - Archive and restore finished plans
Release notes excerpt
Added - Opt-in archive and restore for named plans. set-active-plan.sh --archive <id> (PowerShell: -Archive <id>) previews the move to .planning/.archive/<id>/, --yes (-Yes) applies it, and --restore <id> moves a plan back the same way. The directory moves with its sidecars in a single rename. Nothing is deleted and nothing is archived automatically. The shared .active_plan pointer is cleared only when it names the archived plan, and an ID must match the directory name exactly, including case. --list --archived lists archived plans, and the JSON inventory reports `archived_ …View on GitHub ↗ -
v3.27.0 v3.27.0 - Agent-readable plan inventory
Release notes excerpt
Planning agents can request a bounded JSON inventory from the existing listing helpers with --list --json or PowerShell -List -Json. It includes root and named planning-file paths, availability, phase metadata, shared defaults and explicit selection uncertainty. Inventory remains read-only and runs only when requested. Claude plugin commands now follow the selected-plan and initializer contracts. The updates preserve valid pinned legacy roots, initialize from the validated project root, keep status reads compact and delegate attestation to the shipped helpers. …View on GitHub ↗ -
v3.26.0 v3.26.0 - Claude subagent isolation and hook fixes
Release notes excerpt
Added Claude Code can suppress plan context and progress reminders for subagent tool calls with PWF_SKIP_SUBAGENTS=1. The default is unchanged. The opt-in also fails closed when the hook cannot classify its input (#348). Fixed - Preserve existing Codex hook registrations during setup and avoid nested hook directories (PR #345, #343). - Keep Copilot PreToolUse output neutral while using supported context events (PR #346, #344). - Honor PLANNING_DISABLED=1 across Gemini lifecycle hooks, including SessionEnd (PR #347, #329). Thanks …View on GitHub ↗