ᗺB - Brain Bootstrap

Your AI coding assistant is brilliant.
It just forgets everything, ignores your rules, and breaks your conventions.
Brain doesn't hope the AI behaves — it makes it. Permanently.

_{by y-abs · no third-party installs without your explicit approval}

What This Is  ·  Guarantees  ·  Before & After  ·  Real Example  ·  5 Min Setup  ·  Under the Hood  ·  200+ Files  ·  Gets Smarter  ·  Guardrails  ·  Superpowers  ·  Make It Yours  ·  FAQ  ·  Contribute

💡 What This Is

Brain Bootstrap is a project configuration template — a ready-made .claude/ folder you install once into your repo. It gives Claude Code persistent memory, enforced guardrails, and 31 built-in workflows so your AI assistant finally knows your project and stops repeating the same mistakes every session.

The problem it solves:

You ask Claude to add a feature. It uses npm run build — but you use yarn turbo build. It installs date-fns even though @company/utils already has formatDate(). It edits tsconfig.json to silence a type error — the file you explicitly said never to touch.

You correct it. It apologizes. Next session: same mistakes.

Claude Code is stateless by design — each session starts blank. So you end up re-explaining your stack, re-enforcing the same rules, re-correcting the same errors. Every. Single. Session. You become the AI's memory.

What Brain Bootstrap gives you instead:

• Persistent memory — conventions, architecture, past mistakes embedded once and never forgotten
• Enforced rules — bash hooks that block violations before they run, no AI judgment involved
• Ready-to-use workflows — 31 slash commands (/plan, /review, /mr and 28 more), 18 skills, 5 specialist subagents
• Self-updating knowledge — the knowledge layer grows with your codebase, session by session

Install once. Correct once. It never happens again.

🔒 Not Suggestions — Guarantees

Every other instruction system hopes the AI complies. Brain doesn't hope — it enforces.

Corrections become permanent rules. Forbidden patterns get blocked before they run — by deterministic bash scripts, not AI judgment. The knowledge base updates itself as your codebase evolves. The same mistake cannot happen twice.

You stop babysitting — the AI just knows.

✨ What Changes When You Add a Brain

Every AI coding tool reads instructions. None of them enforce those instructions on themselves. You write "never edit tsconfig.json" — it edits tsconfig.json anyway. You correct it — same mistake next session.

Instructions are text. Text is advisory. Advisory gets overridden. Brain replaces text with mechanisms — hooks that block before execution, memory that persists across sessions, knowledge that stays current:

After a few sessions, your AI will know things about your codebase that even some team members don't.

👀 See It In Action — Real Project, Real Diff

Skeptical? Here's the exact output on a TypeScript / Go / Kafka stack — every file Brain added, zero manual editing:

→ kafka-message-scheduler-admin: before vs. after Brain Bootstrap

🎯 200+ files isn't complexity. It's the minimum architecture where instructions become guarantees.

🚀 Get Started in 5 Minutes

Step 1 — Install the template

Prerequisites: git, bash ≥ 3.2, jq (install jq if missing — brew install jq / apt install jq).

git clone https://github.com/y-abs/claude-code-brain-bootstrap.git /tmp/brain
bash /tmp/brain/install.sh your-repo/
rm -rf /tmp/brain

🔍 Pre-flight check: bash /tmp/brain/install.sh --check — verifies all prerequisites (git, bash, jq) before touching your repo. Runs in 1 second, no side effects.

The installer auto-detects fresh install vs. upgrade — it never overwrites your knowledge (CLAUDE.md, lessons, architecture docs). Existing files stay untouched; only missing pieces are added. A backup is auto-created before any upgrade. settings.json is deep-merged (your existing allowlist is preserved). Existing commands are never overwritten — Brain's versions only fill the gaps.

Step 2 — Let the AI configure itself

/bootstrap

The /bootstrap command runs the discovery engine (discover.sh — pure bash, zero tokens), detects your entire stack, fills 70+ placeholders, then has the AI write architecture docs and domain knowledge specific to your codebase. Fully automated, ~5 minutes.

