GraphCanon updated 4w · GitHub synced 4w · 35 views this month
Decision brief
A tool designed for providing persistent file-based planning in long-running AI coding tasks.
Good fit when
- - When your coding agent needs to retain plans across sessions without context loss.
- - For supporting multi-agent shared state, ensuring all agents have the most updated plan on disk.
Avoid when
- - When you do not need persistent storage for plans, such as short tasks where context is unlikely to be lost.
- - For projects that strictly prohibit the use of external file storage for tracking progress due to security concerns.
- Pricing:
- freemium - Freely available under MIT License; community-supported.
Observed Jul 11, 2026 · Source: enrich:decision_facts
Verify the decision
Maintenance and security
Full trust report- Maintenance
- Very active (2d since push)
- As of 4w
- Provenance
- Not a fork · Personal account
- As of 4w
- Security (OSV)
- No lockfile
- As of 1mo
Public GitHub metadata and optional OSV scans. Signals, not a guarantee. Trust methodology.
Install
pip install planning-with-filesHow it fits your stack(12)
Typed graph edges - alternatives, integrations, successors, and dependencies. Ranked by relationship type, not raw GitHub stars.
Alternative
Integrates
Related
Relationship graph
Optional deeper exploration of typed edges and category neighbours.
claude-mem91k★
mem063k★
OpenHands84k★
open-code-review11k★
open-swe10k★
learn-claude-code74k★
awesome-claude-skills68k★
agentic-awesome-skills44k★
agents38k★claude-mem91k★mem063k★OpenHands84k★open-code-review11k★open-swe10k★learn-claude-code74k★awesome-claude-skills68k★agentic-awesome-skills44k★agents38k★Similar tools
Same-category neighbours not already linked as typed edges.
Evidence and technical details
Sourced facts, taxonomy, compatibility claims, README excerpt, and machine-readable endpoints.
Overview
Provides crash-proof markdown plans that survive context loss in long-running agentic tasks. Supports multi-agent shared state on disk through a deterministic completion gate.
Capability facts
- Languages
- python
Source: github.language · Jul 20, 2026
Categories
Compatibility
Sourced claims from the README excerpt - not unsourced marketing copy.
Source: README excerpt (regex_v1, Jul 20, 2026)
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -gSource link
Source: README excerpt (regex_v1, Jul 20, 2026)
Works with Claude Code, Cursor, Codex, Gemini CLI, Autohand Code, and 40+ agents supporting the [Agent Skills]Source link
Tags
README
Quick Install
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
🌐 Available in 5 other languages
🇸🇦 العربية / Arabic
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g
🇩🇪 Deutsch / German
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g
🇪🇸 Español / Spanish
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g
🇨🇳 中文版 / Chinese (Simplified)
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g
🇹🇼 正體中文版 / Chinese (Traditional)
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g
Works with Claude Code, Cursor, Codex, Gemini CLI, Autohand Code, and 40+ agents supporting the Agent Skills spec.
🔧 Claude Code Plugin (Advanced Features)
For Claude Code-specific features like /plan autocomplete commands:
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
That's it! Now use one of these commands in Claude Code:
| Command | Autocomplete | Description |
|---|---|---|
/planning-with-files:plan | Type /plan | Start planning session (v2.11.0+) |
/planning-with-files:status | Type /plan:status | Show planning progress at a glance (v2.15.0+) |
/planning-with-files:start | Type /planning | Original start command |
/planning-with-files:pwf | Type /pwf | Short alias for /plan; supports --autonomous / --gated init (v3.0.0+) |
/planning-with-files:plan-goal | Type /plan-goal | Run until the plan reports complete by composing with Claude Code /goal (v2.38.0+) |
/planning-with-files:plan-loop | Type /plan-loop | Planning-aware cadence on Claude Code /loop, default 10m tick (v2.38.0+) |
/planning-with-files:plan-attest | Type /plan-attest | Lock task_plan.md with a SHA-256 attestation; --show / --clear (v2.37.0+) |
/planning-with-files:plan-de | Type /plan-de | Start planning in German (also -ar, -es, -zh, -zht) (v2.33.0+) |
Typing /plan prefix-matches every plan* command in autocomplete; /planning-with-files:status autocompletes as /status (the older /plan:status label predates the rename). On the Pi extension the status command is named plan-status.
Alternative: If you want /planning-with-files (without prefix), copy skills to your local folder:
macOS/Linux:
cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
Windows (PowerShell):
Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
See docs/installation.md for all installation methods.
How do I stop my coding agent from losing its plan after /clear or a crash?
The plan lives on disk in task_plan.md, findings.md, and progress.md, not only in the context window. At the start of each turn the UserPromptSubmit hook re-injects the active plan, and after a /clear or a new session the skill re-reads the files from disk (session recovery), so the agent recovers its goals and progress automatically.
How does this work with Claude Code's plan mode?
They are complementary stages, not alternatives. Plan mode designs the approach before execution and leaves an approved strategy in the transcript. planning-with-files persists execution state on disk while the work runs. The handoff is one step: after accepting a plan-mode plan, tell the agent to write the accepted plan into task_plan.md as phases (or invoke /plan and let
For agents
This page has a .md twin and JSON over the API.