npm package: @gingerdev/codemap-cli
Description: Static analysis CLI that generates relationship maps of codebases for AI-assisted development
Author: Edmund Hee
Latest version: 0.4.0

# codemap

A static analysis CLI that generates relationship maps of your codebase — classes, functions, imports, call graphs, type dependencies — and exposes them via MCP so AI coding assistants can understand your project without re-scanning it every session.

## Why

Every time an AI assistant works on your code, it spends tokens exploring the codebase: grepping for functions, reading files, following imports, building mental models from scratch. On large projects this means 10–20 tool calls just to understand how one feature connects.

codemap does this once, up front. It parses your entire codebase, builds a structured JSON map of all relationships, and serves it on demand via MCP. Instead of:

```
grep "createOrder" → 8 files → read file 1 → see import → read file 2 → grep again...
```

The assistant does:

```
codemap_query("createOrder") → defined in orders/service.ts, calls [validatePayment, calculateTotal],
                                called by [OrderController.create, checkout.handler]
```

One call instead of ten.

## Terminology

| Term | Meaning |
|------|---------|
| **Codemap** | The generated JSON + Markdown output describing your project's structure and relationships |
| **Call graph** | A map of which functions call which other functions |
| **Reverse call graph** | The inverse — which functions are called by which callers (useful for dead code detection and impact analysis) |
| **Import graph** | File-level dependency tree showing which files import from which other files |
| **Module** | A directory within your project, treated as a logical unit in the codemap output |
| **MCP** | Model Context Protocol — a standard for AI tools to discover and use external capabilities |
| **Framework detection** | Automatic identification of frameworks (Express, FastAPI, etc.) from config files and dependencies |

## Installation

```bash
# Install globally via npm
npm install -g @gingerdev/codemap-cli

# Or install as a project dependency (auto-creates Claude Code commands)
npm install @gingerdev/codemap-cli
```

Requires Node.js >= 18.

## Quick Start

```bash
# Generate a codemap for your project
cd /path/to/your/project
codemap init          # creates .codemaprc
codemap generate      # parses codebase, writes .codemap/

# Query from CLI
codemap query --search "createOrder"
codemap query --function "validatePayment"
codemap query --callers "UserService.create"
codemap query --class "OrderController"

# Connect to Claude Code via MCP
claude mcp add codemap -- codemap-mcp /path/to/your/project
```

## Commands

### `codemap init`

Creates a `.codemaprc` configuration file with auto-detected include directories and default excludes.

```bash
codemap init                  # create config in current directory
codemap init --path ./myapp   # create config in a specific directory
codemap init --force          # overwrite existing config
```

### `codemap generate`

Parses the codebase and generates the codemap output.

```bash
codemap generate              # generate in current directory
codemap generate --path ./app # generate for a specific project
```

Output is written to `.codemap/`:

```
.codemap/
├── codemap.json       # Full structured data (classes, functions, call graphs, etc.)
├── codemap.md         # Compact root summary (~1500-2000 lines for large projects)
├── modules/           # Per-directory detailed markdown files
│   ├── src__core.md
│   ├── src__api.md
│   └── ...
└── .hashes            # Content hashes for change detection
```

### `codemap query`

Search and inspect the generated codemap.

```bash
codemap query --function <name>     # Query a function by name
codemap query --class <name>        # Query a class
codemap query --file <path>         # Query a file (partial match supported)
codemap query --module <dir>        # Query a directory/module
codemap query --type <name>         # Query a type/interface
codemap query --search <term>       # Search across everything
codemap query --callers <name>      # Show what calls a function
codemap query --calls <name>        # Show what a function calls
codemap query --json                # Output as JSON
```

### `codemap analyze`

Run structural analysis on the generated codemap to find issues.

```bash
codemap analyze --dead-code         # Detect unused functions and methods
codemap analyze --duplicates        # Detect redundant/duplicate functions
codemap analyze --circular          # Detect circular dependencies
codemap analyze --all               # Run all checks at once
codemap analyze --all --json        # Output raw JSON for scripting
```

### `codemap health`

Show a project health score (0–100) with metrics, hotspots, and coupling data.

```bash
codemap health                      # Show full health report
codemap health --summary            # One-line score only
codemap health --json               # Output raw JSON
codemap health --gate               # Exit code 1 if below threshold (CI mode)
codemap health --gate --threshold 80  # Custom minimum score
codemap health --no-degrade         # Fail if score dropped from last run
```

The health score factors in complexity, dead code, god classes, nesting depth, and module coupling. Run `codemap generate` at least twice to see trend data.

### `codemap diff`

Show what changed in the codebase since the last codemap generation.

```bash
codemap diff                        # Show changes since last generation
codemap diff --update               # Show changes, then regenerate
```

## Configuration

The `.codemaprc` file controls what gets scanned and how. Created by `codemap init`.

