llms.txt

# Codebase Intelligence

> TypeScript codebase analysis engine — dependency graphs, architectural metrics, MCP + CLI interfaces.

## Documentation

- [Architecture](docs/architecture.md): Pipeline, module map, data flow, design decisions
- [Data Model](docs/data-model.md): All TypeScript interfaces with field descriptions
- [Metrics](docs/metrics.md): Per-file and module metrics, force analysis, complexity scoring
- [MCP Tools](docs/mcp-tools.md): 29 MCP tools — inputs, outputs, use cases, selection guide
- [CLI Reference](docs/cli-reference.md): CLI commands, flags, output formats, examples

## Quick Start

MCP mode (AI agents):
```bash
codebase-intelligence ./path/to/project
```

CLI mode (humans/CI) — 35 public commands (29 MCP-backed analysis tools + CI/dev workflows):
```bash
codebase-intelligence overview ./src
codebase-intelligence hotspots ./src --metric cognitive_complexity
codebase-intelligence file ./src parser/index.ts
codebase-intelligence search ./src "auth"             # keyword or type/shape query
codebase-intelligence changes ./src --json
codebase-intelligence dependents ./src types.ts --depth 3
codebase-intelligence modules ./src
codebase-intelligence forces ./src
codebase-intelligence dead-exports ./src
codebase-intelligence opportunities ./src --limit 10
codebase-intelligence duplicates ./src --mode mild --min-tokens 30
codebase-intelligence groups ./src
codebase-intelligence symbol ./src parseCodebase
codebase-intelligence impact ./src getUserById
codebase-intelligence rename ./src oldName newName
codebase-intelligence processes ./src --entry main
codebase-intelligence map ./src --focus getUserById --context-budget 800 --json
codebase-intelligence drift ./src --min-score 50 --json
codebase-intelligence health ./src --score --min-score 70
codebase-intelligence boundaries ./src --preset layered --list --json
codebase-intelligence highways ./src --operation create --min-routes 3 --propose --json
codebase-intelligence clusters ./src --min-files 3
codebase-intelligence owners ./src --group-by owner --json
codebase-intelligence architecture ./src --json
codebase-intelligence workspaces . --base origin/main --changed --json
codebase-intelligence lsp ./src --diagnostics --json
codebase-intelligence watch ./src --once --json
codebase-intelligence ci ./src --base origin/main --new-only --changed-workspaces --format json
codebase-intelligence doctor . --profile agent --agent codex --json
codebase-intelligence migrate-config . --json
codebase-intelligence hooks install . --json          # dry-run by default; add --apply to write
codebase-intelligence history . --json
codebase-intelligence explain no-dead-exports --json
codebase-intelligence check ./src                     # rules gate for CI; JSON includes findings plus active/stale suppressions
codebase-intelligence init .                          # make AI agents use CI
```

## Behavior Notes

- CLI analysis commands cache to `.codebase-intelligence/`; legacy `.code-visualizer/` is migration input only. Run `codebase-intelligence init --gitignore` to ignore the canonical cache directory.
- `overview --json` includes `analysis.mode`, `analysis.callGraphPrecision`, and `analysis.fullProgramFileLimit`.
- Analysis commands with `--json` and `init --json` include `cache`: `cacheDir`, `legacyCacheDir`, `migrated`, `gitignoreUpdated`, `warnings[]`.
- Repos above the full-program file limit use AST-only extraction; dependency metrics remain available, call graph precision becomes syntax-only.

## Optional

For complete documentation in a single file, see [llms-full.txt](llms-full.txt).