Content
# Corrdex
Corrdex is a local code intelligence engine for real codebases.
License: `BUSL-1.1`. See [LICENSE](/C:/Users/HRD/code/corrdex/corrdex/LICENSE).
It parses source files into ASTs, builds a semantic dependency graph, classifies files and functions, detects architectural signals, runs repository rules, and exposes that intelligence through:
- a CLI
- an MCP server
- a VS Code extension UI
Corrdex is built for structural code understanding, not just text search. It tries to answer questions like:
- What kind of file is this?
- Is this controller doing direct database work?
- Which functions are real entrypoints?
- What breaks if I change this function?
- Which files are orchestrators, hotspots, or architectural boundaries?
## What Corrdex Ships
This repository contains three user-facing surfaces:
- `corrdex` CLI
- `corrdex-mcp` MCP server launcher
- VS Code extension source
Important distinction:
- the published npm package is the local CLI + MCP package
- this repo also contains the VS Code extension source used during development
## What Corrdex Does
Corrdex performs local static analysis and semantic classification across a project.
Core capabilities:
- Parse TypeScript, JavaScript, Python, SQL, and JSON
- Build a file dependency graph
- Classify files into architectural and semantic types
- Classify individual functions
- Detect workflow paths and runtime entrypoints
- Estimate change impact for files and functions
- Find hotspots, orchestrators, and architectural roles
- Run built-in rules plus custom policy rules
- Expose results through CLI and MCP
Typical outputs include:
- primary file type
- behaviors
- dependency categories
- architectural findings
- architectural roles
- semantic partitions
- domain hints
- workflow paths
- function call relationships
## How Corrdex Works
Corrdex is local-first.
High-level pipeline:
1. Discover project files and project root.
2. Parse source files into language-specific AST metadata.
3. Build a project dependency graph.
4. Run primary file classification.
5. Enrich files with:
- propagated behaviors
- architectural roles
- findings
- workflow paths
- function graph data
6. Run rule checks and produce diagnostics.
7. Serve the results through CLI, MCP, or the extension.
Corrdex is not relying on embeddings or generic RAG for its core understanding. It uses explicit structure:
- AST metadata
- import resolution
- execution blocks
- call/member expressions
- file identities
- dependency categories
- rule-based semantic inference
## Supported Languages
Current built-in parsing support:
- TypeScript
- JavaScript
- TSX
- JSX
- Python
- SQL
- JSON
## Installation
### Install the Published CLI/MCP Package
```bash
npm install -g corrdex
```
This gives you:
- `corrdex`
- `corrdex-mcp`
### Run From This Repository
```bash
npm install
npm run build
node dist/cli/index.js --help
```
### Build the npm Package Output
```bash
npm run build:npm-package
```
The publishable package lives under [packages/npm](/C:/Users/HRD/code/corrdex/corrdex/packages/npm).
## Use With Coding Agents
After installing Corrdex:
```bash
npm install -g corrdex
```
Connect it to any coding agent that supports stdio MCP:
```json
{
"mcpServers": {
"corrdex": {
"command": "corrdex-mcp",
"args": ["C:\\path\\to\\project"]
}
}
}
```
If the agent cannot see global npm binaries on Windows, use the full command path:
```json
{
"mcpServers": {
"corrdex": {
"command": "C:\\Users\\HRD\\AppData\\Roaming\\npm\\corrdex-mcp.cmd",
"args": ["C:\\path\\to\\project"]
}
}
}
```
If you are testing from this repository before npm publish, point the agent at the local build:
```json
{
"mcpServers": {
"corrdex": {
"command": "node",
"args": [
"C:\\Users\\HRD\\code\\corrdex\\corrdex\\dist\\mcp\\server.js",
"C:\\path\\to\\project"
]
}
}
}
```
Corrdex MCP connects immediately, then indexes in the background. If initial indexing is still running, call `getIndexStatus`.
## Quick Start
Initialize a repo and build the first index:
```bash
corrdex init .
```
Index the full project:
```bash
corrdex index .
```
Scan for rule violations:
```bash
corrdex scan .
```
Inspect one file:
```bash
corrdex classify file src/orders/orderService.ts --explain
```
Inspect one function:
```bash
corrdex classify function src/orders/orderService.ts createOrder --explain
```
Estimate file impact:
```bash
corrdex impact src/orders/orderService.ts
```
Start the MCP server:
```bash
corrdex mcp .
```
Or launch the dedicated MCP binary:
```bash
corrdex-mcp .
```
## CLI
Corrdex CLI supports:
- project initialization
- indexing
- scanning
- cache management
- file classification
- function classification
- semantic search
- impact inspection
- architecture summaries
- MCP server launching
Main commands:
```bash
corrdex init [path] [--json]
corrdex scan [path] [--staged] [--branch <name>] [--remote <url>] [--api-key <token>] [--project-id <id>] [--json] [--debug] [--no-cache]
corrdex index [path] [--rebuild] [--remote <url>] [--api-key <token>] [--project-id <id>] [--json]
corrdex check <path> [--json] [--debug] [--explain]
corrdex cache <status|clear> [path] [--json]
corrdex classify file <path> [--json] [--debug] [--explain]
corrdex classify function <path> <functionNameOrId> [--json] [--debug] [--explain]
corrdex find type <primaryType> [path] [--limit <n>] [--all] [--json]
corrdex find behavior <behavior> [path] [--limit <n>] [--all] [--json]
corrdex find role <architecturalRole> [path] [--limit <n>] [--all] [--json]
corrdex impact <path> [--json]
corrdex architecture summary [path] [--json]
corrdex architecture compare <leftPath> <rightPath> [--json]
corrdex architecture diff <baseSnapshot> <headSnapshot> [--json]
corrdex mcp [path]
```
Global flags:
- `--json`
- `--debug`
- `--explain`
- `--quiet`
- `--no-cache`
For the deeper CLI reference, see [CLI.md](/C:/Users/HRD/code/corrdex/corrdex/CLI.md).
## MCP Server
Corrdex exposes its local intelligence through MCP over stdio.
You connect it through the agent's MCP server config.
After `npm install -g corrdex`, the command available to agents is:
```bash
corrdex-mcp C:\path\to\project
```
In any coding agent that supports stdio MCP, add a server entry like this:
```json
{
"mcpServers": {
"corrdex": {
"command": "corrdex-mcp",
"args": ["C:\\path\\to\\project"]
}
}
}
```
If the agent cannot see global npm binaries, use the full command path instead:
```json
{
"mcpServers": {
"corrdex": {
"command": "C:\\Users\\HRD\\AppData\\Roaming\\npm\\corrdex-mcp.cmd",
"args": ["C:\\path\\to\\project"]
}
}
}
```
Before npm publish, you can point an agent directly at the local repo build:
```json
{
"mcpServers": {
"corrdex": {
"command": "node",
"args": [
"C:\\Users\\HRD\\code\\corrdex\\corrdex\\dist\\mcp\\server.js",
"C:\\path\\to\\project"
]
}
}
}
```
Startup behavior:
- MCP connects immediately and does not wait for a full index before transport startup.
- Corrdex bootstraps from `.corrdex-cache.json` when available, then refreshes the full project index in the background.
- If first-time indexing is still running, call `getIndexStatus`.
- File-level tools can start from cache-backed state earlier than function-level tools.
Current MCP tools include:
- `listBehaviors`
- `getIndexStatus`
- `listPrimaryTypes`
- `listArchitecturalRoles`
- `findFiles`
- `findFunctions`
- `getFunctionContext`
- `getFunctionImpact`
- `findEntrypoints`
- `findArchitecturalRoles`
- `findOrchestrators`
- `listArchitecturalFindings`
- `findHotspots`
- `analyzeFile`
- `analyzeImpact`
- `getSemanticContext`
- `getRawClassification`
- `explainArchitecture`
- `summarizeArchitecture`
- `compareModules`
- `compareSnapshots`
- `reindexProject`
Example local use:
```bash
corrdex mcp .
```
The MCP server indexes the target project, hydrates an in-memory semantic registry, and serves deterministic tool outputs from that local project graph.
## VS Code Extension
This repo also contains the Corrdex VS Code extension source.
The extension:
- runs a local language server
- shows a Corrdex sidebar in the Explorer
- provides a Corrdex AI view in the Secondary Sidebar
- refreshes on source/config saves
- reads `corrdex.config.json` and `corrdex.policies.json`
Extension commands:
- `Corrdex: Refresh Sidebar`
- `Corrdex: Open AI`
- `Corrdex: Focus AI`
- `Corrdex: Open AI Settings`
- `Corrdex: Set AI API Key`
- `Corrdex: Clear AI API Key`
- `Corrdex: Open Config`
### Extension Development
Build the extension code:
```bash
npm run build
```
The extension entrypoint is [client/index.ts](/C:/Users/HRD/code/corrdex/corrdex/client/index.ts).
## Configuration
### `corrdex.config.json`
This file controls rule severities for local analysis.
Example:
```json
{
"rules": {
"no-external-api-in-controller": "warning"
}
}
```
Supported severities:
- `off`
- `warning`
- `error`
- `info`
Corrdex also accepts the legacy filename `mergelens.config.json`.
### `corrdex.policies.json`
This file adds compiled policy rules on top of built-in rules.
Example scaffold created by `corrdex init`:
```json
{
"policies": []
}
```
Built-in rules are always loaded first. Policy rules are appended after reading this file.
## Local Cache
Corrdex stores semantic cache data in:
```text
.corrdex-cache.json
```
The cache improves repeated indexing and scanning by reusing prior AST/classification work where possible.
Useful commands:
```bash
corrdex cache status
corrdex cache clear
```
## Optional Remote Upload
The local CLI works without any backend.
If you want to push scan or index results to a backend, `scan` and `index` support:
- `--remote`
- `--api-key`
- `--project-id`
Example:
```bash
corrdex scan . --remote https://api.example.com --api-key key_xxx --project-id proj_123
```
This is optional. Corrdex’s local parsing, indexing, CLI, and MCP flow do not require remote infrastructure.
## What Corrdex Classifies
Corrdex produces structural semantic output at both file and function level.
Examples of file-level concepts:
- controller
- service
- repository
- config
- database-model
- queue-worker
- scheduler
- app-bootstrap
- validator
- dto
Examples of behavior-level concepts:
- database-read
- database-write
- outbound-http-call
- env-config
- filesystem-read
- filesystem-write
- audit-trail
- ai-inference
- queue-processing
- background-processing
Examples of higher-order outputs:
- architectural roles
- architectural findings
- hotspot score
- domain inference
- workflow paths
- function entrypoints
- function blast radius
## Recommended Workflows
### Understand an unfamiliar repo
```bash
corrdex index .
corrdex architecture summary .
corrdex find role integration-boundary . --limit 20
```
### Audit changed files before commit
```bash
corrdex scan --staged
```
### Inspect a suspicious controller
```bash
corrdex classify file src/controllers/orderController.ts --explain
```
### Trace a risky function
```bash
corrdex classify function src/orders/orderService.ts createOrder --explain
corrdex mcp .
```
Then call MCP tools like:
- `getFunctionContext`
- `getFunctionImpact`
- `findEntrypoints`
## Repository Layout
Key directories:
- [core](/C:/Users/HRD/code/corrdex/corrdex/core) - parsers, classifiers, dependency graph, rules, intelligence
- [cli](/C:/Users/HRD/code/corrdex/corrdex/cli) - CLI entrypoint and command handling
- [mcp](/C:/Users/HRD/code/corrdex/corrdex/mcp) - MCP server, runtime, tools, adapters
- [client](/C:/Users/HRD/code/corrdex/corrdex/client) - VS Code extension client UI
- [packages/npm](/C:/Users/HRD/code/corrdex/corrdex/packages/npm) - publishable npm package layout
- [scripts](/C:/Users/HRD/code/corrdex/corrdex/scripts) - build/package helpers
- [test](/C:/Users/HRD/code/corrdex/corrdex/test) - tests
Important files:
- [core/engine.ts](/C:/Users/HRD/code/corrdex/corrdex/core/engine.ts)
- [core/buildDependencyGraph.ts](/C:/Users/HRD/code/corrdex/corrdex/core/buildDependencyGraph.ts)
- [core/classify/classifyFile.ts](/C:/Users/HRD/code/corrdex/corrdex/core/classify/classifyFile.ts)
- [core/classify/classifyFunction.ts](/C:/Users/HRD/code/corrdex/corrdex/core/classify/classifyFunction.ts)
- [mcp/server.ts](/C:/Users/HRD/code/corrdex/corrdex/mcp/server.ts)
- [cli/index.ts](/C:/Users/HRD/code/corrdex/corrdex/cli/index.ts)
## Development
Install dependencies:
```bash
npm install
```
Build:
```bash
npm run build
```
Watch:
```bash
npm run watch
```
Run tests:
```bash
npm test
```
Run the CLI from the built output:
```bash
node dist/cli/index.js --help
```
Run the MCP server from the built output:
```bash
node dist/mcp/server.js .
```
Prepare the npm package:
```bash
npm run prepare:npm-package
```
Build and prepare the npm package:
```bash
npm run build:npm-package
```
## Current Scope
Corrdex is strongest today at:
- structural code understanding
- architectural inspection
- deterministic local analysis
- function/file impact reads
- MCP-driven code intelligence
It is intentionally not trying to be:
- a generic code completion engine
- a text-only grep replacement
- an LLM-only repo understanding layer
## Summary
Corrdex gives you a local semantic graph of a codebase and makes it usable through CLI, MCP, and VS Code.
If you want the fastest path to value:
```bash
npm install -g corrdex
corrdex init .
corrdex index .
corrdex scan .
corrdex mcp .
```
