npx codebase-intelligence overview ./src

Common workflows:

npx codebase-intelligence hotspots ./src --metric complexity --limit 10
npx codebase-intelligence opportunities ./src --limit 10
npx codebase-intelligence duplicates ./src --mode mild --min-tokens 30
npx codebase-intelligence impact ./src parseCodebase
npx codebase-intelligence dead-exports ./src --limit 20
npx codebase-intelligence changes ./src --json
npx codebase-intelligence boundaries ./src --preset layered --list --json

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

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

• 24 CLI commands for architecture analysis, dependency impact, duplicate families, focused map/context packs, content drift, health scoring, boundary enforcement, Highways convergence, improvement opportunities, dead code detection, search, CI rules, and agent setup
• Machine-readable JSON output (--json) for automation and CI pipelines
• Auto-cached index in .codebase-intelligence/ for fast repeat queries
• Cache migration facts in JSON (cacheDir, legacyCacheDir, migrated, gitignoreUpdated, warnings[])
• Quality metrics — PageRank, betweenness, coupling, cohesion, tension, churn, cyclomatic/cognitive complexity, blast radius, dead exports, test coverage, escape velocity, risk, maintainability, and CRAP score
• Symbol-level analysis — callers/callees, symbol importance, impact blast radius
• BM25 search — ranked keyword search across files, symbols, and type/shape facts
• Process tracing — detect entry points and execution flows through the call graph
• Codebase maps + context packs — focused file/symbol/test graph with deterministic evidence IDs and token-bounded context for agents
• Content drift — report-only detection for file/name/scope/side-effect/shape/test placement mismatch with stable evidence
• Health score — CI-gateable composite score with per-file maintainability, CRAP, coverage source, and risk hotspots
• Highways analysis — find repeated routes that bypass canonical dataflow paths and synthesize safe proposed highways
• Community detection — Louvain clustering for natural file groupings
• Agent adoption — init writes per-agent instruction files + installs a skill so AI agents query CI before grep/read
• MCP parity (secondary) — same analysis and rules gate available as 25 MCP tools, 2 prompts, and 3 resources

Run directly with npx (no install):

npx codebase-intelligence overview ./src

Or install globally:

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

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

The scanner always excludes common generated and agent-workspace directories such as .codebase-intelligence/, legacy .code-visualizer/, .next/, dist/, coverage/, .worktrees/, and .claude/worktrees/.

Analysis commands with --json and init --json include a top-level cache object with the canonical cache path, legacy cache path, migration status, .gitignore update status, and non-fatal cache warnings.

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

codebase-intelligence has the data — but AI agents only benefit if they actually query it instead of defaulting to grep/read. init closes that gap.

codebase-intelligence init                  # interactive picker (TTY)
codebase-intelligence init --agents claude,cursor
codebase-intelligence init --all --skill    # every agent + global skill
codebase-intelligence init --yes            # non-interactive defaults

Nothing is written unless you choose it. On a terminal, init shows an interactive picker (AGENTS.md + CLAUDE.md preselected); non-interactively it defaults to those two. The global skill is opt-in (--skill). It writes an idempotent, marked instruction block ("query CI before grep/read") into each selected agent's native file:

Writes are idempotent — only content between the <!-- codebase-intelligence:start --> / :end markers is ever touched, so re-running is safe and your own edits are preserved.

The skill is also published to the skills.sh registry:

ags install codebase-intelligence
# or
npx skills add github.com/bntvllnt/codebase-intelligence

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

npx codebase-intelligence ./src

Add to .mcp.json:

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

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.

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.

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

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

Publishing is automated through GitHub Actions. See CHANGELOG.md for release notes.

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

• Pushes to main trigger a canary publish.
• The package is published to npm with the canary tag.
• Canary versions are derived from the current package version plus the short commit SHA.

1. Bump package.json version in a normal PR.
2. Merge that PR to main.
3. Run the Publish workflow manually from GitHub Actions.
4. 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.

Please do not report security vulnerabilities in public issues.

• Read SECURITY.md for supported versions and disclosure guidance.
• Use GitHub Security Advisories or private maintainer contact for sensitive reports.

Contributions are welcome.

Start here:

• CONTRIBUTING.md — setup, workflow, testing, and PR expectations
• CODE_OF_CONDUCT.md — community standards
• SECURITY.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
pnpm verify:cli-real        # default real-repo CLI matrix
pnpm verify:cli-real:heavy  # large /home/ubuntu repo matrix

MIT