codebrain 0.3.0

Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.

CodeBrain

Know what breaks before you break it.

CodeBrain builds a structural knowledge graph of your codebase — every function, class, import, and call chain — stored locally in SQLite. No cloud. No LLM required. Just deterministic structural analysis.

pip install codebrain
cd your-project
brain init

You'll immediately see:

Indexing my-project (93 files) ...
Done in 1.2s — 1861 nodes, 8837 edges

=== Instant Findings ===
Health: 60/100 (B)
Riskiest symbols: Flask (34 files), App (35 files), Scaffold (28 files)
Dead code: 11 candidates (none high-confidence)

Then explore:

brain impact my_function    # What breaks if I change this?
brain callers my_function   # Who calls this?
brain health                # Codebase health score (0-100)
brain hotspots              # Riskiest symbols in the codebase
brain deadcode              # Unused functions with confidence levels
brain zoom                  # Google Maps-style navigation of your architecture

Why CodeBrain?

AI coding agents (Claude Code, Cursor, Copilot) generate code faster than you can review it. They apply local fixes without understanding global structure. When an agent removes a function, it doesn't know 3 other files call it.

CodeBrain knows. It maintains a persistent knowledge graph of every symbol and relationship in your codebase, and can tell you exactly what would break before any change is made.

No API keys. No cloud. No LLM. Everything runs locally on your machine.

Features

Impact Analysis

$ 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

Health Score

