project-butler
Make AI coding agents remember your project between sessions.
project-butler helps Claude Code, Cursor, Codex, and similar AI coding assistants behave like long-term project teammates instead of starting from scratch every session.
For normal use, you only need four actions:
/project-butler Set up project memory
end session Save progress and next steps
continue Resume next time
status Check where the project stands
For projects that need stronger product, architecture, roadmap, research, or eval alignment, project-butler can also create a Project Profile during setup and offer profile-aware Normal Close / Full Close behavior.
Quick Start
Install as a Claude Code skill:
git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler
Open any project and set up project memory:
/project-butler
Work normally. At the end of a work session:
end session
Next time, resume without re-explaining the project:
continue
That is enough for daily use. For Cursor, Codex, and other assistants, see Tool Compatibility.
Updating project-butler
The skill auto-checks for updates on every invocation. Once per day per
machine, it runs git fetch against its own repo and compares local
HEAD to origin/main. If behind, the next response carries this
banner block:
VERSION_NOTICE: project-butler is N commits behind upstream.
→ Update: cd <path> && git pull
→ Silence: PROJECT_BUTLER_NO_UPDATE_CHECK=1
The banner disappears on the next invocation after you pull — cache is keyed on commit SHA, not just time.
Side effect on git status: after the auto-fetch, git status
inside the skill directory may show "behind origin/main by N commits".
This is expected and harmless — the skill never modifies the working
tree.
Silencing: export PROJECT_BUTLER_NO_UPDATE_CHECK=1. Only the
literal value "1" silences — =0, =false, or empty does not
silence (counter-intuitive but intentional).
Debugging missing banners: from an external shell only, run the
shared update-check script with
PROJECT_BUTLER_UPDATE_CHECK_DEBUG=1. Never enable debug inside
Claude Code — CC captures stderr into the LLM context and debug output
will leak into responses.
Cursor / Codex: these tools do not have Claude Code's skill lifecycle, so update checks are manual/on-demand:
bash "${PROJECT_BUTLER_SKILL_DIR:-$HOME/.claude/skills/project-butler}/scripts/check-update.sh"
Reach limitation: if you installed project-butler before v1.7.0, you do not have this auto-check feature yet. Pull once manually:
cd ~/.claude/skills/project-butler && git pull
After that, future updates are announced automatically.
Why It Exists
AI coding assistants are powerful in one session and forgetful across sessions. If any of these sound familiar, project-butler is for you:
- "I had to re-explain the architecture again." Each new session starts with missing context.
- "What did we decide about naming conventions last week?" Decisions disappear into chat history.
- "The README and TODOs keep drifting from reality." Project state stops matching the files.
- "The AI keeps violating rules I already explained." Rules live in your head instead of in project memory.
- "I switch between Claude Code, Cursor, and Codex." Different tools need one shared source of truth.
project-butler turns a project folder into that source of truth, so the next AI session can pick up where the last one stopped.
Main Commands
All triggers are natural language. Use slash commands only for first-time setup.
| Command | Use it when |
|---|---|
/project-butler |
Set up or upgrade project memory. |
end session / we're done |
Save progress, refresh next steps, and record important changes. |
continue / continue from last time |
Resume the previous session without re-explaining context. |
status / where are we |
Get the current project state and the next best step. |
Advanced Commands
| Command | Use it when |
|---|---|
continue full context |
Rebuild the full project trajectory after a long break or assistant switch. |
review claude / check the rules |
Review candidate project rules before they become long-term rules. |
sync wiki / update overview |
Force-refresh PROJECT.md. |
organize files |
Clean up new files according to STRUCTURE.md. |
change language |
Switch project management files between English, Chinese, and bilingual mode. |
normal close |
Save the session and defer profile-impacting updates into the pending queue. |
full close |
Align affected profile docs now with a bounded Scope Plan. |
profile setup / foundation repair |
Create or repair the project profile and baseline reference docs after confirmation. |
Session recovery (continue / continue full context) is routed through project-butler internally. There is no separate /continue command to install.
What It Maintains
Run /project-butler once. It maintains these plain Markdown files in your project:
project-root/
├── CLAUDE.md <- Project rules / constitution
├── PROJECT.md <- Current project wiki
├── STRUCTURE.md <- File organization rules
├── UPDATE_LOG.md <- Milestone-level changelog
├── DOCS.md <- Document index and metadata
├── session-handoff.md <- Cross-session handoff
├── TODO.md <- Execution checklist
├── docs/ <- Archived project documents
├── log/ <- Session logs
└── .claude/
├── candidates.md <- Candidate rules for review
├── project-profile.json <- Project profile config
├── profile-pending.json <- Profile pending/debt queue
└── .file-snapshot.json <- File organization snapshot
The core files are plain Markdown, so other tools can read them even when they do not run the skill natively.
What that means in practice:
- Keeps the current project state readable.
- Keeps next steps clear between sessions.
- Keeps project documents indexed and findable.
- Records milestone changes so the project has a clear history.
- Keeps new files from drifting into random folders.
- Preserves long-term rules only after user review.
Project Butler also keeps a small machine-readable profile so the assistant can understand which long-lived docs matter, which sections are protected, and which profile updates have been deferred.
Tool Support
| Tool | Status | How it works |
|---|---|---|
| Claude Code | Native skill | Install this repo under ~/.claude/skills/project-butler and run /project-butler. |
| Cursor | Project rules, best-effort | project-butler can generate .cursor/rules/project-system.mdc, which points Cursor at the same project memory files and mirrors the main triggers. |
| Codex | AGENTS.md, best-effort |
project-butler can generate AGENTS.md, which points Codex at the same project memory files and mirrors the main triggers. |
| Other AI assistants | File-based | Any assistant that can read project files can use the project memory as shared context. |
See docs/compatibility.md for details and caveats.
How It Works
Internals: The Memory Stack
project-butler uses a 7-component memory stack internally, organized by stability:
Stable rules
┌─────────────────────────────────────┐
│ CLAUDE.md / project rules │ <- Human-reviewed principles
│ ↑ candidates collected by AI │
└─────────────────────────────────────┘
↑ distilled from work
Current state
┌─────────────────────────────────────┐
│ PROJECT.md │ <- What the project is now
│ STRUCTURE.md │ <- Where files belong
│ UPDATE_LOG.md │ <- Milestone-level changes
│ DOCS.md │ <- Document index
│ .claude/project-profile.json │ <- Profile config
│ .claude/profile-pending.json │ <- Profile debt queue
└─────────────────────────────────────┘
↑ summarized from facts
Raw facts
┌──────────────────────┐ ┌───────────────────────┐
│ log/ │ │ TODO.md │
│ What happened │ │ What needs doing │
└──────────────────────┘ └───────────────────────┘
↓
session-handoff.md <- Where the next session should resume
Bottom feeds top. Top constrains bottom.
- Session logs capture what happened.
- Handoff tells the next assistant where to resume.
- Project wiki summarizes the current state.
- TODOs keep execution visible.
- Rules / constitution preserve decisions that should keep guiding the project.
- Update log records significant changes at milestone level.
- Structure rules keep files from drifting into chaos.
- Document index keeps project documents organized under
docs/. - Project profile tracks project shape, document tiers, document policies, pending profile updates, and review queue items.
Project Profiles
Project Profile System is internal profile-aware behavior for setup and close. Fresh setup stays conversational and can remain lightweight by creating only minimal co