Codanna Explore

Codanna Explore

Topic-driven codebase exploration via codanna's local code intelligence (semantic search + tree-sitter symbol graph + RAG over docs).

Docs: https://docs.codanna.sh/ · Repo: https://github.com/bartolli/codanna Workflow diagram & rationale: README.md

When to use

• User gives a topic: "explore the auth flow", "map the parser", "how does X work".
• Need call graph, callers, or impact analysis for a function / type.
• Need semantic ("find code that does Y") search, not just grep.

Don't use for: regex / text-pattern searches (use rg, fall back to grep), nix lookups (search-nix-manix), or trivial single-file questions.

Tool surface (prefer MCP, fall back to CLI)

Output flags: --json, --fields=<top-level-keys>, -k/--kind, -l/--limit, -m/--module. Add --watch to codanna mcp … to reindex stale files before the call.

--fields= only matches top-level JSON keys, not nested paths. For retrieve search-style results the top level is symbol, file_path, relationships — use --fields=symbol,file_path (not --fields=name,symbol_id,file_path, which silently drops everything but file_path). The symbol's ID lives at symbol.id, but the CLI/MCP input parameter is symbol_id:N (name mismatch is intentional in codanna).

Default text output is often better than --json: codanna's default formatter is compact, shows similarity scores, inlines relationships, and most tools end with a 💡 hint pointing to the next useful call (e.g. "Explore 'get_calls' to see what it calls"). Read those hints — they save round-trips. search_documents is the one exception that doesn't emit a 💡 line. Reach for --json | toon only when you need to extract symbol.ids programmatically or paginate large result sets.

Always suppress stderr when piping JSON through toon: codanna ... --json 2>/dev/null | toon. Tantivy emits lock-busy warnings on stderr that break toon's JSON parser.

Workflow

1. Status check — get_index_info and codanna documents list. Branch into bootstrap if symbol_count: 0 or no docs collections exist. Note: semantic_search.enabled: false in get_index_info is misleading — the embedding model loads on demand. Try semantic_search_* anyway; only fall back to fuzzy search_symbols if it actually errors.

2. Bootstrap if missing (skip questions the user has already answered):

   • 2a. Code — if not indexed, autodetect code dirs. Standard list: src lib app cmd internal pkg. For JS/TS / web projects also consider pages components routes app server client. If nothing standard matches, ls the repo root and ask the user which dirs to index. Then codanna init + codanna index <dirs>. User refusal = stop; exploration needs code. codanna init also drops a .codannaignore (gitignore-style file for codanna's indexer, with sensible defaults) — leave it committed.
   • 2b. Docs — if no collection, autodetect docs targets: directories docs openspec ADRs adrs; or, if only a root README.md (no docs/ directory), use codanna documents add-collection readme . --pattern "README.md". Ask y/n, then codanna documents index --all. User refusal or nothing detected = skip step 3.
   • 2c. .gitignore tip — if any bootstrap actually ran, append (don't overwrite) these to the repo's .gitignore:

     .codanna/
     .fastembed_cache
     

     .codanna/settings.toml contains absolute paths (workspace_root, indexed_paths) and machine-specific config, so the whole .codanna/ directory must stay local. .fastembed_cache is a symlink into ~/.codanna/models/ — broken on every other machine. Leave .codannaignore committed (project-shared).

3. Harvest concepts from docs (only when a docs collection exists) — search_documents query:"<topic>". Read the previews and freeform-extract concepts and likely symbol names related to the query — no fixed schema, whatever looks useful. Feed into step 4. Note: enriching the anchor query often shifts the result set toward the harvested terms rather than simply boosting recall; compare with the bare query if you suspect drift.

4. Anchor in code — semantic_search_with_context query:"<topic + harvested terms>". Returns the highest-quality entry points (file + symbol + relationships). For top hits, call graph / callers / impact are inlined in the response — step 6 may be unnecessary for those symbols. No hits → rephrase once, then fall back to a regex search with rg/grep (step 8).

5. Lock + disambiguate symbols — find_symbol (exact) or search_symbols kind:function|struct|trait|class|method|interface. For same-name collisions, grab the symbol ID from --json output (the field path is data[].symbol.id for retrieve search) and pass it as symbol_id:N downstream. You can shrink the payload with --fields=symbol,file_path (top-level keys only).

6. Map relationships — treat as hints, not truth (codanna is static):

   • get_calls <sym|symbol_id:N> — outgoing dependencies.
   • find_callers <sym|symbol_id:N> — incoming uses.
   • analyze_impact <sym|symbol_id:N> — full blast radius. Usually small (10-30 lines in practice); call it freely and narrow with find_callers only if data is actually large. Often redundant when step 4 already inlined relationships.

7. Read source — zat <file> for signatures-first skim, then Read(offset, limit) into specific bodies. Use ctx_read or Read when you need full text.

8. Always-on regex sanity pass — run rg (preferred) or grep on the topic keyword + harvested terms from step 3. Catches what static analysis misses: macros, dynamic dispatch, FFI, generated code, string-based references. Run every time, not just when you suspect gaps. If new symbols surface, loop back to step 5.

9. Report (text) — entry points as path:line, call graph summary, surprising coupling, gaps where codanna's static view looked incomplete, plus any regex findings from step 8.

10. Offer a markdown+mermaid report (only if the mermaid-diagrams skill is listed as available) — after delivering the text report, ask the user whether they want a richer artifact with diagrams. Good candidates:

    • Call/dependency graph (flowchart) from get_calls / find_callers / analyze_impact data.
    • Sequence diagram for traced execution flow through the entry points.
    • Component / module diagram when several modules are involved.
    • Class diagram for struct / trait / impl relationships. On yes → invoke the mermaid-diagrams skill and emit a markdown file with embedded fenced ```mermaid blocks. On no → done.

Companion tools (prefer if installed)

Run command -v <tool> once per session, then route accordingly.

Routing rule: codanna first (structural understanding) → rg (or grep if rg is unavailable) for any regex or text-pattern search.

Output shape

All MCP / retrieve JSON wraps results in {type, status, code, exit_code, message, hint, data, meta}. The shape of data varies by command — don't assume a single path:

• status: "not_found" → data: null; read the hint field — it tells you the next useful move (e.g. "try semantic_search_docs"). Don't retry the identical query.
• Most default-text outputs end with a 💡 line carrying the same nudge. search_documents is the exception — it has no trailing 💡.

Common pitfalls