$ brain health
Codebase Health
  Score: 93/100 (A)
  [##################--]
  Dead code:     517 symbols (4.2%)  score 79/100
  Import cycles: 0                   score 100/100
  Coupling:      3 hotspot(s)        score 94/100

Risk Hotspots

$ brain hotspots
Risk hotspots (top 5):
  Score  Type       Name                            Deps  Files
   48.2  function   getAstroData                      48     69
   35.1  function   compileAstroDetails               35     52
   28.7  class      ProfileBuilder                    28     41

Dead Code Detection

Finds unused symbols with confidence levels:

• High — truly unreferenced, safe to delete
• Medium — file uses dynamic patterns (callbacks, registries)
• Low — might be used via reflection or external entry points

Implicit Contracts

$ brain contracts
Implicit contracts (12):
  [co_import       ] (100%) 'Colors' and 'Spacing' are imported together in 141/141 files
  [co_import       ] (98%)  'Spacing' and 'react-native' are imported together in 138/141 files

Module Coupling

$ brain coupling
Most coupled file pairs:
  140  logger.py  <->  main.py
  101  ForeignSettlementProfile.py  <->  ForeignSettlementProfiling.py

Architectural Layers

$ brain layers
Layer 0 — foundation (deepest dependencies)
    utils/logger.py
    utils/constants.py
Layer 1 — core
    core/engine.py
    core/models.py

Multi-Resolution Zoom

Navigate your codebase like Google Maps — zoom from system level to package to file to symbol:

$ brain zoom
System: 1328 files, 17756 symbols across 5 packages
Backbone: debug_astrodata.py, debug_dasha_data.py, debug_house_data.py

$ brain zoom backend
Package: backend (978 files, 14794 symbols)
Top modules: ProfileAPI/main.py (429 symbols), test_subscription_tiers.py (210 symbols)

$ brain zoom backend/vedic-profiles/ProfileAPI/main.py
Module: main.py — 429 symbols, 15853 lines. Isolated (no dependents).

AI Agent Integration

Claude Code (MCP)

brain setup    # auto-generates CLAUDE.md + MCP config

Or add manually to your MCP config:

{
  "mcpServers": {
    "codebrain": {
      "command": "python",
      "args": ["-m", "codebrain.mcp_server"],
      "cwd": "/path/to/your/repo"
    }
  }
}

22 MCP tools available including:

Tool	Purpose
propose_change	Validate before writing — the structural safety gate
impact_analysis	Trace transitive dependents of any symbol
ask_codebase	Natural language questions about the codebase
validate_change	Check if a file change would break callers
risk_hotspots	Find structurally dangerous symbols
find_dead_code	Unused symbols with confidence levels
codebase_overview	System-level architecture summary

Structural Safety Gate

The propose_change MCP tool validates changes before the AI writes them. When a change would remove a function that other files call, or change a signature that callers depend on, CodeBrain blocks it and tells the agent exactly what would break.

All CLI Commands

Command	Description
brain init	Index the current repository
brain status	Show index statistics
brain search <query>	Find symbols by name
brain impact <name>	What breaks if this changes?
brain callers <name>	Who calls this function? (reverse trace)
brain trace <name>	Forward call chain from a symbol
brain deps <name>	Dependencies of a symbol or file
brain deadcode	Find unused functions/classes
brain cycles	Detect import cycles
brain health	Codebase health score (0-100)
brain hotspots	Riskiest symbols by structural exposure
brain coupling	Module coupling analysis
brain contracts	Implicit contract detection
brain layers	Architectural layer inference
brain zoom [target]	Multi-resolution navigation
brain overview	System-level codebase overview
brain module <file>	Module-level view
brain context <name>	LLM-optimized symbol context
brain validate <file>	Check if a file change is safe
brain ci --base main	CI validation for pull requests
brain watch	File watcher daemon (re-index on save)
brain hook install	Install pre-commit validation hook
brain reindex	Force a full rebuild
brain doctor	Diagnostic health check
brain serve	Start REST API server

All commands support --json for machine-readable output, --repo <path> for different repos, --timeout N for analysis timeout (default: 120s), and --verbose for debug logging.

Configuration

Create .codebrain.toml in your repo root (optional):

[codebrain]
skip_dirs = ["__pycache__", ".git", "node_modules", "vendor"]
extensions = [".py", ".ts", ".tsx", ".js", ".jsx"]
max_file_size_kb = 1024
cli_timeout = 120

Or use environment variables:

Variable	Description
CODEBRAIN_SKIP_DIRS	Comma-separated directories to skip
CODEBRAIN_EXTENSIONS	Comma-separated file extensions to index
CODEBRAIN_CLI_TIMEOUT	Analysis timeout in seconds (default: 120)
CODEBRAIN_MAX_WORKERS	Max parallel worker processes

Language Support

Language	Parser	Quality
Python	AST (stdlib)	Full — functions, classes, imports, calls, dataflow
TypeScript/JSX	tree-sitter	Full — requires pip install codebrain[ts]
JavaScript/JSX	tree-sitter	Full — requires pip install codebrain[ts]
Java	tree-sitter	Full — Spring Boot aware (DI, endpoints, JPA)
Go	tree-sitter	Full — interfaces, goroutines, struct methods
Rust	tree-sitter	Full — traits, impls, modules, derive macros
C#	tree-sitter	Full — async/await, LINQ, attributes
Kotlin	tree-sitter	Full — coroutines, extensions, data classes
Dart/Flutter	regex	Good — classes, mixins, extensions
Vue SFC	regex	Good — components, props, events

Adding Languages

Implement BaseParser and register via entry points:

from codebrain.parser.base import BaseParser
from codebrain.parser.models import ParsedFile

class MyParser(BaseParser):
    def extensions(self) -> frozenset[str]:
        return frozenset({".xyz"})

    def parse(self, path, repo_root) -> ParsedFile:
        ...  # parse and return nodes + edges

# pyproject.toml
[project.entry-points."codebrain.parsers"]
rust = "your_package.parser:RustParser"

CI Integration

Pre-commit Hook

brain hook install     # validates staged files before every commit
brain hook uninstall   # remove the hook

GitHub Action

name: CodeBrain Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install codebrain
      - run: brain ci --base origin/main --json

Optional Extras

pip install codebrain[ts]    # TypeScript/JavaScript tree-sitter parser
pip install codebrain[api]   # REST API server (FastAPI)
pip install codebrain[llm]   # LLM-enhanced explanations (optional, requires API key)
pip install codebrain[all]   # Everything

The core tool requires no extras. Python parsing, impact analysis, health scores, dead code detection, coupling analysis — all work out of the box with just pip install codebrain.

How It Works

Source Files  -->  Parser (Python AST / tree-sitter)  -->  Nodes + Edges
                                                               |
                                                         GraphStore (SQLite)
                                                               |
                                                         QueryEngine
                                                               |
                                 CLI / MCP Server / REST API / VS Code Extension

• Node — a code symbol (function, class, method, variable, file)
• Edge — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
• GraphStore — persistent SQLite database with WAL mode, lives in .codebrain/graph.db
• QueryEngine — BFS/DFS traversal for impact analysis, call chains, dead code, cycle detection

Everything is local. The database is a single SQLite file in your repo's .codebrain/ directory (auto-gitignored).

Real-World Validation

Tested on a 1,328-file mixed Python + TypeScript production codebase:

Metric	Result
Files indexed	1,328 (zero errors)
Symbols extracted	17,756
Relationships mapped	111,793
Indexing time	135 seconds
Health score	93/100
Impact analysis	48 dependents traced across 69 files
Implicit contracts	Found co-import pattern in 141/141 files
Tests passing	794

Requirements

• Python 3.11+
• No internet connection required
• No API keys required
• No LLM required
• Works on Windows, macOS, and Linux

Development

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

pytest tests/ -v              # Run tests
mypy codebrain/               # Type checking
ruff check codebrain/         # Linting
pytest --cov=codebrain        # Coverage

License

MIT