English · 简体中文

Language-neutral code index for AI agents — precise navigation without full-project search.

CodeMap builds a deterministic, AST-based index of your codebase so AI agents (Claude Code, Cursor, Codex, etc.) can find call chains, route mappings, and cross-file relationships without grepping the entire project. Indexing is static, fast, and reproducible — no LLM in the index path.

Status: 0.3.1 stable. Installable from PyPI as codemap-core plus 17 codemap-<lang> plugins + 2 framework / output plugins (codemap-mybatis, codemap-aimemory, added in 0.3.0; 0.3.1 adds the codemap llm config CLI).

👉 In a hurry? The INSTALL.md guide is the definitive walkthrough — it covers pipx / uv tool / pip, language-plugin injection, offline distribution, troubleshooting, and a verbatim clean-machine validation log.

• Core principles
• Installation
  • 1. Main CLI
  • 2. Optional extras
  • 3. Language plugins
  • 4. Local clone (development)
  • 4b. Install from git
  • 5. System requirements
• Verify
• Commands
• Configuration
• Built-in indexers and bridges
• Architecture
• Writing a plugin
• Performance
• Documentation
• Contributing
• License

1. Static analysis first, LLM as consumer — the index is deterministic and reproducible.
2. Layered defense, confidence-graded — admit uncertainty rather than hallucinate.
3. Cross-asset bridging is the core value — non-source assets (XML, YAML, IDL) bridge to code via the same protocol as languages.
4. Evolvable path — CLI → MCP Server → Agent CLI, each step independently valuable.
5. Ecosystem-compatible — SCIP for symbols, MCP for tools.
6. Language-neutral — no language or framework is privileged; all indexers and bridges register through the same plugin protocol (see ADR-L001).

# Recommended: pipx provides environment isolation + a system-wide
# `codemap` command
pipx install codemap-core

# Plain pip (preferably into a venv)
pip install codemap-core

# Or with uv
uv tool install codemap-core

# `--watch` mode needs watchdog
pip install "codemap-core[watch]"
pipx install "codemap-core[watch]"

# Development tools (tests, lint, mypy, import-linter, benchmarks)
pip install "codemap-core[dev]"

Each non-Python language indexer ships as an independent PyPI distribution. To add a language to a pipx-installed codemap, use pipx inject so the plugin lands in the same isolated venv as the main CLI:

# All 17 languages in one shot
pipx inject codemap codemap-typescript codemap-javascript codemap-vue \
                    codemap-java codemap-jsp codemap-go \
                    codemap-rust codemap-swift codemap-kotlin \
                    codemap-ruby codemap-php codemap-sql \
                    codemap-bash codemap-c codemap-cpp \
                    codemap-csharp codemap-scala

Plain pip (when codemap-core is installed via pip, not pipx):

pip install codemap-typescript codemap-javascript codemap-vue \
            codemap-java codemap-jsp codemap-go codemap-rust \
            codemap-swift codemap-kotlin codemap-ruby codemap-php \
            codemap-sql codemap-bash codemap-c codemap-cpp \
            codemap-csharp codemap-scala

Or one at a time when you only need a single language:

pipx inject codemap codemap-typescript   # or pip install codemap-typescript

Each plugin declares codemap-core as a dependency, so pip will pull the engine if you don't already have it. After installation, codemap doctor lists every installed plugin alongside the built-in indexers on identical terms — see Writing a plugin for the design.

git clone https://github.com/qxbyte/codemap.git
cd codemap

# Editable install with all dev tooling
pip install -e ".[dev,watch]"

# Optionally install language plugins in editable mode
pip install -e plugins/codemap-typescript
pip install -e plugins/codemap-java
pip install -e plugins/codemap-go
pip install -e plugins/codemap-rust
pip install -e plugins/codemap-swift
pip install -e plugins/codemap-kotlin
pip install -e plugins/codemap-ruby
pip install -e plugins/codemap-php
pip install -e plugins/codemap-sql
pip install -e plugins/codemap-bash
pip install -e plugins/codemap-c
pip install -e plugins/codemap-cpp
pip install -e plugins/codemap-csharp
pip install -e plugins/codemap-scala

For users who want unreleased changes from main or to pin to a specific commit, the git URL form still works:

# Track main
pip install git+https://github.com/qxbyte/codemap.git
pipx install git+https://github.com/qxbyte/codemap.git

# Pin to a commit
pip install git+https://github.com/qxbyte/codemap.git@2c3ed45

