codemap

Local-first code intelligence that gives AI agents and people structural awareness of codebases — combining a code graph (LSP + parsers) with semantic vector search (veclite), exposed through a CLI, an MCP server, and an interactive terminal UI.

Working on the code? Read AGENTS.md first — it is the source of truth for conventions, architecture, and gotchas.

codemap answers questions that grep and a single LSP call can't: who calls this function and which tests cover it, what's the blast radius of changing this type across all my projects, find auth-like code and then show me everything that calls into it. It precomputes the structure once, then serves narrow, structured answers — so an agent spends a few tool calls instead of dozens of file reads.

Features

• Structural code graph — files, functions, types, methods, and tests as nodes; calls, imports, implements, references, overrides, and test-coverage as edges. Stored in pure-Go SQLite, queryable offline.

• Semantic search — every node's source is embedded (Ollama nomic-embed-text, 768-dim) into veclite; vector + BM25 hybrid search.

• Impact analysis — impact returns a symbol's definition sites, direct callers, the transitive blast radius (everything affected by a change), and which tests cover those paths (flagging untested code).

• Cross-project — the graph spans every registered project, not just one repo.

• Precise + broad — a pure-Go go/parser backend for Go today, plus a headless LSP client (validated against gopls) for precise, multi-language extraction. (tree-sitter for more languages is planned.)

• Incremental — hash-based reindex; an embedding-profile guard forces a rebuild when the provider/model/dimension changes instead of corrupting the vector space.

• Three surfaces, one store — a Cobra CLI (with --json for agents), a stdio MCP server, and the studio TUI for humans.

• Graph analytics — hotspots (hubs), orphans (dead-code candidates), and path (shortest call path between two symbols).

• Local-first & private — everything runs on your machine; no cloud, no uploads.

• Single binary — pure-Go, CGO_ENABLED=0, cross-compiled and shipped via Homebrew.

Related MCP server: Axon.MCP.Server

studio (TUI)

codemap studio opens an interactive, full-screen explorer of your code (Charm v2 — Bubble Tea / Lip Gloss / Bubbles). Switch tabs with 1–4 or tab; navigate with ↑/↓.

 codemap studio                        myproject · 411 nodes · 1414 edges · 35 files
  1 Graph   2 Metrics   3 Impact   4 Search
 Hubs                          │ Close
    38  Close                  │  Called by (38)
    21  Error                  │    indexFile   internal/index/indexer.go:182
    18  NewService             │    Index       internal/app/service.go:81
                               │  Calls (0)

• Graph — a call-graph explorer: the hubs (most-referenced symbols) on the left, the selected hub's callers and callees on the right.

• Metrics — node/edge/file counts and bar charts by kind and language, plus top hubs.

• Impact — type a symbol, see its callers, blast radius, and which tests cover it.

• Search — semantic search by meaning (ranked results).

Installation

Homebrew (recommended)

brew install abdul-hamid-achik/tap/codemap

Prerequisites

• Go 1.25+ (only to build from source)

• Ollama with the embedding model: ollama pull nomic-embed-text

• LSP servers for the languages you index (gopls, typescript-language-server, …)

• Optional: Task for the dev workflow

From source

git clone https://github.com/abdul-hamid-achik/codemap
cd codemap
task build        # → ./bin/codemap   (or: go build ./cmd/codemap)

Go install

go install github.com/abdul-hamid-achik/codemap/cmd/codemap@latest

Quick start

# 1. Register and index a project
codemap init                       # registers the current directory
codemap index                      # extract graph + embed nodes (incremental)
codemap index --no-embed           # structure only (no Ollama needed)

# 2. Navigate the call graph
codemap callers authenticateUser   # who calls it
codemap callees authenticateUser   # what it calls
codemap path     Handler Login     # shortest call path between two symbols

# 3. Analyze impact and structure
codemap impact   authenticateUser --depth 3   # callers + blast radius + tests
codemap hotspots --top 20          # most-referenced symbols (hubs)
codemap orphans                    # functions with no callers (dead-code candidates)

# 4. Search by meaning (needs an embedded index)
codemap semantic "jwt validation middleware" --top 10

# 5. Explore visually
codemap studio

Add --json to any query command for machine-readable output (for agents/scripts).

Commands

All query commands accept --json.

Use it from an agent (MCP)

codemap is a stdio MCP server. Register it with any MCP client:

Claude Code

claude mcp add codemap -- codemap serve

Generic MCP config

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

Tools (10): codemap_init, codemap_index, codemap_status, codemap_semantic, codemap_callers, codemap_callees, codemap_impact, codemap_hotspots, codemap_orphans, codemap_path. Each takes an optional path (the project directory) and returns JSON.

The flagship is codemap_impact — one call returns a symbol's definition sites, callers, the transitive blast radius, and which tests cover those paths, replacing many file reads.

Configuration

XDG-style, with CODEMAP_* environment overrides and an ecosystem fallback:

$XDG_CONFIG_HOME/codemap/config.yaml     # config        (~/.config/codemap/…)
$XDG_DATA_HOME/codemap/                   # graph DB, veclite, project registry
$XDG_CACHE_HOME/codemap/                  # caches

If ~/.codemap/ already exists it is used (back-compat with vecgrep/noted). Use codemap init --local to keep repo-local state. Precedence and all keys are documented in AGENTS.md. Override paths with CODEMAP_CONFIG / CODEMAP_DATA.

How it fits the ecosystem

codemap is built on veclite and shares conventions with vecgrep (semantic code search) and noted (code notes). An agent can combine them: vecgrep/codemap to find code by meaning, codemap to learn what calls it and what breaks if it changes.

Documentation

Full docs: docs/ (VitePress). Design rationale: SPEC.md.

License

MIT © 2026 Abdul Hamid Achik