CodeBrain

Know what breaks before you break it.

CodeBrain builds a structural knowledge graph of your codebase — every function, class, import, and call chain — and stores it locally in SQLite. Wire it into Claude Code, Cursor, or any MCP-compatible agent and your AI suddenly knows the structure of your code instead of guessing.

pip install codebrain
cd your-project
brain init

Indexing your-project (1,328 files) ...
Done in 135s — 17,756 nodes, 111,793 edges
Health: 93/100 (A)

Free. MIT-licensed. No cloud. No LLM required for the core features.

Why

AI coding agents (Claude Code, Cursor, Copilot) generate code faster than you can review it. They read fragments of code, lack persistent structural memory, and apply local fixes. When an agent removes a function, it doesn't know 3 other files call it. When it changes a signature, it doesn't know what depends on the old shape.

CodeBrain knows. It maintains a persistent graph of every symbol and relationship and gives agents tools (via MCP) to query it.

Wire it into Claude Code

The killer feature. One command:

brain setup

Indexes the repo, drops a CLAUDE.md with project context, writes the MCP config. Restart Claude Code and it has tools like mcp__codebrain__impact_analysis, mcp__codebrain__find_dead_code, mcp__codebrain__call_chain, mcp__codebrain__zoom, mcp__codebrain__ask_codebase, plus a few dozen more. It uses them on its own.

Manual config — drop .mcp.json at your project's root (not in a global config). CodeBrain's index lives in <repo>/.codebrain/, so a global config would make every Claude session in every project fight over the same database. brain setup writes the right thing for you.

{
  "mcpServers": {
    "codebrain": {
      "command": "python",
      "args": ["-m", "codebrain.mcp_server"]
    }
  }
}

What you can do from the CLI

brain impact create_user        # what breaks if I change this?
brain callers create_user       # who calls this?
brain trace create_user         # what does it call, recursively?
brain deadcode                  # actually-unused functions, with confidence levels
brain hotspots                  # riskiest symbols (most depended on)
brain cycles                    # import cycles
brain health                    # codebase score 0-100
brain coupling                  # module-to-module coupling
brain layers                    # architectural layers inferred from imports
brain zoom system|module|symbol # Google Maps for your architecture
brain ask "where does login flow live?"

Sample output:

$ brain impact getAstroData
Impact of changing predictions_api.py::getAstroData:
  [1] Ascendant.py::compileAstroDetails       (CALLS)
  [1] AsthaKoota.py::getNakAndRasi             (CALLS)
  [2] ProfileBuilder.py::buildProfile          (CALLS via compileAstroDetails)
  ... 48 dependents across 69 files
  Blast radius: 5.2% of the codebase

$ brain hotspots
Risk hotspots (top 3):
   48.2  function  getAstroData             48 deps   69 files
   35.1  function  compileAstroDetails      35 deps   52 files
   28.7  class     ProfileBuilder           28 deps   41 files

Run brain --help for the full command list (60+).

Pre-commit and CI

brain hook install              # validates staged Python files before each commit
brain ci --base origin/main     # exit 1 on structural regressions in a PR
brain diff-impact               # blast radius of currently-staged changes

GitHub Action:

- run: pip install codebrain
- run: brain ci --base origin/main --json

Language support

Adding a parser: implement BaseParser, register via the codebrain.parsers entry point. See docs/USAGE.md.

Optional extras

pip install "codebrain[ts]"     # TypeScript / JS / Vue
pip install "codebrain[api]"    # FastAPI REST server
pip install "codebrain[llm]"    # AI-powered explain / ask / rewrite
pip install "codebrain[all]"    # everything

Core install (pip install codebrain) is enough for Python projects and the MCP server.

Configuration

.codebrain.toml at repo root, or CODEBRAIN_* env vars:

[index]
exclude = ["vendor/", "**/__generated__/**"]

[mcp]
tool_timeout = 25
idle_timeout = 1800

[parser]
languages = ["python", "typescript", "java"]

How it works

Source files ─► Parser ─► Nodes + Edges ─► SQLite (.codebrain/graph.db)
                                                │
                          ┌─────────────────────┴───────────────────────┐
                          ▼                                             ▼
                       brain CLI                              MCP server / REST API

• Node — a symbol (function, class, method, file)
• Edge — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
• GraphStore — SQLite with WAL mode, lives in .codebrain/ (auto-gitignored)
• QueryEngine — BFS/DFS for impact, call chains, dead code, cycles

Everything stays on your machine. The only thing that leaves is what you explicitly send to an LLM via brain ask / brain explain / brain rewrite.

Documentation

• docs/USAGE.md — full usage guide: workflows, every command, MCP setup, troubleshooting.
• docs/cli-reference.md — generated CLI reference.
• docs/mcp-tools.md — every MCP tool with examples.
• docs/PRD.md — product requirements.

Development

git clone https://github.com/monk0062006/CodeBrain.git
cd CodeBrain
pip install -e ".[dev]"

pytest tests/                   # 1,900+ tests
ruff check codebrain/
mypy codebrain/

License

MIT. Use it however you want.

Links

• PyPI: https://pypi.org/project/codebrain/
• Issues: https://github.com/monk0062006/CodeBrain/issues