codebrain 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. codebrain-0.1.0/LICENSE +21 -0
  2. codebrain-0.1.0/PKG-INFO +360 -0
  3. codebrain-0.1.0/README.md +316 -0
  4. codebrain-0.1.0/codebrain/__init__.py +3 -0
  5. codebrain-0.1.0/codebrain/__main__.py +6 -0
  6. codebrain-0.1.0/codebrain/agent_bridge.py +162 -0
  7. codebrain-0.1.0/codebrain/analyzer.py +943 -0
  8. codebrain-0.1.0/codebrain/api.py +578 -0
  9. codebrain-0.1.0/codebrain/api_models.py +102 -0
  10. codebrain-0.1.0/codebrain/cli.py +1927 -0
  11. codebrain-0.1.0/codebrain/comprehension.py +1939 -0
  12. codebrain-0.1.0/codebrain/config.py +46 -0
  13. codebrain-0.1.0/codebrain/context.py +276 -0
  14. codebrain-0.1.0/codebrain/export.py +334 -0
  15. codebrain-0.1.0/codebrain/graph/__init__.py +0 -0
  16. codebrain-0.1.0/codebrain/graph/query.py +656 -0
  17. codebrain-0.1.0/codebrain/graph/schema.py +113 -0
  18. codebrain-0.1.0/codebrain/graph/store.py +295 -0
  19. codebrain-0.1.0/codebrain/hook_runner.py +71 -0
  20. codebrain-0.1.0/codebrain/hooks.py +107 -0
  21. codebrain-0.1.0/codebrain/indexer.py +450 -0
  22. codebrain-0.1.0/codebrain/llm.py +676 -0
  23. codebrain-0.1.0/codebrain/logging.py +42 -0
  24. codebrain-0.1.0/codebrain/mcp_server.py +1635 -0
  25. codebrain-0.1.0/codebrain/memory/__init__.py +5 -0
  26. codebrain-0.1.0/codebrain/memory/store.py +270 -0
  27. codebrain-0.1.0/codebrain/parser/__init__.py +0 -0
  28. codebrain-0.1.0/codebrain/parser/base.py +27 -0
  29. codebrain-0.1.0/codebrain/parser/config_parser.py +228 -0
  30. codebrain-0.1.0/codebrain/parser/models.py +44 -0
  31. codebrain-0.1.0/codebrain/parser/python_parser.py +658 -0
  32. codebrain-0.1.0/codebrain/parser/registry.py +144 -0
  33. codebrain-0.1.0/codebrain/parser/typescript_parser.py +1189 -0
  34. codebrain-0.1.0/codebrain/parser/typescript_treesitter.py +535 -0
  35. codebrain-0.1.0/codebrain/py.typed +0 -0
  36. codebrain-0.1.0/codebrain/resolver.py +171 -0
  37. codebrain-0.1.0/codebrain/settings.py +88 -0
  38. codebrain-0.1.0/codebrain/utils.py +59 -0
  39. codebrain-0.1.0/codebrain/validator.py +563 -0
  40. codebrain-0.1.0/codebrain/watcher/__init__.py +0 -0
  41. codebrain-0.1.0/codebrain/watcher/file_watcher.py +173 -0
  42. codebrain-0.1.0/codebrain.egg-info/PKG-INFO +360 -0
  43. codebrain-0.1.0/codebrain.egg-info/SOURCES.txt +91 -0
  44. codebrain-0.1.0/codebrain.egg-info/dependency_links.txt +1 -0
  45. codebrain-0.1.0/codebrain.egg-info/entry_points.txt +6 -0
  46. codebrain-0.1.0/codebrain.egg-info/requires.txt +26 -0
  47. codebrain-0.1.0/codebrain.egg-info/top_level.txt +1 -0
  48. codebrain-0.1.0/pyproject.toml +111 -0
  49. codebrain-0.1.0/setup.cfg +4 -0
  50. codebrain-0.1.0/tests/test_agent_bridge.py +57 -0
  51. codebrain-0.1.0/tests/test_analyzer.py +446 -0
  52. codebrain-0.1.0/tests/test_api.py +412 -0
  53. codebrain-0.1.0/tests/test_ci.py +184 -0
  54. codebrain-0.1.0/tests/test_cli.py +475 -0
  55. codebrain-0.1.0/tests/test_comprehension.py +635 -0
  56. codebrain-0.1.0/tests/test_context.py +107 -0
  57. codebrain-0.1.0/tests/test_contracts_real.py +123 -0
  58. codebrain-0.1.0/tests/test_dataflow.py +265 -0
  59. codebrain-0.1.0/tests/test_dead_code_confidence.py +129 -0
  60. codebrain-0.1.0/tests/test_error_recovery.py +192 -0
  61. codebrain-0.1.0/tests/test_export.py +213 -0
  62. codebrain-0.1.0/tests/test_hooks.py +142 -0
  63. codebrain-0.1.0/tests/test_indexer.py +115 -0
  64. codebrain-0.1.0/tests/test_install.py +41 -0
  65. codebrain-0.1.0/tests/test_integration.py +287 -0
  66. codebrain-0.1.0/tests/test_jyotishyamitra.py +368 -0
  67. codebrain-0.1.0/tests/test_llm.py +475 -0
  68. codebrain-0.1.0/tests/test_mcp_server.py +615 -0
  69. codebrain-0.1.0/tests/test_memory.py +462 -0
  70. codebrain-0.1.0/tests/test_multi_project_cli.py +184 -0
  71. codebrain-0.1.0/tests/test_narratives.py +166 -0
  72. codebrain-0.1.0/tests/test_parser.py +249 -0
  73. codebrain-0.1.0/tests/test_plugin_system.py +221 -0
  74. codebrain-0.1.0/tests/test_production_hardening.py +377 -0
  75. codebrain-0.1.0/tests/test_query.py +447 -0
  76. codebrain-0.1.0/tests/test_real_world.py +298 -0
  77. codebrain-0.1.0/tests/test_resolver.py +66 -0
  78. codebrain-0.1.0/tests/test_scale.py +245 -0
  79. codebrain-0.1.0/tests/test_scale_optimizations.py +229 -0
  80. codebrain-0.1.0/tests/test_scale_real.py +220 -0
  81. codebrain-0.1.0/tests/test_schema.py +100 -0
  82. codebrain-0.1.0/tests/test_settings.py +113 -0
  83. codebrain-0.1.0/tests/test_store.py +190 -0
  84. codebrain-0.1.0/tests/test_ts_ast_parser.py +130 -0
  85. codebrain-0.1.0/tests/test_ts_parser_enhanced.py +224 -0
  86. codebrain-0.1.0/tests/test_typescript_parser.py +170 -0
  87. codebrain-0.1.0/tests/test_utils.py +37 -0
  88. codebrain-0.1.0/tests/test_validation_narratives.py +103 -0
  89. codebrain-0.1.0/tests/test_validator.py +120 -0
  90. codebrain-0.1.0/tests/test_validator_scenarios.py +328 -0
  91. codebrain-0.1.0/tests/test_watch_validate.py +107 -0
  92. codebrain-0.1.0/tests/test_watcher.py +135 -0
  93. codebrain-0.1.0/tests/test_zoom.py +189 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 CodeBrain Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,360 @@