# A specific language plugin from a subdirectory
pip install "git+https://github.com/qxbyte/codemap.git#subdirectory=plugins/codemap-typescript"

codemap --version      # → 0.1.0
codemap --help         # list global flags + subcommands
codemap doctor         # show registered indexers, bridges, and `.codemap/` state

A successful install with the TypeScript plugin should look like:

$ codemap doctor
CodeMap 0.1.0
project_root: /your/path

                   Registered indexers
┃ name          ┃ version ┃ languages  ┃ file_patterns ┃
┃ _example_lang │ 0.1.0   │ example    │ *.example     │
┃ python        │ 0.1.0   │ python     │ *.py, *.pyi   │
┃ typescript    │ 0.1.0   │ typescript │ *.ts, *.tsx   │
┃ java          │ 0.1.0   │ java       │ *.java        │
┃ go            │ 0.1.0   │ go         │ *.go          │
┃ rust          │ 0.1.0   │ rust       │ *.rs          │
┃ swift         │ 0.1.0   │ swift      │ *.swift       │
┃ kotlin        │ 0.1.0   │ kotlin     │ *.kt, *.kts   │
┃ ruby          │ 0.1.0   │ ruby       │ *.rb          │
┃ php           │ 0.1.0   │ php        │ *.php         │
┃ sql           │ 0.1.0   │ sql        │ *.sql, *.ddl  │
┃ bash          │ 0.1.0   │ bash       │ *.sh, *.bash, *.bats │
┃ c             │ 0.1.0   │ c          │ *.c, *.h      │
┃ cpp           │ 0.1.0   │ cpp        │ *.cpp, *.cc, *.cxx, *.hpp, *.hh, *.hxx │
┃ csharp        │ 0.1.0   │ csharp     │ *.cs, *.csx   │
┃ scala         │ 0.1.0   │ scala      │ *.scala, *.sc │

           Registered bridges
┃ name                 ┃ version ┃ requires ┃
┃ http_route           │ 0.1.0   │ -        │
┃ python_cross_module  │ 0.1.0   │ -        │

Full reference: docs/cli.md.

# Index a project (writes .codemap/)
codemap index /path/to/project
codemap index . --rebuild               # discard old index
codemap index . --incremental           # re-parse only files whose sha256 changed
codemap index . --watch                 # stay running and re-index on changes
codemap index . --dry-run               # report what would be indexed, no write

# Diagnose
codemap doctor                          # plugins + index health
codemap diagnostics --severity error    # show recorded warnings / errors
codemap config show                     # merged effective configuration

# Query
codemap search login -n 5
codemap get '<symbol-id>'
codemap callers '<symbol-id>' --depth 2
codemap callees '<symbol-id>'
codemap trace --from '<id>' --depth 5
codemap trace --from '<id>' --to '<id>' # shortest path
codemap routes                          # HTTP routes from the http_route bridge

# Knowledge recall — 0.3.5+ (codemap-aimemory plugin)
# Scans .ai-memory/knowledge/*.yml (written by specode-distill / task-swarm)
# and ranks by token overlap; returns top-K relevant knowledge.
# Designed to be called by specode at the start of the requirements phase.
codemap recall '<query>'                                 # default top-k 5, yaml output
codemap recall '<query>' -p /abs/project -k 10 -o json   # explicit project + json
codemap recall '<query>' -t rules,pitfalls               # filter categories
codemap recall --from-spec requirements.md               # 0.3.6+: use spec file as query
codemap recall '<query>' --with-content                  # 0.4.0+: include rule/pit/case core fields
# Every result carries `freshness_score`/`ranked_score`/`stale` since 0.4.0;
# fresher hits outrank stale ones at the same token score (180-day half-life + code-churn decay).
# With `codemap-semantic-index` plugin installed (P1-3, since v0.4.2), recall
# automatically does hybrid token+embedding ranking with RRF fusion.

# Semantic recall (requires opt-in `codemap-semantic-index` plugin, P1-3)
codemap embed install               # interactive picker; downloads default Qwen3-Embedding-0.6B (1.2GB)
codemap embed                       # incremental embed of knowledge-base/*.md
codemap embed --rebuild             # force full rebuild
codemap embed backend set --provider qwen --api-key sk-xxx  # switch to cloud Qwen embedding

# Machine-readable output: all commands take --json
codemap --json callers '<symbol-id>'

