by Ethan-YS
One folder. Every session knows where you left off. — An open-source methodology for AI-assisted projects.
# Add to your Claude Code skills
git clone https://github.com/Ethan-YS/project-brainGuides for using ai agents skills like project-brain.
Different session. Same brain.
A folder structure + collaboration protocol that lets your AI assistant pick up a project after a context wipe — across new sessions, new windows, new collaborators.
Part of Sprout Labs — Local-first AI memory & agent safety, built independently by Ethan (Independent Product Designer & AI Builder, since 2016). ethanflow.com · LinkedIn · @ethanflow_lab · GitHub
Long-running projects with AI coding assistants (Claude Code, Cursor, Copilot, etc.) hit a counter-intuitive wall:
Larger context windows don't solve the problem. Better information structure does.
A wider window doesn't mean it gets read. Read doesn't mean located. Located doesn't mean prioritized. Without structure, every new session starts with "wait, what's going on here?" — and the AI either reads too much (wasting tokens) or misses the critical pieces.
Symptoms you'll recognize:
project-brain is a structural answer: a brain/ folder layout + a small set of protocols, designed so a fresh AI session can read 2-3 files and be productive.
No comments yet. Be the first to share your thoughts!
In Claude Code, run these two slash commands:
/plugin marketplace add Ethan-YS/project-brain
/plugin install project-brain@sprout-labs
If /plugin isn't exposed in your Claude Code environment (some embedded / SDK contexts strip it), the CLI form does the exact same thing — run from any terminal:
claude plugin marketplace add Ethan-YS/project-brain
claude plugin install project-brain@sprout-labs
That's it. From any project after that, just say:
MAP.md + STATUS.md + (if exists) HANDOFF.mdThe skill handles four workflows: new-project kick-off, startup resume, window-switch handoff, and updates. Auto-trigger requires an explicit user request — it intentionally does not activate just because a brain/ folder exists.
Already installed the old way? If you previously cloned to
~/.claude/skills/project-brain, remove it first:rm -rf ~/.claude/skills/project-brain. The plugin install is the supported path going forward.
Update later:
/plugin marketplace update sprout-labsto fetch the latest version.
If you don't use Claude Code, or you just want the scaffold script:
git clone https://github.com/Ethan-YS/project-brain.git
# Scaffold into your project (defaults to all four AI adapters)
./project-brain/scripts/scaffold.sh /path/to/your/project
# Or pick specific adapters:
./project-brain/scripts/scaffold.sh /path/to/your/project --tools claude,cursor
# Fill in brain/PROJECT.md on day one
# Walk through ⚠️ TODO ⚠️ placeholders
What the scaffold gives you:
| File | Tool |
|---|---|
| brain/ | The project brain (PROJECT/MAP/STATUS/DECISIONS/HANDOFF + topics/) |
| CLAUDE.md | Claude Code instruction file |
| .cursorrules | Cursor instruction file |
| .github/copilot-instructions.md | GitHub Copilot Chat |
| AGENTS.md | Codex CLI / Aider / Continue (AGENTS.md convention) |
When a new AI session opens your project, the auto-loaded instruction file directs it to read brain/MAP.md + brain/STATUS.md. If brain/HANDOFF.md exists, it picks up the previous session's "still-warm-not-yet-written-down" thoughts.
./project-brain/scripts/doctor.sh /path/to/your/project
Read-only structural checks: missing core files, STATUS over 80 lines, decisions without "rejected alternatives," topics/ files not registered in MAP, stale ⚠️ TODO ⚠️ placeholders, etc. Reports issues but never fixes them — that's still your call. See scripts/doctor.sh.
If the empty templates feel abstract, see examples/small-saas/ — a fictional SaaS project ("Quill," a local-first notes app at v0.3) with every file filled in. Reading it is the fastest way to understand what each brain/ file looks like in real use.
brain/
├── PROJECT.md What is this project? What do we explicitly NOT do?
├── MAP.md Module structure + document index ("where do I find X?")
├── STATUS.md Current state — overwritable, soft cap 80 lines
├── DECISIONS.md Decision log — append-only, requires "rejected alternatives"
├── HANDOFF.md Cross-window bridge — what's still in head but not yet written
├── handoffs/ Archive of past HANDOFFs (timestamped)
└── topics/ Per-problem-dimension docs
├── systems/ → "How is this designed?"
├── operations/ → "How do I operate it / what to do each release?"
├── planning/ → "What are we going to build / how to plan it?"
└── feedback/ → "What is reality / users telling us?"
The five core files in brain/ are split by how often they change, not by topic:
| File | Volatility | When to read |
|---|---|---|
| PROJECT.md | Almost never | First contact / scope ambiguous |
| MAP.md | Slowly | Every new session |
| STATUS.md | Frequently (per session) | Every new session |
| DECISIONS.md | Append-only, event-driven | Tracing why something is the way it is |
| HANDOFF.md | Per window-switch | New session start (if exists) |
Why volatility-based? Because mixing low-frequency content with high-frequency content forces the low-frequency content to be re-edited every session — the most common mode of doc rot.
brain/topics/ is divided into 4 dimensions: systems / operations / planning / feedback. A single business module (say, "payment") has its design in systems/, deploy logs in operations/, pricing strategy in planning/, user feedback in feedback/.
Why? Modules grow, shrink, get renamed, get merged. The four problem dimensions are far more stable.
Every entry in DECISIONS.md must include what was considered and rejected, and why. Without this, the file degrades into a worse version of CHANGELOG.md (which already records "what was done"). The unique value of decision logs is the paths not taken — that's where a project's judgment lives.
When the user says "update the project brain":
The AI should not push specialized judgments back ("which files do you want me to update?") — that hands the wrong layer of judgment to the wrong person.
Some projects naturally have parallel independent workstreams (e.g., development + operations + outreach in one product). For these, STATUS and HANDOFF split per workstream:
brain/
├── PROJECT.md ← shared
├── MAP.md ← shared
├── DECISIONS.md ← shared
├── STATUS_dev.md ← split per workstream
├── STATUS_ops.md
├── HANDOFF_dev.md
├── HANDOFF_ops.md
├── handoffs/
│ ├── dev/
│ └── ops/
└── topics/ ← shared
Single-workstream projects ignore this — they keep the default STATUS.md / HANDOFF.md.
This methodology didn't appear from a design session. It evolved through real use across multiple projects — each iteration triggered by friction we hit and couldn't ig