1
+ Metadata-Version: 2.4
2
+ Name: codebrain
3
+ Version: 0.1.0
4
+ Summary: Persistent structural knowledge graph for codebases — lets LLM agents skip grep and understand repos in seconds.
5
+ Author: CodeBrain Contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/monk0062006/CodeBrain
8
+ Project-URL: Repository, https://github.com/monk0062006/CodeBrain
9
+ Project-URL: Issues, https://github.com/monk0062006/CodeBrain/issues
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Quality Assurance
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: click>=8.1
23
+ Requires-Dist: watchdog>=3.0
24
+ Requires-Dist: mcp<1.20,>=1.0
25
+ Requires-Dist: jinja2>=3.1
26
+ Provides-Extra: api
27
+ Requires-Dist: fastapi>=0.110; extra == "api"
28
+ Requires-Dist: uvicorn>=0.27; extra == "api"
29
+ Provides-Extra: llm
30
+ Requires-Dist: httpx>=0.27; extra == "llm"
31
+ Provides-Extra: ts
32
+ Requires-Dist: tree-sitter>=0.21; extra == "ts"
33
+ Requires-Dist: tree-sitter-languages>=1.10; extra == "ts"
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=7.0; extra == "dev"
36
+ Requires-Dist: pytest-tmp-files>=0.0.2; extra == "dev"
37
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
38
+ Requires-Dist: mypy>=1.8; extra == "dev"
39
+ Requires-Dist: ruff>=0.3; extra == "dev"
40
+ Requires-Dist: httpx>=0.27; extra == "dev"
41
+ Provides-Extra: all
42
+ Requires-Dist: codebrain[api,llm,ts]; extra == "all"
43
+ Dynamic: license-file
44
+
45
+ # CodeBrain
46
+
47
+ Structural intelligence for AI-assisted development. CodeBrain builds a
48
+ persistent knowledge graph of your codebase and validates changes before
49
+ they land — preventing AI coding agents from silently breaking things.
50
+
51
+ ## The Problem
52
+
53
+ AI coding agents (Claude Code, Cursor, Copilot) generate code faster than
54
+ you can review it. They grep fragments, apply local fixes, and don't
55
+ maintain a mental model. When the AI removes a function, it doesn't know
56
+ 3 other files call it.
57
+
58
+ CodeBrain knows.
59
+
60
+ ## Quick Start
61
+
62
+ ### 1. Install
63
+
64
+ ```bash
65
+ pip install codebrain
66
+ ```
67
+
68
+ Optional extras:
69
+
70
+ ```bash
71
+ pip install codebrain[api] # REST API server
72
+ pip install codebrain[llm] # LLM-enhanced explanations
73
+ pip install codebrain[ts] # TypeScript AST parser (tree-sitter)
74
+ pip install codebrain[all] # Everything
75
+ ```
76
+
77
+ ### 2. Index your project
78
+
79
+ ```bash
80
+ cd your-project
81
+ brain init
82
+ ```
83
+
84
+ ### 3. Connect to Claude Code
85
+
86
+ ```bash
87
+ brain agent # generates CLAUDE.md + MCP config
88
+ ```
89
+
90
+ Or add to your MCP config manually:
91
+
92
+ ```json
93
+ {
94
+ "mcpServers": {
95
+ "codebrain": {
96
+ "command": "python",
97
+ "args": ["-m", "codebrain.mcp_server"],
98
+ "cwd": "/path/to/your/repo"
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ ### 4. That's it
105
+
106
+ CodeBrain will automatically validate changes before Claude writes them.
107
+ When a change would break something, it says so — with the specific files
108
+ and callers that would be affected.
109
+
110
+ ## What It Does
111
+
112
+ ### Structural Safety Gate
113
+
114
+ Before an AI agent writes a file, CodeBrain checks if the change would break
115
+ callers in other files. If it would, the agent is told to fix the breakage first.
116
+
117
+ ### Impact Analysis
118
+
119
+ "What would break if I change this?" — answers with specific files, symbols,
120
+ and call chains. Not grep results. Deterministic graph traversal.
121
+
122
+ ### Risk Hotspots
123
+
124
+ Identifies the most structurally dangerous code — functions called by many files,
125
+ modules with high coupling, symbols where a signature change would cascade.
126
+
127
+ ### Dead Code Detection
128
+
129
+ Finds unused symbols with confidence levels. High-confidence means it's really dead.
130
+ Medium means the file uses dynamic patterns. Low means it might be used indirectly.
131
+
132
+ ### Comprehension Narratives
133
+
134
+ Plain English explanations: "store.py is the most depended-on file — 8 modules
135
+ import from it. Changes here have the highest blast radius in the codebase."
136
+
137
+ ## CLI Commands
138
+
139
+ | Command | Description |
140
+ |---------|-------------|
141
+ | `brain init` | Index the current repository |
142
+ | `brain reindex` | Force a full rebuild |
143
+ | `brain status [--json]` | Show index statistics |
144
+ | `brain search <query> [--json]` | Find symbols by name |
145
+ | `brain trace <name> [--depth N] [--json]` | Forward call chain |
146
+ | `brain impact <name> [--depth N] [--json]` | Reverse impact analysis |
147
+ | `brain deps <name> [--json]` | Dependencies of a symbol or file |
148
+ | `brain deadcode [--json]` | Find unused functions/classes |
149
+ | `brain cycles [--json]` | Detect import cycles |
150
+ | `brain validate <file> [--json]` | Check if a file change is safe |
151
+ | `brain overview [--json]` | System-level codebase overview |
152
+ | `brain module <file> [--json]` | Module-level view |
153
+ | `brain context <name> [--json]` | LLM-optimized symbol context |
154
+ | `brain hotspots [--top N] [--json]` | Riskiest symbols |
155
+ | `brain coupling [--json]` | Module coupling analysis |
156
+ | `brain contracts [--json]` | Implicit contract detection |
157
+ | `brain layers [--json]` | Architectural layer inference |
158
+ | `brain doctor` | Diagnostic health check |
159
+ | `brain zoom [target] [--json]` | Multi-resolution navigation (system/package/module/symbol) |
160
+ | `brain ci [--base B] [--fail-on F] [--json]` | CI validation of changed files |
161
+ | `brain diff` | Show files changed since last index |
162
+ | `brain watch` | Start file watcher daemon |
163
+ | `brain repair` | Check database integrity, rebuild if corrupted |
164
+ | `brain mcp` | Start MCP server (stdio) |
165
+ | `brain hook install` | Install pre-commit hook |
166
+ | `brain hook uninstall` | Remove pre-commit hook |
167
+ | `brain agent` | Generate agent integration files |
168
+ | `brain serve [--host H] [--port P]` | Start REST API server |
169
+
170
+ All commands accept `--repo <path>` to specify a different repository root, `--verbose` for debug logging, and `--timeout N` to set analysis timeout in seconds (default: 120).
171
+
172
+ ## MCP Tools (for AI agents)
173
+
174
+ 22+ tools available via MCP protocol. Key tools:
175
+
176
+ | Tool | Purpose |
177
+ |------|---------|
178
+ | `propose_change` | Validate before writing — the structural safety gate |
179
+ | `impact_analysis` | Trace transitive dependents of any symbol |
180
+ | `get_file_context` | Full file understanding for LLM context |
181
+ | `get_symbol_context` | Full symbol understanding for LLM context |
182
+ | `ask_codebase` | Natural language questions about the codebase |
183
+ | `validate_change` | Check if a file change would break callers |
184
+ | `risk_hotspots` | Find structurally dangerous symbols |
185
+ | `find_dead_code` | Unused symbols with confidence levels |
186
+ | `codebase_overview` | System-level architecture summary |
187
+ | `get_task_context` | Pull relevant context for a development task |
188
+
189
+ See [docs/mcp-tools.md](docs/mcp-tools.md) for full documentation.
190
+
191
+ ## Configuration
192
+
193
+ Create `.codebrain.toml` in your repo root:
194
+
195
+ ```toml
196
+ [codebrain]
197
+ # Extra directories to skip during indexing
198
+ skip_dirs = ["__pycache__", ".git", "node_modules", "vendor"]
199
+
200
+ # File extensions to index
201
+ extensions = [".py", ".ts", ".tsx", ".js", ".jsx"]
202
+
203
+ # Watcher debounce interval (seconds)
204
+ watcher_debounce = 0.5
205
+
206
+ # File count threshold for parallel parsing
207
+ parallel_threshold = 50
208
+
209
+ # Maximum file size to index (KB)
210
+ max_file_size_kb = 1024
211
+ ```
212
+
213
+ Environment variables override the config file:
214
+
215
+ | Variable | Description |
216
+ |----------|-------------|
217
+ | `CODEBRAIN_SKIP_DIRS` | Comma-separated skip directories |
218
+ | `CODEBRAIN_EXTENSIONS` | Comma-separated file extensions |
219
+ | `CODEBRAIN_DEBOUNCE` | Watcher debounce seconds |
220
+ | `CODEBRAIN_PARALLEL_THRESHOLD` | Parallel parsing threshold |
221
+ | `CODEBRAIN_MAX_WORKERS` | Max parallel worker processes |
222
+ | `CODEBRAIN_CLI_TIMEOUT` | CLI analysis timeout in seconds (default: 120) |
223
+
224
+ See [docs/configuration.md](docs/configuration.md) for full reference.
225
+
226
+ ## Language Support
227
+
228
+ - **Python**: Full AST parsing (stable)
229
+ - **TypeScript/JavaScript**: tree-sitter parsing (`pip install codebrain[ts]`)
230
+ - **TypeScript fallback**: regex-based (experimental, limited coverage)
231
+
232
+ ## CI Integration
233
+
234
+ ### Pre-commit Hook
235
+
236
+ ```bash
237
+ brain hook install # validates staged files before every commit
238
+ brain hook uninstall # remove the hook
239
+ ```
240
+
241
+ The hook blocks commits with critical structural violations. Use `git commit --no-verify` to bypass.
242
+
243
+ ### CI Pipeline
244
+
245
+ ```bash
246
+ brain ci --base main # exits 1 if UNSAFE changes detected
247
+ brain ci --base main --json # machine-readable output
248
+ brain ci --fail-on caution # stricter: also fail on CAUTION
249
+ ```
250
+
251
+ ### GitHub Action
252
+
253
+ ```yaml
254
+ # .github/workflows/codebrain.yml
255
+ name: CodeBrain Validation
256
+ on: [pull_request]
257
+ jobs:
258
+ validate:
259
+ runs-on: ubuntu-latest
260
+ steps:
261
+ - uses: actions/checkout@v4
262
+ with:
263
+ fetch-depth: 0
264
+ - uses: actions/setup-python@v5
265
+ with:
266
+ python-version: '3.11'
267
+ - run: pip install codebrain
268
+ - run: brain ci --base origin/main --json
269
+ ```
270
+
271
+ Or use the reusable composite action:
272
+
273
+ ```yaml
274
+ - uses: ./.github/actions/codebrain-validate
275
+ with:
276
+ base-branch: main
277
+ fail-on: unsafe
278
+ ```
279
+
280
+ ## VS Code Extension
281
+
282
+ See [`vscode-extension/`](vscode-extension/) — 5 commands (impact, context, search, validate, hotspots) plus validate-on-save with inline diagnostics.
283
+
284
+ ## REST API
285
+
286
+ ```bash
287
+ pip install codebrain[api]
288
+ brain serve --port 8484
289
+ ```
290
+
291
+ ~20 endpoints at `/api/status`, `/api/search`, `/api/impact/{name}`, `/api/hotspots`, etc. Interactive docs at `/docs`.
292
+
293
+ ## Plugin System
294
+
295
+ Add custom language parsers by implementing `BaseParser` and registering via entry points:
296
+
297
+ ```python
298
+ from codebrain.parser.base import BaseParser
299
+
300
+ class RustParser(BaseParser):
301
+ def extensions(self) -> frozenset[str]:
302
+ return frozenset({".rs"})
303
+
304
+ def parse(self, path, repo_root):
305
+ ... # return ParsedFile
306
+ ```
307
+
308
+ ```toml
309
+ # pyproject.toml
310
+ [project.entry-points."codebrain.parsers"]
311
+ rust = "your_package.parser:RustParser"
312
+ ```
313
+
314
+ ## Architecture
315
+
316
+ ```
317
+ Source Files --> Parser (Python/TS) --> ParsedFile (Nodes + Edges)
318
+ |
319
+ GraphStore (SQLite)
320
+ |
321
+ QueryEngine
322
+ |
323
+ CLI / MCP / REST API / VS Code / Agent Bridge
324
+ ```
325
+
326
+ **Key abstractions:**
327
+
328
+ - **Node** — a code symbol (function, class, method, variable)
329
+ - **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
330
+ - **GraphStore** — CRUD over the SQLite knowledge graph
331
+ - **QueryEngine** — impact analysis, call chains, dead code, cycles
332
+
333
+ ## Validated on Real Codebases
334
+
335
+ CodeBrain has been tested on a 1,328-file mixed Python + TypeScript project (17,756 symbols, 111,793 edges):
336
+
337
+ - **Indexing**: 1,328 files in 135s, zero errors
338
+ - **Health score**: 93/100 in under 5s
339
+ - **Impact analysis**: Traces `getAstroData` → 48 dependents across 69 files
340
+ - **Contracts**: Found `Colors` + `Spacing` co-imported in 141/141 files (confidence 1.0)
341
+ - **Coupling**: Identified `logger.py` ↔ `main.py` (score 140)
342
+ - **Layers**: Detected architectural cycles in `kp-astrology` module
343
+ - **752 tests passing** across unit, integration, and real-world validation
344
+
345
+ ## Development
346
+
347
+ ```bash
348
+ git clone https://github.com/monk0062006/CodeBrain.git
349
+ cd CodeBrain
350
+ pip install -e ".[dev]"
351
+
352
+ pytest tests/ -v # Run tests
353
+ mypy codebrain/ # Type checking
354
+ ruff check codebrain/ # Linting
355
+ pytest --cov=codebrain # Coverage
356
+ ```
357
+
358
+ ## License
359
+
360
+ MIT
@@ -0,0 +1,316 @@
1
+ # CodeBrain
2
+
3
+ Structural intelligence for AI-assisted development. CodeBrain builds a
4
+ persistent knowledge graph of your codebase and validates changes before
5
+ they land — preventing AI coding agents from silently breaking things.
6
+
7
+ ## The Problem
8
+
9
+ AI coding agents (Claude Code, Cursor, Copilot) generate code faster than
10
+ you can review it. They grep fragments, apply local fixes, and don't
11
+ maintain a mental model. When the AI removes a function, it doesn't know
12
+ 3 other files call it.
13
+
14
+ CodeBrain knows.
15
+
16
+ ## Quick Start
17
+
18
+ ### 1. Install
19
+
20
+ ```bash
21
+ pip install codebrain
22
+ ```
23
+
24
+ Optional extras:
25
+
26
+ ```bash
27
+ pip install codebrain[api] # REST API server
28
+ pip install codebrain[llm] # LLM-enhanced explanations
29
+ pip install codebrain[ts] # TypeScript AST parser (tree-sitter)
30
+ pip install codebrain[all] # Everything
31
+ ```
32
+
33
+ ### 2. Index your project
34
+
35
+ ```bash
36
+ cd your-project
37
+ brain init
38
+ ```
39
+
40
+ ### 3. Connect to Claude Code
41
+
42
+ ```bash
43
+ brain agent # generates CLAUDE.md + MCP config
44
+ ```
45
+
46
+ Or add to your MCP config manually:
47
+
48
+ ```json
49
+ {
50
+ "mcpServers": {
51
+ "codebrain": {
52
+ "command": "python",
53
+ "args": ["-m", "codebrain.mcp_server"],
54
+ "cwd": "/path/to/your/repo"
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ ### 4. That's it
61
+
62
+ CodeBrain will automatically validate changes before Claude writes them.
63
+ When a change would break something, it says so — with the specific files
64
+ and callers that would be affected.
65
+
66
+ ## What It Does
67
+
68
+ ### Structural Safety Gate
69
+
70
+ Before an AI agent writes a file, CodeBrain checks if the change would break
71
+ callers in other files. If it would, the agent is told to fix the breakage first.
72
+
73
+ ### Impact Analysis
74
+
75
+ "What would break if I change this?" — answers with specific files, symbols,
76
+ and call chains. Not grep results. Deterministic graph traversal.
77
+
78
+ ### Risk Hotspots
79
+
80
+ Identifies the most structurally dangerous code — functions called by many files,
81
+ modules with high coupling, symbols where a signature change would cascade.
82
+
83
+ ### Dead Code Detection
84
+
85
+ Finds unused symbols with confidence levels. High-confidence means it's really dead.
86
+ Medium means the file uses dynamic patterns. Low means it might be used indirectly.
87
+
88
+ ### Comprehension Narratives
89
+
90
+ Plain English explanations: "store.py is the most depended-on file — 8 modules
91
+ import from it. Changes here have the highest blast radius in the codebase."
92
+
93
+ ## CLI Commands
94
+
95
+ | Command | Description |
96
+ |---------|-------------|
97
+ | `brain init` | Index the current repository |
98
+ | `brain reindex` | Force a full rebuild |
99
+ | `brain status [--json]` | Show index statistics |
100
+ | `brain search <query> [--json]` | Find symbols by name |
101
+ | `brain trace <name> [--depth N] [--json]` | Forward call chain |
102
+ | `brain impact <name> [--depth N] [--json]` | Reverse impact analysis |
103
+ | `brain deps <name> [--json]` | Dependencies of a symbol or file |
104
+ | `brain deadcode [--json]` | Find unused functions/classes |
105
+ | `brain cycles [--json]` | Detect import cycles |
106
+ | `brain validate <file> [--json]` | Check if a file change is safe |
107
+ | `brain overview [--json]` | System-level codebase overview |
108
+ | `brain module <file> [--json]` | Module-level view |
109
+ | `brain context <name> [--json]` | LLM-optimized symbol context |
110
+ | `brain hotspots [--top N] [--json]` | Riskiest symbols |
111
+ | `brain coupling [--json]` | Module coupling analysis |
112
+ | `brain contracts [--json]` | Implicit contract detection |
113
+ | `brain layers [--json]` | Architectural layer inference |
114
+ | `brain doctor` | Diagnostic health check |
115
+ | `brain zoom [target] [--json]` | Multi-resolution navigation (system/package/module/symbol) |
116
+ | `brain ci [--base B] [--fail-on F] [--json]` | CI validation of changed files |
117
+ | `brain diff` | Show files changed since last index |
118
+ | `brain watch` | Start file watcher daemon |
119
+ | `brain repair` | Check database integrity, rebuild if corrupted |
120
+ | `brain mcp` | Start MCP server (stdio) |
121
+ | `brain hook install` | Install pre-commit hook |
122
+ | `brain hook uninstall` | Remove pre-commit hook |
123
+ | `brain agent` | Generate agent integration files |
124
+ | `brain serve [--host H] [--port P]` | Start REST API server |
125
+
126
+ All commands accept `--repo <path>` to specify a different repository root, `--verbose` for debug logging, and `--timeout N` to set analysis timeout in seconds (default: 120).
127
+
128
+ ## MCP Tools (for AI agents)
129
+
130
+ 22+ tools available via MCP protocol. Key tools:
131
+
132
+ | Tool | Purpose |
133
+ |------|---------|
134
+ | `propose_change` | Validate before writing — the structural safety gate |
135
+ | `impact_analysis` | Trace transitive dependents of any symbol |
136
+ | `get_file_context` | Full file understanding for LLM context |
137
+ | `get_symbol_context` | Full symbol understanding for LLM context |
138
+ | `ask_codebase` | Natural language questions about the codebase |
139
+ | `validate_change` | Check if a file change would break callers |
140
+ | `risk_hotspots` | Find structurally dangerous symbols |
141
+ | `find_dead_code` | Unused symbols with confidence levels |
142
+ | `codebase_overview` | System-level architecture summary |
143
+ | `get_task_context` | Pull relevant context for a development task |
144
+
145
+ See [docs/mcp-tools.md](docs/mcp-tools.md) for full documentation.
146
+
147
+ ## Configuration
148
+
149
+ Create `.codebrain.toml` in your repo root:
150
+
151
+ ```toml
152
+ [codebrain]
153
+ # Extra directories to skip during indexing
154
+ skip_dirs = ["__pycache__", ".git", "node_modules", "vendor"]
155
+
156
+ # File extensions to index
157
+ extensions = [".py", ".ts", ".tsx", ".js", ".jsx"]
158
+
159
+ # Watcher debounce interval (seconds)
160
+ watcher_debounce = 0.5
161
+
162
+ # File count threshold for parallel parsing
163
+ parallel_threshold = 50
164
+
165
+ # Maximum file size to index (KB)
166
+ max_file_size_kb = 1024
167
+ ```
168
+
169
+ Environment variables override the config file:
170
+
171
+ | Variable | Description |
172
+ |----------|-------------|
173
+ | `CODEBRAIN_SKIP_DIRS` | Comma-separated skip directories |
174
+ | `CODEBRAIN_EXTENSIONS` | Comma-separated file extensions |
175
+ | `CODEBRAIN_DEBOUNCE` | Watcher debounce seconds |
176
+ | `CODEBRAIN_PARALLEL_THRESHOLD` | Parallel parsing threshold |
177
+ | `CODEBRAIN_MAX_WORKERS` | Max parallel worker processes |
178
+ | `CODEBRAIN_CLI_TIMEOUT` | CLI analysis timeout in seconds (default: 120) |
179
+
180
+ See [docs/configuration.md](docs/configuration.md) for full reference.
181
+
182
+ ## Language Support
183
+
184
+ - **Python**: Full AST parsing (stable)
185
+ - **TypeScript/JavaScript**: tree-sitter parsing (`pip install codebrain[ts]`)
186
+ - **TypeScript fallback**: regex-based (experimental, limited coverage)
187
+
188
+ ## CI Integration
189
+
190
+ ### Pre-commit Hook
191
+
192
+ ```bash
193
+ brain hook install # validates staged files before every commit
194
+ brain hook uninstall # remove the hook
195
+ ```
196
+
197
+ The hook blocks commits with critical structural violations. Use `git commit --no-verify` to bypass.
198
+
199
+ ### CI Pipeline
200
+
201
+ ```bash
202
+ brain ci --base main # exits 1 if UNSAFE changes detected
203
+ brain ci --base main --json # machine-readable output
204
+ brain ci --fail-on caution # stricter: also fail on CAUTION
205
+ ```
206
+
207
+ ### GitHub Action
208
+
209
+ ```yaml
210
+ # .github/workflows/codebrain.yml
211
+ name: CodeBrain Validation
212
+ on: [pull_request]
213
+ jobs:
214
+ validate:
215
+ runs-on: ubuntu-latest
216
+ steps:
217
+ - uses: actions/checkout@v4
218
+ with:
219
+ fetch-depth: 0
220
+ - uses: actions/setup-python@v5
221
+ with:
222
+ python-version: '3.11'
223
+ - run: pip install codebrain
224
+ - run: brain ci --base origin/main --json
225
+ ```
226
+
227
+ Or use the reusable composite action:
228
+
229
+ ```yaml
230
+ - uses: ./.github/actions/codebrain-validate
231
+ with:
232
+ base-branch: main
233
+ fail-on: unsafe
234
+ ```
235
+
236
+ ## VS Code Extension
237
+
238
+ See [`vscode-extension/`](vscode-extension/) — 5 commands (impact, context, search, validate, hotspots) plus validate-on-save with inline diagnostics.
239
+
240
+ ## REST API
241
+
242
+ ```bash
243
+ pip install codebrain[api]
244
+ brain serve --port 8484
245
+ ```
246
+
247
+ ~20 endpoints at `/api/status`, `/api/search`, `/api/impact/{name}`, `/api/hotspots`, etc. Interactive docs at `/docs`.
248
+
249
+ ## Plugin System
250
+
251
+ Add custom language parsers by implementing `BaseParser` and registering via entry points:
252
+
253
+ ```python
254
+ from codebrain.parser.base import BaseParser
255
+
256
+ class RustParser(BaseParser):
257
+ def extensions(self) -> frozenset[str]:
258
+ return frozenset({".rs"})
259
+
260
+ def parse(self, path, repo_root):
261
+ ... # return ParsedFile
262
+ ```
263
+
264
+ ```toml
265
+ # pyproject.toml
266
+ [project.entry-points."codebrain.parsers"]
267
+ rust = "your_package.parser:RustParser"
268
+ ```
269
+
270
+ ## Architecture
271
+
272
+ ```
273
+ Source Files --> Parser (Python/TS) --> ParsedFile (Nodes + Edges)
274
+ |
275
+ GraphStore (SQLite)
276
+ |
277
+ QueryEngine
278
+ |
279
+ CLI / MCP / REST API / VS Code / Agent Bridge
280
+ ```
281
+
282
+ **Key abstractions:**
283
+
284
+ - **Node** — a code symbol (function, class, method, variable)
285
+ - **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
286
+ - **GraphStore** — CRUD over the SQLite knowledge graph
287
+ - **QueryEngine** — impact analysis, call chains, dead code, cycles
288
+
289
+ ## Validated on Real Codebases
290
+
291
+ CodeBrain has been tested on a 1,328-file mixed Python + TypeScript project (17,756 symbols, 111,793 edges):
292
+
293
+ - **Indexing**: 1,328 files in 135s, zero errors
294
+ - **Health score**: 93/100 in under 5s
295
+ - **Impact analysis**: Traces `getAstroData` → 48 dependents across 69 files
296
+ - **Contracts**: Found `Colors` + `Spacing` co-imported in 141/141 files (confidence 1.0)
297
+ - **Coupling**: Identified `logger.py` ↔ `main.py` (score 140)
298
+ - **Layers**: Detected architectural cycles in `kp-astrology` module
299
+ - **752 tests passing** across unit, integration, and real-world validation
300
+
301
+ ## Development
302
+
303
+ ```bash
304
+ git clone https://github.com/monk0062006/CodeBrain.git
305
+ cd CodeBrain
306
+ pip install -e ".[dev]"
307
+
308
+ pytest tests/ -v # Run tests
309
+ mypy codebrain/ # Type checking
310
+ ruff check codebrain/ # Linting
311
+ pytest --cov=codebrain # Coverage
312
+ ```
313
+
314
+ ## License
315
+
316
+ MIT
@@ -0,0 +1,3 @@
1
+ """CodeBrain — persistent structural knowledge graph for codebases."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,6 @@
1
+ """Allow running as `python -m codebrain`."""
2
+
3
+ from codebrain.cli import cli
4
+
5
+ if __name__ == "__main__":
6
+ cli()