```json
{
  "include": ["."],
  "exclude": [
    "node_modules",
    "__pycache__",
    "dist",
    "build",
    "lib",
    ".git",
    ".codemap",
    "*.test.*",
    "*.spec.*",
    "*.min.*",
    "coverage",
    "vendor",
    ".next",
    ".nuxt",
    "venv",
    ".venv",
    "env",
    ".env",
    ".tox",
    "eggs",
    "*.egg-info",
    ".mypy_cache",
    ".pytest_cache",
    ".ruff_cache",
    "site-packages",
    "migrations"
  ],
  "projects": [
    "/path/to/project-a",
    { "name": "my-api", "root": "/path/to/project-b" }
  ]
}
```

| Field | Description |
|-------|-------------|
| `include` | Directories to scan. `["."]` scans everything from root. |
| `exclude` | Patterns to exclude. Supports directory names and glob patterns. |
| `projects` | (MCP only) List of project paths for multi-project MCP server. |
| `framework` | Override framework detection (default: auto-detect). |
| `output` | Output directory (default: `.codemap`). |
| `detail` | `"full"` for complete signatures, `"names-only"` for compact output. |
| `features` | Toggle specific analysis: `call_graph`, `import_graph`, `routes`, `models`, `types`, `data_flow`, `config_deps`, `middleware`. |

## MCP Server (Claude Code Integration)

The MCP server exposes codemap data as tools that Claude Code can call automatically.

### Setup

```bash
# Single project
claude mcp add codemap -- codemap-mcp /path/to/your/project

# Multiple projects via CLI args
claude mcp add codemap -- codemap-mcp ~/Work/project-a ~/Work/project-b

# Multiple projects via .codemaprc (reads "projects" field)
claude mcp add codemap -- codemap-mcp
```

For the config-based approach, add a `projects` array to `~/.codemaprc` or your project's `.codemaprc`.

### Available MCP Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `codemap_projects` | List all registered projects and their status | none |
| `codemap_overview` | Project summary: modules, frameworks, languages, file counts, dependencies | `project?` |
| `codemap_module` | Detailed info for a specific directory | `directory`, `project?` |
| `codemap_query` | Search by function, class, type, or file name (exact + fuzzy) | `name`, `project?` |
| `codemap_callers` | Find what calls a given function | `name`, `project?` |
| `codemap_calls` | Find what a given function calls | `name`, `project?` |

The `project` parameter is optional when only one project is registered. With multiple projects, Claude Code will select the right one based on context.

### Claude Code Commands

codemap ships with slash commands for Claude Code that orchestrate multi-step workflows using the MCP tools. These are created automatically in `.claude/commands/` when you run `codemap init`, `codemap generate`, or `npm install @gingerdev/codemap-cli`.

| Command | Description |
|---------|-------------|
| `/codemap-explore` | Understand the project structure and architecture |
| `/codemap-find-reusable` | Search for existing code to reuse before writing new functions |
| `/codemap-impact` | Analyze blast radius before refactoring or modifying code |
| `/codemap-plan` | Create an implementation plan grounded in actual code structure |
| `/codemap-health-review` | Review code quality and identify what to refactor next |
| `/codemap-refresh` | Regenerate codemap when source files have changed |

Commands accept arguments after the name. For example:

```
/codemap-find-reusable config parsing logic
/codemap-impact UserService.validate
/codemap-plan add WebSocket support
```

## Language Support

| Language | Parser | File Extensions | Features |
|----------|--------|-----------------|----------|
| TypeScript | ts-morph | `.ts`, `.tsx` | Classes, functions, imports, exports, types, interfaces, enums, decorators, call expressions, env vars |
| JavaScript | ts-morph | `.js`, `.jsx`, `.mjs`, `.cjs` | Same as TypeScript |
| Python | web-tree-sitter (WASM) | `.py` | Classes with inheritance, functions, imports (`import`/`from`), decorators, type hints, `__all__` exports, env vars (`os.environ`, `os.getenv`) |
| Vue | Vue parser + ts-morph | `.vue` | Extracts `<script setup>` or `<script>` blocks for full TS analysis. Captures `<template>` component references (PascalCase and kebab-case) in call graph. |

### Python-Specific Features

- Method access levels from naming conventions (`_protected`, `__private`, `public`)
- `__all__` export list detection
- Supports `import x`, `from x import y`, and `from . import z` patterns
- Async function detection

### Vue-Specific Features

- Prefers `<script setup>` over `<script>` when both exist
- Template component references (`<UserCard>`, `<base-modal>`) appear in call graph
- Shares TypeScript parser instance for efficiency

## Framework Detection

codemap auto-detects frameworks from your config files and dependencies:

