<EXTREMELY-IMPORTANT>
`codemap` only helps when the repo is indexed and the command matches the question.
Non-negotiable rules:
- Check and before relying on results.
- If the project has no codemap setup, ask before running .
- Prefer the narrowest codemap command that answers the question.
- Prefer machine-readable output when you need to interpret structured results.
- Do not auto-edit Claude or project settings just to enable codemap.
</EXTREMELY-IMPORTANT>
codemap
Inputs
- : The search or analysis goal
Goal
Use the
CLI to answer architecture and discovery questions with better signal than plain-text search when:
- intent is semantic rather than literal
- symbol lookup matters
- dependency direction matters
- file importance or coupling matters
Step 0: Verify availability and index state
Check:
If
is missing, tell the user to install it with
npm install -g @ulpi/codemap
and stop. Do not install it automatically.
If the repo is not configured:
- explain that creates project config
- ask before running
- once configured, run
If the repo is configured but stale, re-index with
.
Success criteria: There is a working codemap index for the current repository.
Step 1: Choose the right command
Command Reference
| Command | What It Does | Key Flags |
|---|
| Hybrid vector+BM25 code search | , |
| Find functions, classes, types by name | , |
| File overview with symbols and size | |
| Outgoing imports (what this file uses) | |
codemap dependents <file>
| Incoming imports (what uses this file) | |
| PageRank importance scores | , |
| Afferent/efferent coupling and instability | , , |
| Detect circular dependencies | |
| Aggregate dependency graph statistics | |
| Index project for search | |
| Show index stats | |
| Live index updates on file change | |
| Read full source (or line range) | , |
| Start MCP server over stdio | |
Quick Routing
| What You Want | Command |
|---|
| Find code that does X | |
| Find function/class named X | |
| What does this file depend on? | |
| What depends on this file? | codemap dependents <file>
|
| Most important files | |
| Circular dependencies? | |
| Overview of a file | |
| Architecture health | |
| Project stats | |
Prefer
when you need structured output rather than prose.
Success criteria: The command matches the actual question instead of overfetching.
Step 2: Run the minimal useful codemap query
Start narrow:
- limited result count
- specific file or module when known
- one analysis dimension at a time
Then expand only if the first result set is clearly insufficient.
Rules:
- do not run every codemap command "just in case"
- do not use codemap when exact is simpler
- when file contents are needed after discovery, use on the concrete file paths returned
Success criteria: The answer uses codemap for discovery and
only for the specific files that matter.
Step 3: Report results in decision-friendly form
Summarize:
- what command was used
- why it was the right command
- the most relevant results
- any follow-up files worth opening
When there are no strong results, say that explicitly instead of inventing certainty.
Success criteria: The user can act on the result set without parsing raw codemap output.
MCP Alternative
Codemap can also run as an MCP server, giving AI agents direct tool access without Bash:
bash
claude mcp add codemap codemap serve
This exposes tools like
mcp__codemap__search_code
,
mcp__codemap__search_symbols
, etc. The CLI skill (this file) uses Bash commands. MCP gives agents native tool calls. Both work -- use whichever the agent setup prefers.
Guardrails
- Do not auto-modify settings files to add permissions.
- Do not run without the user's approval when it would create new config.
- Do not treat stale or empty indexes as authoritative.
- Do not replace simple exact-match tools with codemap when text search is clearly enough.
- Do not add ; this is a general discovery skill.
Output Contract
Report:
- codemap availability and index state
- the command chosen
- the most relevant hits or graph results
- the next file(s) to open if deeper reading is needed
- any limitations such as missing index or weak results