explaingit

othmanadi/planning-with-files

📈 Trending★ 20,504PythonAudience · developerComplexity · 3/5ActiveLicenseSetup · easy

TLDR

A Claude Code skill that uses persistent markdown files to track AI coding tasks across sessions, so work never gets lost when conversations reset.

Mindmap

mindmap
  root((repo))
    What it does
      File-based task tracking
      Session persistence
      Multi-plan isolation
    Key features
      Hash attestation
      Session recovery
      Lifecycle hooks
    Use cases
      Resume interrupted coding
      Track multi-step projects
      Audit repositories
    Tech stack
      Claude Code
      Markdown files
      SHA-256 hashing
    Supported platforms
      GitHub Copilot
      Gemini
      Mastra Code

Things people build with this

USE CASE 1

Resume a multi-day coding project after your Claude Code session ends without losing progress.

USE CASE 2

Track parallel tasks across different parts of a codebase with isolated plan files.

USE CASE 3

Lock completed task plans with hash attestation to prevent accidental modifications.

USE CASE 4

Audit a GitHub repository by maintaining a persistent checklist of findings and fixes.

Tech stack

PythonClaude CodeMarkdownSHA-256

Getting it running

Difficulty · easy Time to first run · 5min
Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

In plain English

Planning with Files is a skill, meaning a packaged behavior that plugs into AI coding assistants such as Claude Code and GitHub Copilot, that adds a structured planning workflow to those assistants. The README pitches it as working the way Manus, an AI agent company Meta acquired for two billion dollars, works: the agent writes its plan to a markdown file on disk, keeps it updated, and reads it back as it works, rather than holding the whole plan only in memory. The core idea is persistent planning. When you start a task, the skill creates a task plan in a markdown file, the assistant ticks off and edits items as it makes progress, and if the session is cleared the plan can be picked up again later. The repository's scripts and lifecycle hooks handle starting a session, isolating parallel plans so several can run side by side, recovering after a clear, and hooking into events like SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop. A recent version adds a SHA-256 attestation step that locks the plan file and a hook that blocks tampering. Someone would use Planning with Files to get more reliable multi-step work out of an AI assistant: planning a refactor, doing a long audit, or running parallel projects without losing context. The README lists installations across many editors and AI assistants including Claude Code, Copilot, Codex, Gemini, Factory, Hermes, Kiro, and Mastra Code, with translated variants in Traditional Chinese, Arabic, German, and Spanish. The repository's primary language is Python, the skill ships under the MIT license, and the README notes a reported 96.7 percent benchmark pass rate. The full README is longer than what was provided.

Copy-paste prompts

Prompt 1
Set up planning-with-files in my Claude Code workspace so I can track tasks in a persistent markdown file that survives session resets.
Prompt 2
Show me how to use the /plan-attest command to lock my task_plan.md with a SHA-256 hash and prevent tampering.
Prompt 3
Integrate planning-with-files with GitHub Copilot so my coding agent can resume work across multiple sessions.
Prompt 4
Create a multi-plan workflow using planning-with-files to track separate task lists for different features in my project.
Prompt 5
How do I extend planning-with-files to support multi-agent orchestration like the community forks do?
Open on GitHub → Explain another repo

Generated 2026-05-21 · Model: sonnet-4-6 · Verify against the repo before relying on details.