convez.ai
MCP Server
bntvllnt

codebase-intelligence

bntvllnt/codebase-intelligence

Ver no GitHub
BomPluginScore · de 0 a 100

CLI-first TypeScript codebase analysis with hotspots, impact, dead-export detection, and architecture metrics. Includes optional MCP server for AI agents.

Instalação

$npx convez-ai bntvllnt/codebase-intelligence

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 3 semanas
Versão
v2.4.1
Issues abertas
2
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

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.

License: MIT Node TypeScript


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

  • 16 CLI commands for architecture analysis, dependency impact, dead code detection, search, and agent setup
  • 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
  • Agent adoption — init writes per-agent instruction files + installs a skill so AI agents query CI before grep/read
  • 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

CommandWhat it does
overviewHigh-level codebase snapshot
hotspotsRank files by metric (coupling, churn, complexity, blast radius, coverage, etc.)
fileFull context for one file
searchBM25 keyword search
changesGit diff analysis with risk metrics
dependentsFile-level blast radius
modulesModule architecture + cross-dependencies
forcesCohesion/tension/escape-velocity analysis
dead-exportsUnused export detection
groupsTop-level directory groups + aggregate metrics
symbolCallers/callees and symbol metrics
impactSymbol-level blast radius
renameReference discovery for rename planning
processesEntry-point execution flow tracing
clustersCommunity-detected file clusters
initSet up AI agents to use CI — writes per-agent instruction files (skill opt-in via --skill)

Useful flags

FlagDescription
--jsonStable JSON output
--forceRebuild 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.

Agent Adoption

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:

LayerTargetDefault
Repo instructionsAGENTS.md, CLAUDE.mdselected
Repo instructions.cursor/rules/*.mdc, .github/copilot-instructions.md, GEMINI.md, CONVENTIONS.md (Aider)opt-in
Portable skill~/.claude/skills/codebase-intelligence/SKILL.mdopt-in (--skill)

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.

Install the skill directly

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

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

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

MetricWhat it reveals
PageRankMost-referenced files (importance)
BetweennessBridge files between disconnected modules
CouplingHow tangled a file is (fan-out / total connections)
CohesionDoes a module belong together? (internal / total deps)
TensionIs a file torn between modules? (entropy of cross-module pulls)
Escape VelocityShould this module be its own package?
ChurnGit commit frequency
ComplexityAverage cyclomatic complexity of exports
Blast RadiusTransitive dependents affected by a change
Dead ExportsUnused exports (safe to remove)
Test CoverageWhether 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 through GitHub Actions. See CHANGELOG.md for release notes.

Normal CI (before release)

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

Canary publish

  • 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.

Create a release

  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.

Security

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.

Contributing

Contributions are welcome.

Start here:

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

License

MIT

Ver o original no GitHub

Bom para

Relacionados