---
title: "planning-with-files"
type: "tool"
slug: "othmanadi-planning-with-files"
canonical_url: "https://www.graphcanon.com/tools/othmanadi-planning-with-files"
github_url: "https://github.com/OthmanAdi/planning-with-files"
homepage_url: null
stars: 24995
forks: 2120
primary_language: "Python"
license: "MIT"
categories: ["ai-agents", "developer-tools"]
tags: ["agent-skills", "agentic-ai", "autonomous-agents", "claude-code", "multi-agent-systems", "planning"]
updated_at: "2026-07-07T19:46:44.490174+00:00"
---

# planning-with-files

> Persistent file-based planning for AI coding agents and long-running agentic tasks

This repository provides a solution called 'planning-with-files' that ensures crash-proof, context loss-resistant markdown plans for AI coding agents like Claude Code, Codex CLI, and more. It supports multi-agent shared state on disk via SKILL.md standard.

## Facts

- Repository: https://github.com/OthmanAdi/planning-with-files
- Stars: 24,995 · Forks: 2,120 · Open issues: 4 · Watchers: 107
- Primary language: Python
- License: MIT
- Last pushed: 2026-07-07T14:25:59+00:00

## Categories

- [AI Agents](/categories/ai-agents.md)
- [Developer Tools](/categories/developer-tools.md)

## Tags

agent-skills, agentic-ai, autonomous-agents, claude-code, multi-agent-systems, planning

## Related tools

- [ECC](/tools/affaan-m-ecc.md) - The agent harness performance optimization system (★ 226,991)
- [hermes-agent](/tools/nousresearch-hermes-agent.md) - The self-improving AI agent built by Nous Research (★ 210,911)
- [AutoGPT](/tools/significant-gravitas-autogpt.md) - AutoGPT: Build, Deploy, and Run AI Agents (★ 185,420)
- [ollama](/tools/ollama-ollama.md) - Get up and running with Kimi-K2.6, GLM-5.1, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models. (★ 175,664)
- [prompts.chat](/tools/f-prompts-chat.md) - The world's largest open-source prompt library for AI (★ 165,025)
- [JavaGuide](/tools/snailclimb-javaguide.md) - Snailclimb/JavaGuide: 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发 (★ 156,863)
- [langflow](/tools/langflow-ai-langflow.md) - Langflow is a powerful platform for building and deploying AI-powered agents and workflows. (★ 151,311)
- [dify](/tools/langgenius-dify.md) - Production-ready platform for agentic workflow development (★ 148,074)

## README (excerpt)

```text
<div align="center">
<img src="media/v3-banner.png" alt="planning-with-files" width="100%">
</div>

# Planning with Files

> 📣 **New in [v3.0.0](https://github.com/OthmanAdi/planning-with-files/releases/tag/v3.0.0):** opt-in autonomous and gated modes for long-running agent runs, with a completion gate that holds the agent until the plan is actually done. Existing setups change nothing.

> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
>
> **planning-with-files** is a persistent file-based planning skill for **AI coding agents**. It keeps `task_plan.md`, `findings.md`, and `progress.md` on disk so the agent survives **context loss**, `/clear`, and crashes, with an opt-in completion gate that holds the agent until the plan is actually done. It installs across 60+ agents via the SKILL.md standard.

[-brightgreen)](docs/evals.md)












<details>
<summary><strong>💬 A Note from the Author</strong></summary>

To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.

If this skill helps you work smarter, that's all I wanted.

</details>

<details>
<summary><strong>🌍 What the community shipped</strong></summary>

### Forks & Extensions

| Fork | Author | What They Built |
|------|--------|-----------------|
| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation |
| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | Multi-project support, SessionStart git sync |
| [plan-cascade](https://github.com/Taoidle/plan-cascade) | [@Taoidle](https://github.com/Taoidle) | Multi-level task orchestration, parallel execution, multi-agent collaboration |
| [agentfund-skill](https://github.com/RioTheGreat-ai/agentfund-skill) | [@RioTheGreat-ai](https://github.com/RioTheGreat-ai) | Crowdfunding for AI agents with milestone-based escrow on Base |
| [openclaw-github-repo-commander](https://github.com/wd041216-bit/openclaw-github-repo-commander) | [@wd041216-bit](https://github.com/wd041216-bit) | 7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw |

### Used in the Wild

| Project | What It Is |
|---------|-----------|
| [lincolnwan/Planning-with-files-copilot-agent](https://github.com/lincolnwan/Planning-with-files-copilot-agent) | Entire Copilot agent repo built around the planning-with-files skill |
| [cooragent/ClarityFinance](https://github.com/cooragent/ClarityFinance) | AI finance agent framework — Planning-with-Files approach directly credited |
| [oeftimie/vv-claude-harness](https://github.com/oeftimie/vv-claude-harness) | Claude Code harness built on Manus-style persistent markdown planning |
| [jessepwj/CCteam-creator](https://github.com/jessepwj/CCteam-creator) | Multi-agent team orchestration skill using file-based planning |

### Skill Registries & Hubs

| Registry | What It Is |
|----------|-----------|
| [buzhangsan/skill-manager](https://github.com/buzhangsan/skill-manager) | Bilingual (EN/中文) skill hub indexing 31,000+ Claude Code skills — planning-with-files installable one-click. |

*Built something? [Open an issue](https://github.com/OthmanAdi/planning-with-files/issues) to get listed!*

</details>

<details>
<summary><strong>🤝 Contributors</strong></summary>

See the full list of everyone who made this project better in [CONTRIBUTORS.md](./CONTRIBUTORS.md).

</details>

<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>

### Current Version: v3.4.0

| Version | Highlights |
|---------|------------|
| **v3.4.0** | **`PLANNING_DISABLED=1` per-invocation opt-out for one-shot sessions (closes #195, reported by @marcmuon).** One-shot `codex exec` runs (CI review bots, read-only research agents, nested orchestrators) that merely shared a cwd with an incomplet
```

---

**Machine-readable endpoints**

- JSON: [`/api/graphcanon/tools/othmanadi-planning-with-files`](/api/graphcanon/tools/othmanadi-planning-with-files)
- LLM index: [/llms.txt](/llms.txt)
- Full corpus: [/llms-full.txt](/llms-full.txt)

_GraphCanon - The knowledge graph for AI development. https://www.graphcanon.com/_