Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Troubleshooting
Start with:
repowise doctor # install, API keys, index drift, store health, wired agents
repowise doctor --repair # fix what it safely can
repowise status # what is indexed, and how far behind HEAD
doctor --repair reconciles drift between the database and the search stores,
re-registers a stuck Claude Code MCP entry, and refreshes the config of every
wired agent. It does not rewrite stale pages: repowise update does that.
Install
repowise: command not found after install. The install directory is not
on PATH.
- uv:
uv tool update-shell, then open a new shell.uv tool dir --binprints the directory. - pipx:
pipx ensurepath, then open a new shell. - pip: add the scripts directory under
python3 -m site --user-base(binon macOS and Linux,Scriptson Windows) toPATH.
Agent hosts start repowise by name, so restart the host after fixing PATH.
"Provider X requires the 'Y' package". Every provider SDK ships with
repowise, so this means a broken or partial install. pip install <package>
clears it at once; reinstalling repowise (uv tool install --reinstall repowise, or pip install --force-reinstall repowise) fixes the cause.
Garbled symbols or encoding errors on Windows. The CLI switches its own
output to UTF-8 and substitutes a placeholder for any glyph the console cannot
draw, so a run should never stop on an encoding error. If a wrapper script or
an older shell still fails, set PYTHONIOENCODING=utf-8 before running it
($env:PYTHONIOENCODING = "utf-8" in PowerShell).
Indexing
init was interrupted, or finished with pages missing. A provider outage
or rate limit can fail individual pages while the run completes.
repowise init --resume writes only the pages that are absent and makes no
model call for the ones you have, even if you switched provider.
Doctor reports zero pages. A keyless run writes pages too. Zero pages
means the run did not finish (run repowise init --resume) or the repo is
Index only (run repowise update --full).
Memory or time on a very large repository. Options, roughly in order of effect:
repowise init --yes --no-prose --mode fast # Index only; `repowise update --full` adds the rest later
REPOWISE_PARSE_WORKERS=2 repowise init # fewer parse processes, less memory
repowise init -x vendor/ -x 'generated/**' # exclude what you never edit
repowise init --max-file-pages 2000 # cap file pages, highest importance first
The parse pool defaults to at most eight worker processes; each one holds its own parser, so lowering the count is the most direct memory lever.
Indexing one directory of a large repository. When the path you index is a
subdirectory of a larger git repository, git rows (per-file history, per-commit
file detail) are recorded for that directory only, so the database stays
proportional to the directory rather than to the whole repository. Co-change
partners outside the directory are not recorded. Set REPOWISE_GIT_SCOPE=repo
to record the whole repository instead. An index created before this change
keeps its old rows until repowise init --force rebuilds it.
An update spends minutes after the files are already indexed. After an
update commits, repowise scans recent commits for what each did to code health.
A commit that touches more than 300 files is skipped, so a bulk import cannot
stall it; change the limit with REPOWISE_COMMIT_HEALTH_MAX_FILES (0 removes
it), or turn the scan off with REPOWISE_COMMIT_HEALTH_COMMITS=0. An update on
a --mode fast index does not run the scan.
Indexing cost more than expected. repowise init --dry-run shows the
estimate without writing a wiki, --test-run generates for the top 10 files
only, and --skip-tests --skip-infra narrows scope. Lower --concurrency if
you hit provider rate limits.
Answers
The agent does not see the repowise tools. Restart the host; most read MCP
config only at startup. Then repowise doctor --repair, then re-run
repowise agents add --target=<id> --yes for your host.
The agent answers from an old version of the code. Every MCP response
carries the indexed commit and warns when it trails HEAD. Run
repowise update. To stop it recurring, keep the post-commit hook init
installs (repowise hook install puts it back) or run repowise watch. See
Auto-Sync.
An empty result. Empty means "not found in what was analyzed", which is
not always "none exists". An empty caller list comes with a *_basis field
saying how much of that language's calls the graph resolved, and a response
whose _meta reports degraded failed to load part of the index. Read those
before concluding nothing calls a symbol or nothing is wrong.
Semantic search returns nothing, or warns embedder.mock_active. No real
embedder is configured, so search is full-text only. Set REPOWISE_EMBEDDER
(for example gemini, openai or ollama) and rebuild the vector store with
repowise reindex. reindex makes embedding calls only, no LLM calls, and
also repairs a corrupted vector store.
FAQ
Do I need an API key? No. Without one, repowise builds the graph, git
history, code health, dead code, change risk and a full wiki rendered from
structure. Every MCP tool works; get_answer and search_codebase answer
from the structural pages. A key, or a keyless provider such as ollama,
claude_cli or codex_cli, adds model-written subsystem pages, decision
mining, repowise ask and dashboard chat.
Where does the key go? In .repowise/.env, which is gitignored.
generate, update and the MCP server load it. repowise init saves the key
it ran with there unless you pass --no-save-key.
Will --yes spend money? Only if a key is available and you did not pass
--no-prose. repowise init --yes --no-prose never calls a model.
The dashboard shows no repositories. The API and the dashboard must use
the same database. Check REPOWISE_DB_URL on the API and REPOWISE_API_URL
on the dashboard. repowise serve runs both together, so this only comes up
when you run them separately.
How do I remove repowise? repowise uninstall --dry-run lists everything
it wrote; repowise uninstall asks what to remove. The index is not selected
by default because rebuilding it is the expensive part.