| Framework | Detection Method |
|-----------|-----------------|
| Express | `express` in package.json (without NestJS) |
| NestJS | `@nestjs/core` in package.json |
| FastAPI | `fastapi` in requirements.txt / pyproject.toml |
| Django | `django` in requirements.txt or `manage.py` exists |
| Flask | `flask` in requirements.txt / pyproject.toml |
| Prisma | `prisma/schema.prisma` exists |
| Sequelize | `sequelize` in package.json |
| Mongoose | `mongoose` in package.json |
| TypeORM | `typeorm` in package.json |
| SQLAlchemy | `sqlalchemy` in requirements.txt / pyproject.toml |

## Noise Reduction

codemap filters out noise that would bloat the output and waste tokens:

- **Built-in calls filtered**: JS/TS builtins (`map`, `filter`, `push`, `JSON.stringify`, etc.) and Python builtins (`isinstance`, `len`, `str`, `range`, etc.) are removed from call graphs
- **Test assertions filtered**: `assertEqual`, `pytest.raises`, etc.
- **Chain expressions collapsed**: `foo.bar().baz().qux()` → `foo.bar`
- **Type signatures truncated**: Verbose `Annotated[bool, Doc("200 lines...")]` → `bool` (120 char limit)
- **`self.`/`this.` stripped**: Normalized for cleaner call graphs

## Dependency Tracking

codemap extracts dependency versions from manifest files without scanning library source code:

- **Node.js**: `package.json` (dependencies, devDependencies, peerDependencies)
- **Python**: `requirements.txt`, `requirements-dev.txt`, `pyproject.toml`

## Output Structure

### JSON (`codemap.json`)

The full structured output containing:

```
project         → name, languages, frameworks, entry points
files           → per-file: language, hash, exports, imports
classes         → per-class: file, extends, implements, decorators, methods, properties
functions       → per-function: file, params, return type, calls, called_by
types           → per-type: file, kind, extends, properties
call_graph      → caller → [callees]
import_graph    → file → [imported files]
dependencies    → package versions from manifests
config_deps     → env var usage across files
```

### Markdown (`codemap.md`)

A compact, directory-level root summary designed for AI context windows. Includes module counts, class/function listings grouped by directory, dependencies, and env var usage. Typically 1500–2000 lines for large projects.

### Module files (`modules/*.md`)

Per-directory detailed files with full function signatures, call/called_by relationships, and import graphs. Used by the MCP `codemap_module` tool for on-demand deep dives.

## Auto-Update with Claude Code Hooks

Use a Claude Code `SessionStart` hook to automatically regenerate the codemap when source files have changed. This runs `codemap check` at the start of each session — if any source files are newer than `codemap.json`, it regenerates before Claude starts working.

Add this to your project's `.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "codemap check || codemap generate"
          }
        ]
      }
    ]
  }
}
```

This runs on session startup only (not on resume/compact). `codemap check` exits with code 0 if fresh, 1 if stale, 2 if missing — so `||` triggers `codemap generate` only when needed.

### Freshness Check

You can also check staleness manually:

```bash
codemap check              # shows which files changed
codemap check --quiet      # exit code only (0=fresh, 1=stale, 2=missing)
```

## Architecture

```
src/
├── cli/                  # CLI entry point and commands
│   ├── index.ts          # Commander setup
│   └── commands/         # generate, init, query, check, analyze, diff, health
├── core/                 # Core logic
│   ├── config.ts         # .codemaprc loading and defaults
│   ├── scanner.ts        # File discovery (fast-glob)
│   ├── orchestrator.ts   # Main pipeline: scan → parse → analyze → output
│   └── query-engine.ts   # Shared query logic (CLI + MCP)
├── parsers/              # Language-specific AST parsers
│   ├── parser.interface.ts
│   ├── typescript/       # ts-morph based
│   ├── python/           # web-tree-sitter WASM based
│   └── vue/              # Script extraction + TS delegation
├── analyzers/            # Structural analysis
│   ├── call-graph.ts     # Forward + reverse call graph with method resolution
│   ├── import-graph.ts   # File → imports mapping
│   ├── coupling.ts       # Module coupling metrics (afferent/efferent/instability)
│   ├── dead-code.ts      # Dead code detection from reverse call graph
│   ├── duplicates.ts     # Duplicate function detection
│   └── circular-deps.ts  # Circular dependency detection
├── frameworks/           # Auto-detection
│   └── detector.ts
├── output/               # Generators
│   ├── json-generator.ts # Full JSON output
│   └── md-generator.ts   # Compact MD + per-directory modules
├── mcp/                  # MCP server
│   ├── server.ts         # Multi-project MCP with stdio transport
│   └── formatters.ts     # Markdown formatters for MCP tool output
└── utils/
    ├── call-filter.ts    # Noise reduction (built-in filtering, type truncation)
    ├── logger.ts
    └── file-utils.ts
```

## License

MIT