Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
claude-code: dir: codebase-exploration frontmatter: | name: codebase-exploration description: > Use when exploring, understanding, or answering questions about a codebase that has Repowise indexed (a .repowise/ directory in the project root). Activates for "how does X work", "explain the architecture", "where is Y implemented", "what does this module do", or any task that needs an understanding of structure before diving into source files. user-invocable: false codex: dir: codebase-exploration frontmatter: | name: codebase-exploration description: Use when exploring, understanding, or answering questions about a Repowise-indexed codebase, including architecture, where code is implemented, how a module works, or which files are relevant before reading source.
Codebase Exploration with Repowise
This project has a Repowise intelligence layer. Before grepping and reading raw source to understand the codebase, reach for the Repowise MCP tools — they return documentation, ownership, history, decisions, and graph structure that plain file reads don't, usually in one round-trip instead of many.
Which tool for which question
| You want… | Call |
|---|---|
| First orientation in an unfamiliar repo | get_overview() — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. |
| A direct answer to "how/where/why does X work" | get_answer(question="…"): synthesised answer with citations + one confidence trust signal. Collapses the search → read → reason loop. |
| Find a symbol, file, or fuzzy concept | search_codebase(query="…") — hybrid search. mode="auto" routes an identifier to indexed symbol hits (symbol_id/line bounds → pipe into get_symbol), a path to file pages (→ get_context), and prose to semantic wiki search (each hit reports search_method: embedding vs bm25). Force a branch with mode=symbol|path|concept|hybrid; narrow symbols with symbol_kind. |
| A triage card for specific files/symbols | get_context(targets=[…]) — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids (a row without one is path::name). Batch many targets in one call. |
| The actual source of one symbol | get_symbol("path/to/file.py::Name") — exact bytes with line bounds. Cheaper than Read + offset math. Use a symbol_id from get_context. |
Recommended flow
- New area you don't know →
get_overview()once. - A specific question →
get_answer(question=…)first.- High confidence → answer it, cite the paths.
medium/lowconfidence → followbest_guesses[0].fileorfallback_targets[0]intoget_context, thenget_symbolfor bytes.
- A named symbol or a path →
search_codebase(query="Name")/search_codebase(query="path/to/file.py"); symbol hits pipe straight intoget_symbol, file hits intoget_context. - More files around a concept →
search_codebase, thenget_contexton the hits (batched), thenget_symbolonly for the bodies you actually need.
Fall back to your own file-reading and searching tools only when the indexed context doesn't cover the specific detail the user asked about.
Trust signals — verify when
_meta.stale_warningis present (the index has diverged from HEAD), orconfidenceismedium/low, or- a result's
search_methodisbm25.
Otherwise the response is current — act on it.
Error handling
- "No repositories found. Run 'repowise init' first." → suggest
{{cmd:init}}. Add--no-editor-setupif this repo is a scratch clone, a fixture, or a worktree:initotherwise repoints the user's single globalrepowiseMCP entry at it. - MCP tools unavailable → prefer the matching CLI slash commands when the
plugin is installed (
{{cmd:ask}},{{cmd:context}},{{cmd:symbol}},{{cmd:search}}) rather than grepping blind. get_answer/search_codebasecome back empty → the repo may have a template-rendered wiki. Fall back toget_contextwith explicit paths, and note that model-written pages (repowise generate, or{{cmd:init}}with an LLM provider) unlock richer docs + semantic search.- Tools fail to connect at all → the
repowisebinary may not be installed; suggest{{cmd:init}}.