@ulpi/codemap

Code intelligence CLI — hybrid vector + BM25 semantic search, dependency analysis, and PageRank for any codebase.

Features

• Hybrid search — combines vector similarity with BM25 keyword scoring for accurate code search
• Symbol lookup — find functions, classes, types, and interfaces by name
• Dependency graph — trace imports and dependents across your codebase
• PageRank — identify the most important files by connectivity
• Cycle detection — find circular dependencies automatically
• Coupling metrics — measure afferent/efferent coupling and instability per file
• Real-time watching — incremental re-indexing on file changes
• MCP server — 12 tools for AI agent integration (Claude, Cursor, VS Code, Kiro, etc.)
• Per-branch indexing — separate indexes for each git branch
• Multiple providers — works with Ollama (free, local), OpenAI, or ULPI Cloud embeddings

Quick Start

npm install -g @ulpi/codemap

codemap init          # Choose provider + model
codemap index         # Index your project
codemap search "authentication middleware"

Embedding Providers

| Provider | Models | Dims | Cost | Requires | |----------|--------|------|------|----------| | Ollama | nomic-embed-text (768), mxbai-embed-large (1024), all-minilm (384) | varies | Free | Ollama running locally | | OpenAI | text-embedding-3-small (1536), text-embedding-3-large (3072) | varies | Paid | OPENAI_API_KEY | | ULPI Cloud | qwen3-embedding:4b (2048) | 2048 | Managed | ULPI_API_KEY |

codemap init walks you through provider and model selection interactively.

Command Reference

codemap init

Interactive first-time setup. Prompts for embedding provider, model, and API key.

codemap init
codemap init --provider ollama    # Skip interactive prompt
codemap init --provider openai
codemap init --provider ulpi

codemap index

Index the current project for code search. Scans files, chunks with AST awareness, generates embeddings, and builds the dependency graph.

codemap index
codemap index --full              # Force full re-index (ignore incremental state)

codemap search <query>

Search code using hybrid vector + BM25 scoring.

codemap search "database connection pool"
codemap search "error handling" --limit 20
codemap search "auth middleware" --json

| Option | Description | Default | |--------|-------------|---------| | -l, --limit <n> | Max results | 10 | | --json | Output as JSON | — |

codemap symbols <query>

Find functions, classes, and types by name.

codemap symbols "createUser"
codemap symbols "Router" --limit 5
codemap symbols "Handler" --json

| Option | Description | Default | |--------|-------------|---------| | -l, --limit <n> | Max results | 20 | | --json | Output as JSON | — |

codemap status

Show index statistics for the current project.

codemap status
codemap status --json

codemap watch

Watch for file changes and update the index in real-time.

codemap watch
codemap watch --debounce 500

| Option | Description | Default | |--------|-------------|---------| | --debounce <ms> | Debounce interval | 300 |

codemap statusline

Install a CodeMap status indicator into Claude Code's statusline. It extends your existing statusline (if any) and appends CodeMap info.

codemap statusline              # Install
codemap statusline --uninstall  # Remove and restore previous statusline

The statusline shows at a glance:

MyProject | git:main | Opus (1M context) | ctx:8%
CodeMap: ● 842 files · ◆12.4k chunks | 23m ago

With multiple codemap MCP servers registered in .mcp.json, each gets its own line:

MyProject | git:main | Opus (1M context) | ctx:8%
CodeMap: ● 842 files · ◆12.4k chunks | 23m ago
CodeMap (frontend): ○ 360 files · ◆1.9k chunks · ⚠3 stale | 2h ago

• ●/○ — codemap watch running or not
• ◆ — indexed chunks (search units)
• ⚠N stale — files modified since last index
• IDX — indexing in progress

codemap deps <file>

Show files this file depends on (outgoing imports).

codemap deps src/routes/auth.ts
codemap deps src/index.ts --json

codemap dependents <file>

Show files that depend on this file (incoming imports).

codemap dependents src/utils/db.ts
codemap dependents src/config.ts --json

codemap rank [file]

Show PageRank importance scores. Without a file argument, lists top-ranked files.

codemap rank                      # Top 20 files by importance
codemap rank --limit 50
codemap rank src/index.ts         # Single file score
codemap rank --json

| Option | Description | Default | |--------|-------------|---------| | -l, --limit <n> | Number of top files | 20 | | --json | Output as JSON | — |

codemap cycles

Detect circular dependencies in the codebase.

codemap cycles
codemap cycles --json

codemap read <file>

Read and return the full source of a file, or a specific line range.

codemap read src/routes/auth.ts
codemap read src/index.ts --from 10 --to 50
codemap read src/index.ts --json

| Option | Description | |--------|-------------| | --from <line> | Start line (1-based, inclusive) | | --to <line> | End line (1-based, inclusive) | | --json | Output as JSON (includes filePath, totalLines, from, to, content) |

codemap summary <file>

Show file overview with symbols and size.

codemap summary src/routes/auth.ts
codemap summary src/index.ts --json

codemap coupling

Analyze afferent/efferent coupling and instability.

codemap coupling
codemap coupling --module src/routes/ --limit 20
codemap coupling --json

| Option | Description | Default | |--------|-------------|---------| | --module <path> | Filter to a directory prefix | — | | -l, --limit <n> | Max results | 50 | | --json | Output as JSON | — |

codemap graph-stats

Show aggregate dependency graph statistics.

codemap graph-stats
codemap graph-stats --json

