Codebase Intelligence
CLI-first TypeScript codebase analysis with hotspots, impact, dead-export detection, and architecture metrics. Includes optional MCP server for AI agents.
Ask AI about Codebase Intelligence
Powered by Claude Β· Grounded in docs
I know everything about Codebase Intelligence. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
- Security
- 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)
- Parser β extracts files, functions, and imports via TypeScript Compiler API.
- Graph β builds dependency/call graphs with graphology.
- Analyzer β computes file/module/symbol metrics.
- Interfaces β CLI is primary; MCP is available for agent integrations.
Requirements
- Node.js >= 18
- TypeScript codebase (
.ts/.tsxfiles)
Limitations
- TypeScript-focused analysis
- Static analysis only (no runtime tracing)
- Call graph confidence varies by symbol resolution quality
Release
Publishing is automated through GitHub Actions.
Normal CI (before release)
CIworkflow runs on every PR and push tomain:- lint β typecheck β build β test
Canary publish
- Pushes to
maintrigger a canary publish. - The package is published to npm with the
canarytag. - Canary versions are derived from the current package version plus the short commit SHA.
Create a release
- Bump
package.jsonversion in a normal PR. - Merge that PR to
main. - Run the
Publishworkflow manually from GitHub Actions. - The workflow will:
- verify the tag does not already exist
- create and push
vX.Y.Z - publish to npm with provenance via OIDC
- create a GitHub Release with generated notes
No PAT is required for npm publish. The workflow uses GitHub repository permissions for tagging and OIDC for npm publishing.
Security
Please do not report security vulnerabilities in public issues.
- Read
SECURITY.mdfor supported versions and disclosure guidance. - Use GitHub Security Advisories or private maintainer contact for sensitive reports.
Contributing
Contributions are welcome.
Start here:
CONTRIBUTING.mdβ setup, workflow, testing, and PR expectationsCODE_OF_CONDUCT.mdβ community standardsSECURITY.mdβ vulnerability reporting
Quick setup:
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
