Metadata-Version: 2.4
Name: codebrain
Version: 0.4.1
Summary: Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.
Author: CodeBrain Contributors
License: MIT License
        
        Copyright (c) 2026 CodeBrain Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/monk0062006/CodeBrain
Project-URL: Repository, https://github.com/monk0062006/CodeBrain
Project-URL: Issues, https://github.com/monk0062006/CodeBrain/issues
Keywords: code-analysis,static-analysis,knowledge-graph,impact-analysis,dead-code,codebase-health,mcp,ai-coding,structural-analysis,refactoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: watchdog>=3.0
Requires-Dist: mcp<1.20,>=1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: psutil>=5.9
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn>=0.27; extra == "api"
Provides-Extra: llm
Requires-Dist: httpx>=0.27; extra == "llm"
Provides-Extra: ts
Requires-Dist: tree-sitter>=0.21; extra == "ts"
Requires-Dist: tree-sitter-languages>=1.10; extra == "ts"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-tmp-files>=0.0.2; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Provides-Extra: all
Requires-Dist: codebrain[api,llm,ts]; extra == "all"
Dynamic: license-file

# 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.

```bash
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:

```bash
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.

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

---

## What you can do from the CLI

```bash
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

```bash
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:

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

---

## Language support

| Language | Parser | Status |
|---|---|---|
| Python | AST (stdlib) | full |
| TypeScript / JS / JSX / Vue | tree-sitter | full — `pip install "codebrain[ts]"` |
| Java | tree-sitter | full — Spring Boot aware |
| Go, Rust, C#, Kotlin, Dart | tree-sitter / regex | good |
| COBOL, Fortran, MUMPS, PL/SQL | regex | basic — for legacy migration |

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

---

## Optional extras

```bash
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:

```toml
[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](docs/USAGE.md)** — full usage guide: workflows,
  every command, MCP setup, troubleshooting.
- **[docs/cli-reference.md](docs/cli-reference.md)** — generated CLI
  reference.
- **[docs/mcp-tools.md](docs/mcp-tools.md)** — every MCP tool with
  examples.
- **[docs/PRD.md](docs/PRD.md)** — product requirements.

---

## Development

```bash
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
