Non-negotiable rules:

1. Check codemap --version and codemap status before relying on results.
2. If the project has no codemap setup, ask before running codemap init.
3. Prefer the narrowest codemap command that answers the question.
4. Prefer machine-readable output when you need to interpret structured results.
5. Do not auto-edit Claude or project settings just to enable codemap. </EXTREMELY-IMPORTANT>

codemap

Inputs

• $request: The search or analysis goal

Goal

Use the codemap 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:

• codemap --version
• codemap status

If codemap 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 codemap init creates project config
• ask before running codemap init
• once configured, run codemap index

If the repo is configured but stale, re-index with codemap index.

Success criteria: There is a working codemap index for the current repository.

Step 1: Choose the right command

Command Reference

Quick Routing

Prefer --json 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 grep is simpler
• when file contents are needed after discovery, use Read on the concrete file paths returned

Success criteria: The answer uses codemap for discovery and Read 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:

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 codemap init 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 disable-model-invocation; this is a general discovery skill.

Output Contract

Report:

1. codemap availability and index state
2. the command chosen
3. the most relevant hits or graph results
4. the next file(s) to open if deeper reading is needed
5. any limitations such as missing index or weak results