Corrdex

Corrdex is a local code intelligence CLI and MCP server for real codebases.

It parses source files into ASTs, builds a semantic dependency graph, classifies files and functions, detects architectural signals, and exposes that intelligence through:

• a CLI
• an MCP server for coding agents

Corrdex is built for structural code understanding, not just text search. It is meant to answer questions like:

• What kind of file is this?
• Which functions are real entrypoints?
• What breaks if I change this file or function?
• Which files are orchestrators, hotspots, or architectural boundaries?
• Where is database access, messaging, outbound HTTP, or workflow orchestration happening?

What This Package Includes

Installing this package gives you these binaries:

• corrdex
• corrdex-mcp
• mergelens as a compatibility alias

This npm package is the local CLI + MCP distribution. It does not include the VS Code extension.

What Corrdex Does

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

Installation

npm install -g corrdex

Quick Start

Initialize a repo:

corrdex init .

Build a local semantic index:

corrdex index .

Scan for rule violations:

corrdex scan .

Inspect one file:

corrdex classify file src/orders/orderService.ts --explain

Inspect one function:

corrdex classify function src/orders/orderService.ts createOrder --explain

Start the MCP server:

corrdex-mcp .

CLI

Main commands:

corrdex init [path] [--json]
corrdex login [--server <url>] [--client-name <name>] [--path <codebase>] [--json]
corrdex logout [--json]
corrdex whoami [--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 memory save --title <title> --summary <summary> [path] [--details <text>] [--tag <tag>]... [--file <path>]... [--json]
corrdex memory list [path] [--query <text>] [--tag <tag>] [--file <path>] [--limit <n>] [--json]
corrdex memory show <id> [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

Hosted Login And Remote Index

Use this section when you want the local CLI to authenticate with hosted Corrdex and push one specific codebase.

Login

corrdex login --path .

What To Expect During Login

1. Corrdex starts the hosted CLI login flow.
2. Your browser opens the Corrdex approval page.
3. You approve access in the browser.
4. In the terminal, Corrdex binds the hosted session to a codebase path.
5. If you did not pass --path, Corrdex asks for the codebase path before login finishes.
6. Corrdex resolves the repo root from that path and stores it with the hosted session.
7. Login is not complete until that repo root is saved locally.

Index To Hosted Corrdex

corrdex index . --remote

What Remote Index Does

• corrdex index --remote runs one local analysis session.
• It pushes the index run and the scan run from that same local session.
• Remote output prints the selected codebase path so you can verify which repo is being pushed.

Current Limitation

• One saved hosted login is bound to one repo root.
• corrdex index --remote and corrdex scan --remote only work for that bound repo root.
• If you run a remote push from a different repo, Corrdex refuses to push.
• To push another repo, run corrdex login again and bind the hosted session to that other codebase.

Use With Coding Agents

You connect Corrdex to agents through the agent's MCP server config.

After installing Corrdex, the command available to agents is:

corrdex-mcp C:\path\to\project

In any coding agent that supports stdio MCP, add a server entry like this:

{
  "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 instead:

{
  "mcpServers": {
    "corrdex": {
      "command": "C:\\Users\\HRD\\AppData\\Roaming\\npm\\corrdex-mcp.cmd",
      "args": ["C:\\path\\to\\project"]
    }
  }
}

Typical flow:

1. Install corrdex.
2. Add the MCP config to the coding agent.
3. Restart or reload the agent.
4. The agent connects to Corrdex over stdio.
5. Corrdex starts immediately and indexes in the background.
6. The agent can call getIndexStatus, then use other tools.

For endpoint-style questions, start with findRoutes. Corrdex surfaces concrete route registrations, including method, path, handler, and middleware names when the codebase structure supports it.

MCP Server

Corrdex exposes its local intelligence through MCP over stdio.

Current MCP tools include:

• getIndexStatus
• saveTaskMemory
• listTaskMemories
• getTaskMemory
• listBehaviors
• listPrimaryTypes
• listArchitecturalRoles
• findFiles
• findFunctions
• getFunctionContext
• getFunctionImpact
• findRoutes
• findEntrypoints
• findArchitecturalRoles
• findOrchestrators
• listArchitecturalFindings
• findHotspots
• analyzeFile
• analyzeImpact
• getSemanticContext
• getRawClassification
• explainArchitecture
• summarizeArchitecture
• compareModules
• compareSnapshots
• reindexProject

Guidance:

• Use findRoutes first for questions mentioning route, endpoint, GET, POST, PATCH, DELETE, login, logout, middleware, or handler.
• Use findEntrypoints after that when you want the broader runtime flow beyond a specific endpoint.
• Use saveTaskMemory at the end of a task to persist compact decisions, touched files, and next steps for the repo.
• Use listTaskMemories and getTaskMemory at the start of a follow-up task so the agent can recover prior context without replaying the full chat.

Current MCP prompt:

• corrdex-agent-workflow

Current MCP resource:

• corrdex://agent-guidance

Recommended task memory shape:

• title: short task/topic name, preferably <area>: <outcome>
• summary: 1-2 sentence outcome
• details: compact sections like Decisions:, Constraints:, Verification:, Next steps:
• tags: 2-5 stable keywords
• files: only the touched or critical repo-relative paths

Startup behavior:

• MCP transport connects immediately; it does not wait for a full index first.
• 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.

Supported Languages

• TypeScript
• JavaScript
• TSX
• JSX
• Python
• SQL
• JSON

License

BUSL-1.1