codebase-intelligence

CLI-first codebase analysis for TypeScript projects.

Parse your codebase, build a dependency graph, compute architectural metrics, and query everything from your terminal/CI. MCP support is included as an optional secondary interface.

Quick Start

CLI (recommended)

npx codebase-intelligence overview ./src

Common workflows:

npx codebase-intelligence hotspots ./src --metric complexity --limit 10
npx codebase-intelligence impact ./src parseCodebase
npx codebase-intelligence dead-exports ./src --limit 20
npx codebase-intelligence changes ./src --json

MCP (optional)

claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelligence@latest .

Table of Contents

• Features
• Installation
• CLI Usage
• MCP Integration (Secondary)
• Metrics
• Architecture
• Requirements
• Limitations
• Release
• Contributing
• License

Features

• 15 CLI commands for architecture analysis, dependency impact, dead code detection, and search
• Machine-readable JSON output (--json) for automation and CI pipelines
• Auto-cached index in .code-visualizer/ for fast repeat queries
• 11 architectural metrics — PageRank, betweenness, coupling, cohesion, tension, churn, complexity, blast radius, dead exports, test coverage, escape velocity
• Symbol-level analysis — callers/callees, symbol importance, impact blast radius
• BM25 search — ranked keyword search across files and symbols
• Process tracing — detect entry points and execution flows through the call graph
• Community detection — Louvain clustering for natural file groupings
• MCP parity (secondary) — same analysis available as 15 MCP tools, 2 prompts, and 3 resources

Installation

Run directly with npx (no install):

npx codebase-intelligence overview ./src

Or install globally:

npm install -g codebase-intelligence
codebase-intelligence overview ./src

CLI Usage

codebase-intelligence <command> <path> [options]

Commands

| Command | What it does | |---|---| | overview | High-level codebase snapshot | | hotspots | Rank files by metric (coupling, churn, complexity, blast radius, coverage, etc.) | | file | Full context for one file | | search | BM25 keyword search | | changes | Git diff analysis with risk metrics | | dependents | File-level blast radius | | modules | Module architecture + cross-dependencies | | forces | Cohesion/tension/escape-velocity analysis | | dead-exports | Unused export detection | | groups | Top-level directory groups + aggregate metrics | | symbol | Callers/callees and symbol metrics | | impact | Symbol-level blast radius | | rename | Reference discovery for rename planning | | processes | Entry-point execution flow tracing | | clusters | Community-detected file clusters |

Useful flags

| Flag | Description | |---|---| | --json | Stable JSON output | | --force | Rebuild index even if cache is valid | | --limit <n> | Limit results on supported commands | | --metric <m> | Select ranking metric for hotspots |

For full command details, see docs/cli-reference.md.

MCP Integration (Secondary)

Running without a subcommand starts the MCP stdio server (backward compatible):

npx codebase-intelligence ./src

Claude Code (manual)

Add to .mcp.json:

{
  "mcpServers": {
    "codebase-intelligence": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codebase-intelligence@latest", "./src"],
      "env": {}
    }
  }
}

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "codebase-intelligence": {
      "command": "npx",
      "args": ["-y", "codebase-intelligence@latest", "./src"]
    }
  }
}

For MCP tool details, see docs/mcp-tools.md.

Metrics

| Metric | What it reveals | |--------|-----------------| | PageRank | Most-referenced files (importance) | | Betweenness | Bridge files between disconnected modules | | Coupling | How tangled a file is (fan-out / total connections) | | Cohesion | Does a module belong together? (internal / total deps) | | Tension | Is a file torn between modules? (entropy of cross-module pulls) | | Escape Velocity | Should this module be its own package? | | Churn | Git commit frequency | | Complexity | Average cyclomatic complexity of exports | | Blast Radius | Transitive dependents affected by a change | | Dead Exports | Unused exports (safe to remove) | | Test Coverage | Whether a test file exists for each source file |

Architecture

codebase-intelligence <command> <path>
        |
        v
   +---------+     +---------+     +----------+
   | Parser  | --> | Graph   | --> | Analyzer |
   | TS AST  |     | grapho- |     | metrics  |
   |         |     | logy    |     |          |
   +---------+     +---------+     +----------+
        |
        +--> CLI output (default)
        +--> MCP stdio (optional mode)

1. Parser — extracts files, functions, and imports via TypeScript Compiler API.
2. Graph — builds dependency/call graphs with graphology.
3. Analyzer — computes file/module/symbol metrics.
4. Interfaces — CLI is primary; MCP is available for agent integrations.

Requirements

• Node.js >= 18
• TypeScript codebase (.ts / .tsx files)

Limitations

• TypeScript-focused analysis
• Static analysis only (no runtime tracing)
• Call graph confidence varies by symbol resolution quality

Release

Publishing is automated and only happens on v* tags.

One-time setup

1. Create an npm automation token (npmjs.com → Access Tokens).
2. Add it to GitHub repository secrets as NPM_TOKEN.

Normal CI (before release)

• CI workflow runs on every PR and push to main:
  • lint → typecheck → build → test

Create a release

1. Bump package.json version.
2. Commit: chore(release): bump to vX.Y.Z
3. Tag: git tag vX.Y.Z
4. Push: git push origin main --tags

The v* tag triggers the CI workflow publish job (npm publish --access public --provenance).

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

git clone https://github.com/bntvllnt/codebase-intelligence.git
cd codebase-intelligence
pnpm install
pnpm dev          # tsx watch mode
pnpm test         # vitest
pnpm lint         # eslint
pnpm typecheck    # tsc --noEmit
pnpm build        # production build

License

MIT