codemap AGENTS.md

AGENTS.md

Instructions for AI agents (and humans) working on the codemap codebase. This is the canonical source-of-truth doc; CLAUDE.md defers to it. README.md is the public-facing intro; product usage lives in docs/, including docs/configuration.md and the public agent guide at docs/agents.md. The design rationale (architecture, why-it-is-what-it-is) lives in the Obsidian vault at ~/notes/projects/codemap/design-rationale.md. Live work is tracked in the vault's BACKLOG.md (~/notes/projects/codemap/BACKLOG.md) — not in the repo.

Project Overview

codemap is local-first code intelligence: it combines a structural code graph (LSP + stdlib parsers; tree-sitter remains planned and is not shipped) with semantic retrieval (local veclite plus an optional one-hop vecgrep fallback, or vecgrep as the explicit owner) and exposes both as a unified query layer for agents and people. It answers questions a grep or a single LSP call cannot — "who calls this and what tests cover it", "what's the blast radius of changing this type across all my projects", "find auth-like code, then show me what calls it."

Two surfaces over one structural store (semantic retrieval may be delegated to vecgrep):

• CLI — human commands and --json machine output for agents (Cobra).
• MCP server — codemap serve (stdio), codemap_* tools for agents.

Product docs for humans start at docs/quick-start.md; agent workflows at docs/agents.md and docs/mcp.md. The former Studio TUI is not shipped — use CLI + MCP instead (see docs/studio.md).

Key features:

• Structural graph — nodes (files, functions, types, methods, tests) + calls/defines edges in pure-Go SQLite (Go, Ruby, and Lua call edges are name-based by default, Go exact via go/types with --precise; base TS/JS gets name-based JSX component-usage call edges, import edges, and Next.js framework-wiring references via tsscan, while plain TS/JS/Python function-call edges come only from --precise via callHierarchy; Vue SFC script blocks currently produce symbols + defines + import edges but no call graph; Go callback/handler uses and TS/JS framework wiring are persisted as references; Go imports are package-scoped evidence, TS/JS/Vue/Ruby/Lua imports resolve file→file; implements/overrides remain reserved for planned backends).
• Local semantic search — under the local/fallback backend with embeddings enabled, node source text is embedded through the configured Ollama-compatible endpoint (http://localhost:11434 and nomic-embed-text, 768-dim, by default) into veclite; vector + BM25 hybrid (RRF) search. A remote endpoint is explicit opt-in and receives the source text sent for embedding.
• Hybrid queries — codemap_context (one-call source + wiring + impact), codemap_impact (blast radius + test coverage), codemap_review (diff → impact + tests), and confidence-aware file dependency analysis.
• Cross-project — the graph spans all registered projects.
• Incremental — hash-based reindex; embedding-profile guard forces rebuild on provider/model/dimensions/distance change.
• Offline structural queries — the stored graph remains queryable without LSP servers running; one-off precise callers/callees may launch the appropriate server, and semantic retrieval depends on whichever local or delegated backend is configured.