rushikeshmore/CodeCortex

Persistent codebase knowledge layer for AI agents. Pre-builds architecture, dependencies, coupling, and risk knowledge so agents skip the cold start and go straight to the right files.
Website · npm · GitHub
The Problem
Every AI coding session starts with exploration — grepping, reading wrong files, re-discovering architecture. On a 6,000-file codebase, an agent makes 37 tool calls and burns 79K tokens just to understand what's where. And it still can't tell you which files are dangerous to edit or which files secretly depend on each other.
**The data backs this up:**
- AI agents increase defect risk by 30% on unfamiliar code (CodeScene + Lund University, 2025)
- Code churn grew 2.5x in the AI era (GitClear, 211M lines analyzed)
The Solution
CodeCortex eliminates the cold start. It pre-builds codebase knowledge — architecture, dependencies, risk areas, hidden coupling — and injects it directly into your agent's context (CLAUDE.md, .cursorrules, etc.) so agents have project knowledge from the first prompt.
**Not a middleware. Not a proxy. Just knowledge your agent loads on day one.**
Tested on a real 6,400-file codebase (143K symbols, 96 modules):
| | Without CodeCortex | With CodeCortex |
|--|:--:|:--:|
| Tool calls | 37 | **15** (2.5x fewer) |
| Total tokens | 79K | **43K** (~50% fewer) |
| Answer quality | 23/25 | **23/25** (same) |
| Hidden dependencies found | No | **Yes** |
What makes it unique
Three capabilities no other tool provides:
1. **Temporal coupling** — Files that always change together but have zero imports between them. You can read every line and never discover this. Only git co-change analysis reveals it.
2. **Risk scores** — File X has been bug-fixed 7 times, has 6 hidden dependencies, and co-changes with 3 other files. Risk score: 35. You can't learn this from reading code.
3. **Inline context injection** — Project knowledge is injected directly into CLAUDE.md, .cursorrules, and other agent config files with architecture, risk map, and editing directives. Agents use it without any setup.
**Example from a real codebase:**
- schema.help.ts and schema.labels.ts co-changed in 12/14 commits (86%) with **zero imports between them**
- Without this knowledge, an AI editing one file would produce a bug 86% of the time
Quick Start
> **Requires Node 20 or 22.** Node 24 is not yet supported (tree-sitter native bindings need an upstream update).
Connect to Claude Code
**CLI (recommended):**
**Or add to MCP config manually:**
Connect to Cursor
Add to .cursor/mcp.json:
What Gets Generated
All knowledge lives in .codecortex/ as flat files in your repo, plus inline context is injected into agent config files:
Six Knowledge Layers
| Layer | What | File |
|-------|------|------|
| 1. Structural | Modules, deps, symbols, entry points | graph.json + symbols.json |
| 2. Semantic | What each module does, data flow, gotchas | modules/*.md |
| 3. Temporal | Git behavioral fingerprint — coupling, hotspots, bug history | temporal.json |
| 4. Decisions | Why things are built this way | decisions/*.md |
| 5. Patterns | How code is written here | patterns.md |
| 6. Sessions | What changed between sessions | sessions/*.md |
MCP Tools (5)
Five focused tools that provide capabilities agents can't get from reading code:
| Tool | Description |