Project Butler addresses the common issue of AI coding assistants lacking persistent memory across sessions, which forces users to re-explain context and decisions repeatedly. It transforms a project folder into a shared source of truth, enabling AI assistants like Claude Code, Cursor, and Codex to function as long-term project teammates. This significantly improves developer productivity by maintaining project state, decisions, and rules consistently.

How It Works

Project Butler employs a 7-component memory stack, organized by stability, to manage project information. This includes stable rules (CLAUDE.md), current project state summaries (PROJECT.md, STRUCTURE.md, UPDATE_LOG.md, DOCS.md), and raw facts (session logs, TODOs). It also features an internal Project Profile System that infers project shape and manages documentation policies, allowing for more robust setup and closing behaviors, including profile-aware normal and full closes.

Quick Start & Requirements

• Installation (Claude Code): Clone the repository into the Claude Code skills directory: git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler.
• Basic Usage: Use natural language commands like /project-butler (setup), end session (save progress), continue (resume), and status (check state).
• Prerequisites: jq is required for session recovery commands (continue, continue full context).
• Tool Compatibility: Native integration with Claude Code. Best-effort support for Cursor (generating .cursor/rules/project-system.mdc) and Codex (generating AGENTS.md). Other assistants can leverage the Markdown files as shared context.
• Updates: Claude Code skills auto-check for updates. Manual checks are required for Cursor/Codex.

Highlighted Details

• Multi-Tool Support: Designed for seamless integration with Claude Code, with compatibility layers for Cursor and Codex, and file-based support for other AI assistants.
• Project Profile System: Enables sophisticated project management, including conversational setup, profile-aware closing, and management of project documentation policies.
• Versioned Update Log: Supports selectable versioning styles (Semantic, Codename, Patch, Date) for milestone-level changelogs.
• File Reorganization: Implements a four-phase file reorganization process to maintain project structure.
• Language Support: Offers English, Chinese, and Bilingual modes for project management files.

Maintenance & Community

The project is actively maintained, with recent updates focusing on multi-tool compatibility and the Project Profile System. Specific community channels (e.g., Discord, Slack) or notable contributors are not detailed in the README.

Licensing & Compatibility

The project is released under the MIT License, permitting commercial use and modification with minimal restrictions.

Limitations & Caveats

Support for Cursor and Codex is described as "best-effort," implying potential limitations compared to the native Claude Code integration. Automatic update checking is primarily a feature for Claude Code skills; other integrations require manual updates. Users who installed prior to v1.7.0 will need to perform an initial manual update.