The claude/*.md knowledge docs are plain Markdown — any AI can read them. Run discover.sh, then tell your AI to read claude/tasks/.discovery.env and fill the {{PLACEHOLDERS}} in claude/architecture.md + claude/build.md. Or skip discovery and let the AI infer from package.json / pyproject.toml / etc. See DETAILED_GUIDE.md for the full prompt.

The discovery engine detects 25+ languages, 1,100+ frameworks, 21 package managers in ~2 seconds. Then the AI fills in what requires reasoning: architecture, domain knowledge, critical patterns.

🧠 How It Works Under the Hood

Claude Code Brain is 200+ files of structured configuration that live in your repo, version-controlled alongside your code. It's not a wrapper, not a plugin, not a SaaS product — it's a knowledge architecture that teaches your AI assistant how your project actually works.

Your repo
├── 📋 CLAUDE.md                    ← Operating protocol (auto-loaded every conversation)
├── ⚙️ .claude/
│   ├── commands/                   ← 31 slash commands (/build, /test, /review, /mr, /health...)
│   ├── hooks/                      ← 16 lifecycle hooks (safety, quality, recovery, audit)
│   ├── agents/                     ← 5 AI subagents (research, reviewer, plan-challenger...)
│   ├── skills/                     ← 18 skills (TDD, triage, root-cause, code review, semantic search...)
│   ├── rules/                      ← 13 path-scoped rules (auto-load per file type)
│   └── settings.json               ← Tool permissions, hook registration
├── 📚 claude/
│   ├── architecture.md             ← Your project's architecture (auto-imported)
│   ├── rules.md                    ← 24 golden rules (auto-imported)
│   ├── build.md                    ← Build/test/lint/serve commands for your stack
│   ├── terminal-safety.md          ← Shell anti-patterns that cause session hangs
│   ├── cve-policy.md               ← Security decision tree
│   ├── plugins.md                  ← Plugin config (claude-mem + graphify + MCP)
│   ├── scripts/                    ← 19 bootstrap & maintenance scripts
│   ├── bootstrap/                  ← 🧠 Setup scaffolding (auto-deleted after bootstrap)
│   ├── tasks/lessons.md            ← 🧠 Accumulated wisdom (persists across sessions)
│   ├── tasks/todo.md               ← 📝 Current task plan (survives session boundaries)
│   └── tasks/CLAUDE_ERRORS.md      ← 🐛 Error log (promotes to rules after 3+ recurrences)
└── 🚫 .claudeignore                ← Context exclusions (lock files, binaries, etc.)

Write your knowledge once. Every AI tool reads it. ✍️

Because it lives in your repo, it's version-controlled, PR-reviewed, and shared across your team automatically — no SaaS account, no sync, no drift.

🎯 The Three-Layer Token Strategy

The system is designed to minimize token cost while maximizing context — your AI doesn't drown in 50K tokens when you ask it to fix a typo:

📦 What's Inside

🔀 Write Once, Read Everywhere

Agents declare their optimal model (model: opus for review/security, session model for research). Falls back gracefully to whatever you're running — Ollama, LM Studio, Bedrock, any local endpoint.

🔄 It Gets Smarter Over Time

This isn't a static config that rots. It's a living system with six feedback loops:

1. 📋 Exit checklist — captures corrections at the end of every turn, so they stick
2. 🧠 lessons.md — accumulated wisdom, read at every session start — impossible to skip
3. 🐛 Error promotion — same mistake 3 times? Becomes a permanent rule automatically
4. 🔁 Session hooks — context survives restarts, compaction, resume — nothing gets lost
5. 🔍 /maintain — audits all docs for stale paths, dead references, drift
6. 🗺️ Auto-updating graph — knowledge graph rebuilds on every commit and branch switch

🛡️ Safety: Defense in Depth

Security isn't one mechanism — it's two layers working together:

🚫 Layer 1: Permissions — What the AI Can't Even Attempt

settings.json defines hard boundaries. The AI can never push code — it presents a summary and waits for your confirmation. Destructive commands (rm -rf /, DROP DATABASE, deployment scripts) are blocked at the permission layer. Only explicitly allowed tool patterns run; everything else requires your approval.

These aren't suggestions — they're hard permission boundaries enforced before the AI even sees the command.

🪝 Layer 2: Hooks — What Gets Intercepted at Runtime

16 lifecycle hooks add runtime guardrails — deterministic bash scripts, zero tokens, zero AI reasoning:

Plus 13 more — session recovery, batch formatting, test reminders, identity refresh, permission audit, exit checklist. Full hook reference →

🔌 Plugin Ecosystem

Ten plugins available — pick what fits your stack. Run setup-plugins.sh and choose a strategy (recommended, full, personalize, or none):

📚 Full plugin reference: claude/plugins.md — usage examples, install commands, toggle scripts, token economics.

⚙️ Make It Yours

Extending the Brain is simple — one file, one registration:

Three worked examples in claude/_examples/ — API domain, database domain, messaging domain.

📚 Full reference: claude/docs/DETAILED_GUIDE.md — complete file inventory, architecture diagrams, all 31 commands, all 16 hooks, placeholder reference, stack-specific examples, FAQ.

❓ FAQ

Platforms: Linux ✅, macOS ✅, Windows WSL2 ✅, Git Bash ✅, CMD/PowerShell ❌ (Claude Code requires a Unix shell).

Prerequisites: git, bash ≥ 3.2 (≥ 4 for /bootstrap), jq. Optional: Python 3.10+ for plugins like graphify.

Languages: 25+ — TypeScript, Python, Go, Rust, Java, Kotlin, Ruby, PHP, C#, C/C++, Swift, Dart, Elixir, and more. The knowledge docs are language-agnostic; stack-specific details are auto-detected by the discovery engine.

💡 macOS ships Bash 3.2 — discover.sh needs Bash 4+ (brew install bash). Run bash install.sh --check to verify everything in 1 second.

Never. The installer detects your existing config and enters upgrade mode — it adds only what's missing and never touches your knowledge files (CLAUDE.md, lessons.md, architecture docs, settings). A full backup is auto-created before any change.

Very little. The system is designed to be cheap by default — your AI doesn't load 50K tokens when you ask it to fix a typo:

• Always on: ~3-4K tokens (operating protocol + critical rules)
• Auto-loaded: ~200-400 tokens per rule (only when editing matching files)
• On-demand: ~1-2K tokens per doc (only when the task needs it)

See the Three-Layer Token Strategy for the full breakdown.

Yes. Agents declare their optimal model but fall back gracefully to whatever you're running — Ollama, LM Studio, Haiku, Bedrock, any provider. The knowledge docs are plain Markdown — any model can read them. No API keys required for the core system.

Scope. Cursor rules are a flat instruction file — the AI reads it if it feels like it. Brain is a multi-layered enforcement architecture with lifecycle hooks that block before execution, subagents that run in isolated contexts, skills that activate per task, session memory that persists across restarts, and self-maintenance that keeps docs current.

It's the difference between a sticky note and an operating system.

Works great solo, but it's designed for teams. Everything is version-controlled and shared by default (TEAM mode).

Not ready to share your Brain with the team? Switch to SOLO mode: add CLAUDE.md, claude/, .claude/ to .gitignore.

🤝 Contributing

PRs welcome! All contributions must be domain-agnostic.

👉 Full guide → CONTRIBUTING.md · 🐛 Report a bug · CI runs 5 checks on every PR.

📄 License

MIT — see LICENSE.