← Back to all projects

Planning with Files

Keeps the plan in three files on disk and re-injects them every turn, so it survives a cleared context

Agent skillMIT
Stars
27.8k
Forks
2.3k
Open issues
7
Last commit
28 Oct 2026

What is Planning with Files?

A long task fails in a particular way: the agent had a plan, the context was cleared or compacted, and what comes back is an agent confidently finishing a different job. This skill moves the plan out of the conversation and onto disk — one file for the plan, one for what has been found, one for what is done — and puts them back in front of the agent on every turn. Because the plan is a file, it outlives a clear, a crash and a compaction, and you can read it yourself while the run is going. An optional gate stops the agent declaring completion until the plan says so. The maintainers publish blind A/B results, which is more than most skills offer.

What can you do with Planning with Files?

  • Survive a cleared context — The plan lives on disk rather than in the conversation, so clearing the context, a crash or compaction does not lose what the agent was doing.
  • Put the plan back every turn — A hook re-injects the files on each turn instead of trusting the agent to remember, which is the difference between a plan and a suggestion.
  • Read the plan yourself while it runs — Because they are plain Markdown files in the repository, you can open them mid-run to see what the agent believes it is doing.
  • Keep findings separate from progress — What was learned and what was completed are different files, so a discovery made halfway through does not get lost among the checkboxes.
  • Refuse to finish early — An opt-in gate stops the agent declaring the task done until the plan file agrees, which catches the confident premature completion.

Before you choose Planning with Files

  • It writes working files into your project, so decide early whether they belong in version control — a plan file committed by accident is noise in the history.
  • Re-injecting the plan each turn costs tokens on every turn — cheap against a run that loses its way, expensive on short tasks that never needed a plan.

Star history

29 Aug to 30 Oct · +1.4k

26.4k27.8k

Frequently asked questions

Is Planning with Files free for commercial use?

Planning with Files is released under the MIT licence — OSI-approved open source, which permits commercial use.

How can Planning with Files be deployed?

Planning with Files is available as Runs locally.

Planning with Files
Ask AI
GitHub