Project Butler
Give Claude Code, Cursor and Codex a shared, file-based project memory that survives between sessions.
- Source repo
- JamesShi96/project-butler
- Stars
- ★ 374
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Shell
- FA score
- 49/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude CodeCodex (Partial support)Claude.ai (Unsupported)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers iterating on one codebase with Claude Code who are tired of re-explaining architecture every session.
- Not a fit if
- Teams wanting a purely graphical tool and no Markdown files in their repo
- Cursor/Codex-only users who need automatic update prompts and the full runtime behavior
- Projects that need a shared database-backed knowledge base rather than in-repo plain-text memory
- Source review
- 49/100 · Major gaps
What does this agent do, and when should you use it?
project-butler is a project memory system for AI coding assistants, shipped as a Claude Code skill installed at ~/.claude/skills/project-butler. It maintains a set of plain Markdown files in the project root — CLAUDE.md, PROJECT.md, STRUCTURE.md, UPDATE_LOG.md, DOCS.md, session-handoff.md, TODO.md, plus docs/, log/ and .claude/ — capturing rules, current state, next steps, milestone history and session logs. The daily loop is four actions: /project-butler to set up, "end session" to save progress, "continue" to resume, "status" to check state. Internally it describes a 7-component memory stack in which raw facts and current state feed the stable rules above them, and since v1.6.0 a Project Profile System tracks document tiers and deferred updates via .claude/project-profile.json and .claude/profile-pending.json, enabling Normal Close and Full Close modes. Native execution relies on the Claude Code skill lifecycle and jq; Cursor and Codex are supported through generated rule files on a best-effort basis.
Running /project-butler creates or fills in CLAUDE.md, PROJECT.md, STRUCTURE.md, UPDATE_LOG.md, DOCS.md, session-handoff.md and TODO.md in the project root, along with docs/, log/ and .claude/project-profile.json, .claude/profile-pending.json, .claude/candidates.md and .claude/.file-snapshot.json. During work it writes session facts into log/, execution items into TODO.md, and candidate rules into .claude/candidates.md, which only become long-term rules after you run review claude. end session summarizes progress, refreshes next steps and writes an UPDATE_LOG.md entry using your chosen version style (Semantic, Codename, Patch or Date). continue and continue full context use jq to parse logs and reconstruct the prior session or the full project trajectory. organize files applies a four-phase Discover / Ask or Plan / Plan / Execute process against STRUCTURE.md with a never-delete cleanup policy. On each invocation the skill also runs git fetch against its own repository, compares local HEAD to origin/main and offers a fast-forward-only pull (silence with PROJECT_BUTLER_NO_UPDATE_CHECK=1).
- Developers iterating on one codebase with Claude Code who are tired of re-explaining architecture every session.
- Users switching between Claude Code, Cursor and Codex who want all three reading one shared source of project truth.
- Teams that want architecture decisions and naming conventions to become reviewed long-term rules instead of chat history.
- Maintainers whose docs are scattered and who want STRUCTURE.md-driven cleanup plus a DOCS.md index.
- Solo developers who return after weeks away and need
continue full contextto rebuild the whole project picture. - Product-oriented projects that need Normal Close versus Full Close to update profile docs within a bounded Scope Plan.
How do you install or deploy this agent?
Install as a Claude Code skill by cloning into the skills directory:
git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butlerRequirements: the Claude Code CLI (native skill execution) and jq (for continue / continue full context session recovery). If you installed before v1.7.0, pull once manually to unlock the auto update check:
cd ~/.claude/skills/project-butler && git pullTo silence the update check:
export PROJECT_BUTLER_NO_UPDATE_CHECK=1On Cursor or Codex, check for updates on demand:
bash "${PROJECT_BUTLER_SKILL_DIR:-$HOME/.claude/skills/project-butler}/scripts/check-update.sh"There is no separate /continue command to install — session recovery is routed through the main skill.
How do you use this agent?
Open any project and initialize project memory once:
/project-butlerFor daily work, four triggers cover most of it:
end session # save progress and next steps
continue # resume next time without re-explaining
status # see current state and the next best stepAdvanced triggers:
continue full context # rebuild the full trajectory after a long break
review claude # review candidate rules
sync wiki # force-refresh PROJECT.md
organize files # clean up new files per STRUCTURE.md
change language # switch English / Chinese / bilingual mode
normal close # save and defer profile updates into the pending queue
full close # align affected profile docs within a Scope Plan
profile setup # create or repair the project profile and baseline docsWhat are this agent's strengths and limitations?
- Output is plain Markdown in the project root, so any assistant that can read files can reuse the same memory without the skill.
- Separates candidate rules from long-term rules: .claude/candidates.md requires explicit user review before anything enters CLAUDE.md.
- Two close modes — Normal Close defers profile-impacting changes, Full Close applies them inside a bounded Scope Plan with confirmation before protected sections.
- Four-phase file organization adopts an explicit never-delete cleanup policy, limiting the risk of automated reorganization.
- Daily update check uses a fast-forward-only git pull that only runs after you choose "Update now", with an HTTPS fallback on failure.
- Full native behavior is tied to the Claude Code skill lifecycle; Cursor and Codex only get best-effort support via .cursor/rules/project-system.mdc or AGENTS.md.
continue/continue full contextrequire jq, so session recovery breaks without it.- The update check runs git fetch inside the skill directory, which makes that directory's git status show it is behind origin/main.
- Installs older than v1.7.0 never receive automatic update prompts until the user pulls once by hand.
- It adds several managed Markdown files and a .claude/ config tree to the project root, which is a structural change for repos with an existing doc system.
- Language modes cover content language and file naming only; there is no evidence of a broader localized UI.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Project Butler This agent | 49 · Major gaps | Agent plugin / skillFree + model costs | ★ 374 | 3mo ago | Shell | Claude Code |
| RecallLoom Project Memory | Insufficient evidence | Agent plugin / skillFree | ★ 153 | 3mo ago | Python | Codex · Claude Code |
| Better Harness | 85 · Good | Agent plugin / skillFree | ★ 2.4k | 16d ago | JavaScript | Codex · Claude Code |
| Emulo | 78 · Good | Agent plugin / skillFree + model costs | ★ 303 | 1mo ago | HTML | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
README describes a daily git fetch update check with explicit user confirmation before any pull, which is good; however the skill writes multiple files into the project root and reads project content, with no sensitive-data redaction guidance for logs that may contain secrets, and dependency (jq, git) security is not assessed. Rollback relies on git and a never-delete policy. Scores mostly 1-2.
Internal description is fairly consistent (commands, file layout, changelog align), but it depends on external tools (jq, Claude Code CLI, git) and gives limited failure-path/error-message detail beyond update-failure fallbacks. Moderate-low.
Clearly targets Claude Code, Cursor, Codex and other file-reading assistants; scenarios and triggers (end session, continue, status) are well defined and capability boundaries (Cursor/Codex best-effort) are stated. Lacks full validation for non-Claude environments.
Information architecture is clear, install steps concrete, known limitations (best-effort update check, pre-v1.7.0 gap) documented, and LICENSE is full MIT text. Examples/FAQ only point to docs/examples.md not present in evidence; naming stability and maintenance responsibility (unverified publisher) are thin; changelog is solid.
Outputs are plain Markdown project-memory files readable by multiple tools, with clear marginal value (cross-session memory); cost-benefit depends on long-term manual use with no quantified evidence, so moderate.
README claims (auto-update, profile system, compatibility) are largely assertions without tests or reproducible evidence; cross-source corroboration limited to README and LICENSE, with weak fact/inference separation.
- The update check runs git fetch daily and may fast-forward pull; though confirmation is required, this can cause unexpected side effects in restricted networks or private repos.
- The skill writes multiple files into the project root and reads project content; logs may contain sensitive data with no redaction or access-control guidance.
- Depends on jq, git, and Claude Code CLI without version constraints or security assessment.
- Publisher identity is unverified; maintenance responsibility and update path are unclear.
- Compatibility and auto-update claims in README lack tests or reproducible evidence.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.7.3 v1.7.3 — Interactive Update Prompt + Project Profile System
Release notes excerpt
First release since v1.4.0. It rolls up everything from v1.4.1 through v1.7.3 — two big additions (Project Profile System, version freshness check), a versioned update log, and a round of test-driven hardening. Highlights 🔔 Version freshness check (v1.7.0 → v1.7.3) project-butler now tells you when your installed copy is behind upstream. Every invocation starts with a cached check (at most one git fetch per machine per day) comparing local HEAD to origin/main. When you're behind, Claude Code asks once — and at most once every 24 hours: ``` …View on GitHub ↗ -
v1.4.0 v1.4.0 — Document Archiving System
Release notes excerpt
Document Archiving System Add a document archiving layer to the project memory stack. New files: - docs/ directory — organized document storage with 6 preset type subdirectories - DOCS.md — document index with metadata (title, status, last updated, sub-doc hierarchy) - references/document-archiving.md — archiving protocol with auto-classification rules 6 preset document types (selected during init, extensible): - PRD, Tech Design, Design Docs, Research, Meeting Notes, Experiments End session integration: …View on GitHub ↗ -
v1.3.0 v1.3.0 — Four-Phase File Reorganization
Release notes excerpt
Four-Phase File Reorganization Replaced template-based file reorganization with a project-understanding-driven flow. Mode A redesign (整理文件): - Four-phase flow: Discover → Ask or Plan → Plan → Execute - Phase 1 (Discover): structural signals first (glob/grep/imports), content reading only for uncertain files, then relationship inference to build a module map - Phase 2 (Ask or Plan): three-tier confidence routing — high confidence skips straight to plan, medium confidence (most common) focuses on specific issues, low confidence asks user about organizing dimensions …View on GitHub ↗
FAQ
Will it overwrite files I already have?
Can I use it without Claude Code?
Can the AI write its own rules into CLAUDE.md?
review claude or check the rules.