# Optional LLM enrichment (codemap-aimemory plugin, 0.3.0+)
codemap llm config set api-key sk-xxx       # persist to ~/.config/codemap/llm.yaml
codemap llm config set base-url https://api.deepseek.com/v1
codemap llm config set model deepseek-chat
codemap llm config show                     # masked-key view + value source
codemap enrich .                            # fills .ai-memory/enrichment/*.yml
codemap enrich . --dry-run                  # count fn/method symbols, no API call

Exit codes follow sysexits.h (ADR-005); see docs/cli.md for the table.

codemap index produces two parallel directories at the project root:

<project>/
├── .codemap/        ← deterministic, machine-friendly index (queried by `codemap …`)
└── .ai-memory/      ← four-layer-memory-model L1 layout (consumed by AI agents)

Written by codemap-aimemory (L0+L1, every codemap index) and optionally by sibling tools (specode-distill for L2/L3, task-swarm for the auto-ingested cases + pitfalls). AI agents read this tree directly. Stable entity_id slugs are derived from the SCIP SymbolID (e.g. fn-calcPrice / cls-OrderService / tbl-sf_coupon).

.ai-memory/
├── project.yml              ← L0   (codemap-aimemory 0.3.2+)
│                              tech stack / dependencies / git remote /
│                              top dirs / configs — best-effort autodetect
│
├── entities/                ← L1   (codemap-aimemory 0.3.0+)
│   ├── functions.yml          fn-/cls- entities with calls / called_by /
│   │                          related_tables / signature / line_range /
│   │                          confidence / change_count_90d /
│   │                          business_meaning
│   ├── tables.yml             tbl-* table entities
│   ├── files.yml              file-* file entries
│   └── modules.yml            mod-* per-file aggregates (0.3.3+):
│                              {id, path, language, fn_count, cls_count,
│                               functions[], classes[]}
│
├── relations/               ← L1
│   ├── call-graph.yml         `{from, to, type=calls, confidence}`
│   ├── table-relations.yml    `{from, to, type=accesses_table, confidence}`
│   └── rule-constraints.yml   empty placeholder (L2 owns the channel)
│
├── enrichment/              ← L1 OPTIONAL — LLM-generated overlays
│   └── <sha1[:12]>.yml        `{symbol_id, business_meaning,
│                                related_rules, confidence:"llm",
│                                source_model, generated_at}`
│
├── _global/                 ← L1↔L2/L3 lookup (codemap-aimemory 0.3.4+)
│   └── entities.yml           Cross-walk: every entity_id (code or
│                              knowledge) with `source` ∈
│                              {code, knowledge, both} +
│                              `knowledge_refs` (which knowledge yml
│                              mention this entity). Backs `codemap recall`.
│
├── _semantic/               ← P1-3, OPTIONAL — written by codemap-semantic-index
│   ├── chunks.json            chunked text + metadata (model-independent)
│   ├── vectors.npy            (n_chunks, 1024) float32 (model-specific)
│   ├── model_id.txt           active backend fingerprint
│   └── manifest.json          text_hash → chunk_id (drives incremental embed)
│
└── knowledge/               ← L2 + L3 (NOT written by codemap itself —
                              produced by specode-distill / task-swarm;
                              codemap-aimemory reads it to build
                              _global/entities.yml and to power recall)
    ├── rules/    rule-*.yml         L2 business rules / mechanisms
    ├── business/ biz-*.yml          L2 business processes / UI features
    ├── modules/  mod-*.yml          L2 module maps (table / call_chain)
    ├── cases/    case-*.yml         L3 historical implementation cases
    └── pitfalls/ pit-*.yml          L3 reusable failure / fix lessons

Two-hop fan-out: when a Java method maps_to a sql_mapping that accesses_table T, T automatically lands on the method's related_tables. So fn-selectByUser.related_tables = [tbl-sf_coupon] without the agent needing to follow the chain itself.

codemap-aimemory owns L0+L1; L2+L3 (knowledge/) come from sibling tools in the pluginhub family. The integration is one-way and loose — codemap doesn't import the others, just reads their yml output when present:

When codemap-semantic-index is installed, codemap recall automatically becomes hybrid (token + embedding) ranking via Reciprocal Rank Fusion (k=60), then multiplied by freshness_score. Embedding hits that token recall missed surface naturally. Without the plugin installed, recall remains token-only — no behaviour change for users who don't want embeddings.

