OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.

What it solves

This project solves the problem of "context rot" and memory loss in AI coding agents. When an agent's context window fills up, or when a user triggers a /clear command or the agent crashes, the agent typically loses track of its current task, progress, and findings. This tool ensures that the agent's planning state persists on the local disk rather than relying solely on volatile RAM.

How it works

The project implements a "3-file pattern" (task_plan.md, findings.md, and progress.md) that acts as a persistent external memory for the agent. It uses lifecycle hooks to automatically inject these files into the agent's context window at the start of every turn. Because the state is stored as standard Markdown files on the filesystem, it remains available even if the agent resets its session, allowing the agent to resume exactly where it left off.

Who it’s for

It is designed for developers who use AI coding agents (such as Claude Code, Cursor, GitHub Copilot, or various CLI-based agents) for long-running or complex coding tasks that exceed the capacity of a single context window or require resilience against session interruptions.

Highlights

  • Persistent State: Keeps task plans, research findings, and progress logs on disk, surviving /clear commands and crashes.
  • Broad Compatibility: Supports 60+ agents and IDEs via the Agent Skills standard, with native plugins for tools like Claude Code, Qoder, and Hermes.
  • Optimized Performance: Hooks are optimized for speed (sub-300ms) and maintain stability in the model's attention window.
  • Proven Effectiveness: Benchmarked with a 96.7% assertion pass rate and demonstrated success in blind A/B testing.

Related

  • Project
    kleosr/cursorkleosr

    A persistent memory system for Cursor AI agents that uses always-on rules and Markdown files to track project state and goals across sessions.

  • Project
    jsmastery-pro/skills

    A set of modular AI agent skills that implement a professional engineering workflow, moving project state from chat sessions into repository files for persistence and team collaboration.

  • Project
    JamesShi96/project-butler

    A persistent memory system for AI coding assistants that uses a structured Markdown-based memory stack to maintain project context, rules, and progress across sessions.

  • Project
    aerovato/operator-memory

    A self-improving context engine for coding agents that uses Markdown documents to maintain durable, shareable memory of project specs and decisions across sessions.

  • Project
    rohitg00/agentmemory

    A persistent memory layer for AI coding agents that captures and compresses session data to eliminate the need for re-explaining project context across sessions and tools.