Stop Claude Code from rewriting your working code.
A plug-and-play toolkit that gives Claude Code persistent pattern memory, autonomous brownfield enforcement, and semantic code search — across all your projects, surviving autocompacts, session boundaries, and reboots.
If you've used Claude Code on a real project for more than a day, you've hit these:
-
Context amnesia. You close the terminal, come back tomorrow, and Claude has no idea what you were doing. Session summaries eat your context window. Autocompacts lose detail.
-
Greenfield drift. Claude's default instinct is to write fresh code from scratch. On a brownfield project — which is most projects after day three — you want it to find and adapt existing patterns, not reinvent them.
-
Lost institutional knowledge. You spend two hours figuring out the right selector, the right approach, the right workaround. Next week, Claude proposes rewriting it. All that trial-and-error knowledge lived only in the context window, and it's gone.
This toolkit installs three custom agents, four slash commands, autonomous hooks, and a semantic search server. Once set up:
- A brownfield enforcer agent automatically checks for existing patterns before every code change — you don't invoke it, it just happens via hooks
- A pattern librarian agent catalogs your codebase and maintains a structured index in persistent memory
- A session resumer agent reloads your project state in seconds when you come back
- Semantic search (via code-memory) lets Claude find code by intent, not just keywords
- Everything persists in
~/.claude/agent-memory/— surviving autocompacts, session restarts, and reboots
git clone https://github.com/YOUR_USERNAME/claude-code-brownfield-toolkit.git
cd claude-code-brownfield-toolkit
chmod +x setup-claude-toolkit.sh
./setup-claude-toolkit.shThen in any project:
cd ~/your-project
claude
/init-project # existing project, first time
/new-project # brand new project from scratch
/resume # returning to a project
/catalog # refresh patterns after major changesThe toolkit installs three hooks in ~/.claude/settings.json:
| Hook | Fires When | What It Does |
|---|---|---|
| PreToolUse (Write|Edit) | Before any code modification | Forces a pattern check via the brownfield enforcer |
| PostToolUse (Write|Edit) | After any code modification | Reminds Claude to save what it learned to memory |
| Stop | Session ending | Ensures all state is persisted to Tasks and memory |
These are invisible. They fire in the background on every code change. You never need to think about them.
| Agent | Role | Runs | Model |
|---|---|---|---|
| brownfield-enforcer | Gates all code changes — searches for existing patterns first | Automatically via hooks | Sonnet |
| pattern-librarian | Catalogs codebase structure, classifies files, maps patterns | On demand (/init-project, /catalog) |
Sonnet |
| session-resumer | Fast context reload from Tasks + agent memory | On demand (/resume) |
Haiku |
All agents have persistent memory stored in ~/.claude/agent-memory/. This memory accumulates across sessions, days, weeks, and projects.
New projects start in LEARNING mode — the enforcer watches and records patterns without blocking. When you've built enough that there are patterns worth protecting, switch to ENFORCING mode:
"Switch this project to brownfield mode"
The transition is seamless because the enforcer has been learning the whole time.
| Phase | Typical Timing | Mode |
|---|---|---|
| Blank slate | Day 0 | LEARNING |
| Building foundations | Days 1-3 | LEARNING |
| Core patterns established | Days 3-5 | Transition point |
| Extending working code | Day 5+ | ENFORCING |
~/.claude/
├── CLAUDE.md ← Global preferences (loaded every session)
├── USERS-MANUAL.md ← Complete usage guide
├── settings.json ← Hooks + MCP config
├── agents/
│ ├── brownfield-enforcer.md ← Auto pattern checker
│ ├── pattern-librarian.md ← Codebase cataloger
│ └── session-resumer.md ← Fast session reload
├── commands/
│ ├── init-project.md ← /init-project
│ ├── new-project.md ← /new-project
│ ├── resume.md ← /resume
│ └── catalog.md ← /catalog
└── agent-memory/
├── brownfield-enforcer/MEMORY.md ← Grows over time
└── pattern-librarian/MEMORY.md ← Grows over time
| Command | When to Use | What Happens |
|---|---|---|
/init-project |
First time in an existing project | Indexes codebase, catalogs patterns, primes enforcer |
/new-project |
Starting from scratch | Sets enforcer to learning mode, records as you build |
/resume |
Returning to any project | Loads state from Tasks + memory, gives compact briefing |
/catalog |
After major changes | Re-scans files, updates pattern index and enforcer |
For long, complex sessions where drift is likely, you can spin up a parallel QA agent:
"Create a team with a brownfield QA agent monitoring all changes"
This runs two Claude agents: one implementing, one checking every change against existing patterns. Costs more tokens but prevents hours of drift on complex sessions.
Requires: Enable Agent Teams in Claude Code via /config → enable agentTeams. Also requires tmux.
- Linux (tested on Linux Mint / Ubuntu) or macOS
- Claude Code CLI installed and authenticated
- Node.js 18+
- Python 3.10+
tmux(installed by setup script)uv/uvx(installed by setup script)
The CLAUDE.md and agent definitions are designed to be generic. Customize them for your workflow:
~/.claude/CLAUDE.md— Add your language preferences, frameworks, communication style~/.claude/agents/*.md— Adjust agent system prompts, change models, add tools~/.claude/settings.json— Add your own hooks, MCP servers, permissions
See the examples/ directory for a real-world configuration used on a large BPO automation project.
No. This toolkit sits on top of Claude Code, not inside it. All built-in features — syntax checking, auto-testing, Plan mode, Explore subagent, auto-memory, compaction — work exactly as before. The toolkit adds a layer of project awareness and institutional memory. Nothing is overridden or replaced.
Q: Will this slow down Claude Code? A: The enforcer adds a pattern check before each code write. On most projects this takes a few seconds. For quick fixes, the overhead is minimal. For large sessions, it saves far more time than it costs by preventing drift.
Q: What if I'm working on a simple script? A: It works fine. The enforcer checks, finds nothing to flag, and Claude writes normally. Zero friction on small projects.
Q: How much token overhead do the agents add? A: The session resumer uses Haiku (cheap and fast). The enforcer and librarian use Sonnet. The main cost comes from Agent Teams if you use them — each teammate is a full context window.
Q: Can I use this on macOS/Windows? A: macOS should work out of the box since Claude Code is native there. Windows with WSL should work but isn't tested. Native Windows is not recommended for Claude Code.
Issues and PRs welcome. This toolkit was born from real-world frustration with context loss and greenfield drift on complex projects. If you've found better patterns or want to improve the agents, please contribute.
MIT — see LICENSE