Each specode-distill / task-swarm write also produces a twin markdown file under <project_root>/knowledge-base/<category>/<id>.md (same stem as the yml). The twin md preserves narrative / ascii flow charts / wikilink-style tables that field-level yml necessarily flattens, and is intended as the high-quality slicing source for a future embedding indexer. codemap itself doesn't read knowledge-base/ today — codemap recall operates on the yml side; the md exists to serve human reading and future P1-3 semantic search.

Use codemap recall '<query>' to query the union (code-side entity hits + token overlap against every knowledge/*.yml). This is what specode 2.1+ calls from its requirements phase to inject "已知约束 / 历史坑" context before drafting a new spec. See docs/integration.md (coming) for the full agent-side workflow.

No part of knowledge/ is required for codemap to function. On a project that has never run specode-distill or task-swarm, _global/entities.yml simply lists code entities with source: code, and codemap recall returns matched code entities with empty knowledge: [].

The core index is always LLM-free — codemap index never calls any LLM. Only the optional codemap enrich command in codemap-aimemory writes the enrichment/ overlay, and only when you invoke it. The existence of an API key is the on/off switch: without one, codemap enrich exits with a clear error and no network call is made.

Three configuration sources, first non-empty wins:

1. CLI flag — --api-key, --base-url, --model, --backend
2. Environment variable — CODEMAP_LLM_API_KEY (also ANTHROPIC_API_KEY, OPENAI_API_KEY); CODEMAP_LLM_BASE_URL (also OPENAI_BASE_URL, ANTHROPIC_BASE_URL); CODEMAP_LLM_MODEL; CODEMAP_LLM_BACKEND
3. Persistent file config — ~/.config/codemap/llm.yaml (managed by codemap llm config set/unset/show; written chmod 600)
4. Built-in defaults — backend openai, model gpt-4o-mini

Example with DeepSeek:

codemap llm config set base-url https://api.deepseek.com/v1
codemap llm config set api-key sk-xxx
codemap llm config set model deepseek-chat
codemap enrich .

Project-level configuration lives at .codemap/config.yaml (committed or git-ignored — your choice). A user-level override at ~/.config/codemap/config.yaml is layered on top of built-in defaults, and the project file is layered on top of that. CLI flags win over all three.

# .codemap/config.yaml
storage:
  backend: json          # json | sqlite (sqlite reserved for a future sprint)

index:
  ignore: []             # extra fnmatch patterns on names + project-relative paths
  max_file_bytes: 10485760
  follow_symlinks: false

indexers:
  enabled: all           # "all" or an explicit list of indexer names
  disabled: []           # subtractive

bridges:
  enabled: all
  disabled: []

Full reference: docs/configuration.md. Run codemap config show to inspect the merged result and see which file contributed each value.

New language? You never need to PR the main repository — see Writing a plugin.

cli  →  core  ←  indexers
        ↑          ↑
        └── io ────┘
        ↑
        mcp

• core — pure business logic, Pydantic data models, SymbolID (SCIP format), call-graph algorithms (walk_chain, shortest_path)
• io — persistence adapters (JSON today, SQLite reserved for scale)
• indexers — pluggable language/asset indexers, discovered via codemap.indexers entry-point group
• bridges — pluggable cross-language resolvers, discovered via codemap.bridges entry-point group
• cli — Typer command surface
• mcp — MCP server, later sprint

Strict import-linter contracts (pyproject.toml) enforce the dependency direction cli → core ← indexers, cli → core ← io on every PR.

CodeMap's indexers and bridges are plugin-first. Adding a new language is a separate PyPI package — main repo is never touched. The codemap-typescript package under plugins/ is the reference implementation:

# your-plugin/pyproject.toml
[project.entry-points."codemap.indexers"]
yourlang = "codemap_yourlang:YourLangIndexer"

That one line is the only coupling. After pip install your-plugin your indexer appears in codemap doctor on identical terms.

Step-by-step guide: docs/plugin-guide.md. Reference: plugins/codemap-typescript/.

Baseline numbers (median, M-series single core, indexing the CodeMap repo itself, 437 symbols / 1232 edges):

Re-run locally with pytest -m bench -o addopts="". PRs that regress any median by ≥ 20 % are blocked by CI (ADR-010). Full table and methodology: docs/performance.md.

See CONTRIBUTING.md. The key invariant: no language is a first-class citizen. Proposals that special-case any ecosystem will be asked to refactor into the generic plugin protocol (ADR-L001).

CI gates every PR through ruff, mypy --strict, import-linter, pytest --cov 80%, and the benchmark suite.

MIT — see LICENSE.