codemap rebuild-depgraph

Rebuild dependency graph from scratch using tree-sitter tag extraction.

codemap rebuild-depgraph
codemap rebuild-depgraph --json

codemap update

Check for and install the latest version of codemap.

codemap update            # Check and install latest version
codemap update --check    # Check only, don't install

The statusline will show ↑ vX.Y.Z available when a new version is detected. Update checks run automatically in the background (once per day).

codemap ignore

Generate or reset .codemapignore with default exclusion patterns.

codemap ignore
codemap ignore --force            # Overwrite existing .codemapignore

codemap config

Get, set, or list configuration values.

codemap config list
codemap config get embedding.provider
codemap config set embedding.provider openai
codemap config set embedding.apiKey sk-...

codemap serve

Start an MCP server over stdio for AI agent integration.

codemap serve

Global Options

All commands support:

| Option | Description | |--------|-------------| | --cwd <dir> | Override project directory | | --version | Show version | | --help | Show help |

MCP Integration

codemap serve starts an MCP server over stdio, exposing 12 code intelligence tools to any compatible AI agent or editor.

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}

JetBrains (IntelliJ, WebStorm, etc.)

Go to Settings > Tools > AI Assistant > MCP Servers, add:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "codemap": {
      "command": {
        "path": "codemap",
        "args": ["serve"]
      }
    }
  }
}

Multi-Project Setup

You can register multiple CodeMap MCP servers — one per codebase — so your AI agent can search across your frontend, backend, shared libraries, or any other project simultaneously. Each server indexes and serves its own project independently.

First, index each project:

codemap init && codemap index                           # current project
cd /path/to/frontend && codemap init && codemap index   # another project

Then register them as MCP servers. The current project uses codemap serve with no extra arguments. Other projects use --cwd to point to their location:

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"],
      "description": "Semantic code search (hybrid vector + BM25), symbol lookup, file reading, dependency graph analysis (PageRank, cycles, coupling). Use search_code for concept-based queries, search_symbols to find functions/types by name, read_file to view source."
    },
    "codemap-frontend": {
      "command": "codemap",
      "args": ["serve", "--cwd", "/path/to/frontend"],
      "description": "<describe your project, e.g.: React SPA with auth flows and dashboard UI> — Semantic code search (hybrid vector + BM25), symbol lookup, file reading, dependency graph analysis (PageRank, cycles, coupling). Use search_code for concept-based queries, search_symbols to find functions/types by name, read_file to view source."
    }
  }
}

"codemap" serves the current project automatically. "codemap-frontend" serves a different codebase via --cwd. The description tells your AI agent when to use each server. Add as many as you need — each gets its own set of 13 tools (search_code, read_file, get_dependencies, etc.) scoped to that project.

Other Editors

The same pattern works in any editor — add one entry with no --cwd for the local project, and additional entries with --cwd for other codebases. Use unique names (e.g. codemap-api, codemap-shared) so your AI agent can tell them apart.

Your AI agent will then have access to tools like search_code, get_dependencies, and search_symbols across all registered projects, making it easy to trace connections across your stack.

MCP Tools Reference

| Tool | Description | |------|-------------| | read_file | Read full source or a line range (supports from/to params) | | search_code | Search code using hybrid vector + BM25 | | search_symbols | Find functions, classes, and types by name | | get_file_summary | Get file overview with symbols and size | | get_index_stats | Get code search index statistics | | reindex | Trigger a full code search re-index | | get_dependencies | Get files this file imports (outgoing edges) | | get_dependents | Get files that import this file (incoming edges) | | get_file_rank | Get PageRank importance score for files | | find_cycles | Detect circular dependencies | | get_coupling_metrics | Analyze afferent/efferent coupling and instability | | get_depgraph_stats | Get aggregate dependency graph statistics | | rebuild_depgraph | Recompute PageRank and dependency metrics |

Environment Variables

| Variable | Purpose | Default | |----------|---------|---------| | CODEMAP_DATA_DIR | Override data directory | ~/.codemap | | OPENAI_API_KEY | OpenAI API key | — | | OLLAMA_HOST | Ollama server URL | http://localhost:11434 | | ULPI_API_KEY | ULPI Cloud API key | — | | CODEMAP_PROJECT_DIR | Override project directory (MCP mode) | cwd |

Configuration

Configuration is loaded in order of precedence (highest first):

1. Project config — .codemap.json in project root
2. Global config — ~/.codemap/config.json
3. Defaults

Manage with the config command:

codemap config list                          # Show all values
codemap config get embedding.provider        # Get a value
codemap config set embedding.model nomic-embed-text   # Set a value

How It Works

1. Scan — discovers source files respecting .gitignore and deny patterns
2. Chunk — splits files into AST-aware chunks (functions, classes, blocks)
3. Embed — generates vector embeddings via your chosen provider
4. Store — writes vectors to LanceDB and builds a BM25 index
5. Graph — extracts import/export edges with tree-sitter, computes PageRank
6. Search — combines vector similarity, BM25 keyword scoring, symbol boosting, and graph rank

Data is stored per-project and per-branch at ~/.codemap/{projectSlug}/{branchSlug}/.

Requirements

• Node.js 18+
• Ollama provider: running Ollama instance with model pulled (ollama pull nomic-embed-text)
• OpenAI provider: valid OPENAI_API_KEY
• ULPI Cloud provider: valid ULPI_API_KEY

License

See LICENSE.