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