CodeCortex is a persistent codebase knowledge layer for AI coding agents. Its goal is to eliminate the cold-start problem of AI coding sessions: every AI coding session starts with exploration—grep, reading the wrong files, rediscovering the architecture. On a 6,000-file codebase, an agent needs 37 tool calls and consumes 79K tokens just to understand where files are located, and it still cannot determine which files are dangerous to edit or which files have hidden dependencies between them. CodeCortex pre-builds codebase knowledge (architecture, dependencies, risk areas, hidden coupling) and injects it directly into the agent's context (CLAUDE.md, .cursorrules, etc.), so the agent has project knowledge from the very first prompt. It is not middleware, nor a proxy—it is simply knowledge that the agent loads on day one.
Main capabilities
- Temporal coupling: Identifies files that always change together but have no imports between them. This cannot be discovered by reading code alone; only git co-change analysis can reveal it.
- Risk scores: For example, if a file has had bugs fixed 7 times, has 6 hidden dependencies, and co-changes with 3 other files, its risk score is 35. This kind of information cannot be obtained by reading code.
- Inline context injection: Injects project knowledge directly into CLAUDE.md, .cursorrules, and other agent configuration files, including architecture, risk maps, and editing instructions, so the agent can use it without any setup.
How to use Requires Node 20 or 22; Node 24 is not currently supported (tree-sitter native bindings require an upstream update). Connect to Claude Code: The CLI is recommended, or manually add it to the MCP configuration. Connect to Cursor: Add it to .cursor/mcp.json.
Generated content All knowledge is stored as flat files in the repository's .codecortex/ directory, while inline context is injected into agent configuration files. It includes six layers of knowledge, five focused tools (providing capabilities the agent cannot obtain from reading code), 3 MCP resources (static knowledge that can be obtained without tool calls), and 2 MCP prompts.
Technical implementation Hybrid extraction: tree-sitter native N-API for structure (symbols, imports, calls across 27 languages) + host LLM for semantics (what a module does, why it was built this way). No additional API keys are required. Inline context injection: After analysis, CodeCortex injects rich knowledge sections directly into CLAUDE.md and other agent configuration files, including an architecture overview, a risk map with coupled file names, and editing instructions. Git hooks keep knowledge fresh: Automatically runs codecortex update on every commit, re-extracts changed files, and updates temporal analysis. Size-adaptive responses: CodeCortex classifies projects (micro → extra-large) and adjusts response limits accordingly. A 23-file project gets full detail, while a 6,400-file project gets an intelligent summary. Each MCP tool response stays within 10K characters.
Supported languages (27) TypeScript ESM, Node.js 20+. Dependencies include tree-sitter (native N-API) + 27 language grammar packages, @modelcontextprotocol/sdk (MCP server), commander (CLI), simple-git (git integration), yaml, zod, glob.
Use cases Suitable for development scenarios that require AI coding agents to quickly understand large codebases, avoid cold-start exploration, and identify high-risk editing areas and hidden dependencies.
Limitations Requires Node 20 or 22; Node 24 is not currently supported. Other limitations are not yet provided.
