How repowise fits into a normal working week: what to run, when to run it, and what to do when something looks wrong.
This guide is deliberately not a flag reference. When you need the exact options for a command, CLI Reference has every one of them, and it is the file that stays in sync with the code.
| If you want | Go to |
|---|---|
| To get running in five minutes | Quickstart |
| To fix something that is not working | Troubleshooting |
| Every command and flag | CLI Reference |
| Every config key and env var | Config |
| What each MCP tool answers | MCP Tools |
| The web dashboard, view by view | Dashboard |
| What a metric actually means | Glossary |
- Installation
- The mental model
- What gets created
- The commands you will actually use
- Working with your agent
- Keeping the index fresh
- Spending fewer tokens
- The dashboard
- Common workflows
- Troubleshooting
Install with uv tool install repowise, pipx install repowise or
pip install repowise (Python 3.11+ and Git). Every LLM provider SDK ships in
the base package. Step by step, including letting your agent do it:
Quickstart.
Two optional extras exist, and neither is about providers:
pip install "repowise[postgres]" # PostgreSQL + pgvector instead of SQLite
pip install "repowise[graph-extra]" # optional graph algorithms via graspologicFor local development against a clone:
git clone https://github.com/repowise-dev/repowise.git
cd repowise
uv sync --all-packages
uv run repowise --versionThree things happen, and only the first one is slow:
- Index.
repowise initparses every file to an AST, builds the dependency graph, reads git history, scores code health and renders the wiki. With a provider, a model also writes the subsystem pages. This is the one slow step. - Ask. Everything after that is a read against the index: your agent through MCP tools, you through the CLI or the dashboard. Nothing re-analyzes anything.
- Keep fresh.
repowise updatecatches the index up incrementally, in seconds. Automate it once and forget it.
The failure mode to avoid is a stale index, because a confidently wrong answer is
worse than no answer. Every MCP response carries the indexed commit and warns when
it has diverged from your live HEAD, but the real fix is step 3.
Two modes, one upgrade path. --no-prose gives you the graph, git
intelligence, code health, change risk and dead code, plus a complete wiki
rendered from the code's structure, with no LLM, no key and no network. Adding a
provider rewrites the subsystem pages as model-written prose and unlocks
decision mining and chat. Start keyless and upgrade later with
repowise generate, which reuses the stored graph; see
Writing the docs with a model. Semantic
search is separate: it needs an embedder, and repowise reindex builds the
vector store.
your-repo/
├── .repowise/
│ ├── wiki.db # pages, symbols, graph, git data, health scores
│ ├── state.json # sync metadata (last commit, pages, tokens used)
│ ├── config.yaml # provider, model, embedder, excludes
│ ├── .env # saved API keys (gitignored)
│ └── ... # search indexes and caches
├── .mcp.json # MCP server entry for Claude Code and other clients
├── .claude/CLAUDE.md # generated Claude Code context
├── .vscode/mcp.json # VS Code MCP entry
├── AGENTS.md # generated agent context, with --codex or --agents
└── .codex/ # project-local Codex MCP and hooks config, with --codex
Outside the tree, init also registers the MCP server with Claude Code
(~/.claude.json) and Claude Desktop, adds the Claude Code
PostToolUse and SessionStart hooks, and installs a git post-commit hook that
runs repowise update.
--no-editor-setup (or REPOWISE_SKIP_EDITOR_SETUP=1) skips all of it, the
project-local files and the machine-wide registration alike: only .repowise/
is written, and repowise mcp . prints the config to connect a client by hand.
--no-hook skips only the post-commit hook.
.repowise/ is safe to delete and rebuild, and safe to gitignore. Committing it
is a reasonable choice for a team that wants everyone on the same index without
each person paying to generate it.
Grouped by what you are trying to do. Every flag for every command lives in the CLI Reference.
Index and keep it current
| Command | What it is for |
|---|---|
repowise init |
First index, and the one command to start with. Bare init scans the repo and asks how to index it: everything, no prose, or advanced (every indexing and generation knob). Nothing is spent before an estimate is shown and confirmed. --yes --no-prose skips the questions and stays keyless, for scripts and agents. |
repowise generate |
Write wiki pages with a model, on demand. The upgrade path for a keyless repo: --unwritten (default) writes everything still on a template, --path/--page writes a subset, all behind a cost estimate. |
repowise update |
Incremental catch-up after pulling or committing. Seconds, not minutes. |
repowise watch |
File watcher that updates continuously while you work. |
repowise hook install |
Restore the post-commit hook init installs, if you removed or skipped it. |
repowise status |
What is indexed, and how far behind it is. |
repowise doctor |
Checks install, keys, index drift, store health. --repair fixes what it safely can. |
Ask questions
| Command | What it is for |
|---|---|
repowise search "<q>" |
Search the wiki. --mode fulltext|semantic|symbol. |
repowise ask "<q>" |
A synthesized answer with citations and a confidence rating. Costs an LLM call. |
repowise context <files> |
Triage card per file: layer, hotspot, bug-fix history, doc freshness. |
repowise symbol "<file>::<Name>" |
One symbol's body with live-verified line bounds. |
repowise why "<q>" |
Decisions and rationale behind the shape of the code. A path gets its origin story; no argument gets the decision health dashboard. |
repowise health |
Lowest-scoring files and why. --trend for direction, --refactoring-targets for concrete plans. |
repowise risk main..HEAD |
Repo-relative size-and-spread percentile, the touched files' bug-fix record, and a supporting 0-10 diff-shape score. |
repowise dead-code |
What nothing references any more, by confidence tier. |
repowise doc-drift |
Documentation whose claims about the tree no longer hold, by confidence. |
repowise decision list |
Architectural decisions, their evidence and status. |
repowise impacted-tests |
Only the tests a diff actually exercises. |
Serve and connect
| Command | What it is for |
|---|---|
repowise serve |
API, web dashboard and MCP server together. --no-ui for the API alone. |
repowise mcp |
MCP server on stdio, for editors and agents. |
Spend fewer tokens
| Command | What it is for |
|---|---|
repowise distill <cmd> |
Run a command, compress its output before the agent reads it. |
repowise expand <ref> |
Recover anything distill omitted. |
repowise saved |
Tokens and dollars saved so far. |
More than one repo
| Command | What it is for |
|---|---|
repowise workspace list |
Repos in the workspace and their status. |
repowise workspace add <path> |
Add a repo. |
repowise update --workspace |
Update every stale repo in one pass. |
Occasional maintenance
| Command | What it is for |
|---|---|
repowise reindex |
Rebuild the vector store from existing pages (embedding calls only, no LLM). |
repowise restyle |
Re-render the wiki in a different style. |
repowise export |
Export the wiki, for static hosting or archival. |
repowise costs |
What indexing has cost you, by provider and operation. |
repowise generate-claude-md |
Regenerate CLAUDE.md / AGENTS.md on demand. |
repowise telemetry disable |
Turn off anonymous usage telemetry. |
repowise uninstall |
Remove what repowise wrote from this repo, and optionally this machine. It lists everything first, and says what it left and why. |
This is the main event, and it has its own docs. The short version:
Connect once. repowise init wires Claude Code (MCP server and hooks) and
VS Code itself. Codex needs --codex on init; Cursor, OpenCode and Hermes
need repowise agents add --target=<id>. The Claude Code plugin is optional
and adds slash commands and skills. The per-host table is in
Quickstart; Codex,
OpenCode and Hermes have their
own guides.
Ten tools, task-shaped. Your agent gets architecture summaries, per-file triage cards with callers and ownership, symbol source with exact bounds, risk assessment for a set of changed files, decision lookups and health scores, each in one call, not a chain of greps. What each one answers, and worked multi-tool examples: MCP Tools.
Context that arrives unasked. Hooks push the relevant thing into the session at the right moment: a briefing at session start, the governing decision when your agent edits a file that decision covers, a warning on files with a run of recent bug fixes. They never call an LLM or the network, and they fail silently. Inventory and exact settings: Hooks.
Agents that do not speak MCP still benefit, because init generates
CLAUDE.md and AGENTS.md from the real index.
init installs the post-commit hook by default, so most repos need nothing
more. The options, in rough order of how little thought they need. Full guide:
Auto-Sync.
| Method | Command | Best for |
|---|---|---|
| Post-commit hook | installed by init; repowise hook install restores it |
Set-and-forget local dev |
| File watcher | repowise watch |
Active development sessions |
| GitHub webhook | Server endpoint | Teams, CI/CD |
| GitLab webhook | Server endpoint | Teams, CI/CD |
| Polling fallback | Automatic with repowise serve |
Safety net |
Both the hook and the watcher take --workspace to cover every repo at once.
Working in a git worktree? A new worktree seeds its index from your main
checkout on the first init or update, so there is no second full index and
nothing to configure. See Worktrees.
Most of an agent's context goes to command output it never needed: 300 lines of
passing tests around 4 failures, a full git log for "what changed recently".
repowise distill pytest -x # errors first, exit code preserved
repowise distill git log -50 # subjects and counts instead of full bodiesNothing is lost. Omissions leave a [repowise#<ref>: N lines omitted] marker;
repowise expand <ref> returns the full output, and -q <regex> filters it.
Getting your agent to use it. repowise init adds a section to the managed
CLAUDE.md so the agent reaches for it voluntarily, which works in any agent that
runs shell commands. For Claude Code you can also opt into the command-rewrite
hook, which rewrites noisy commands automatically:
repowise hook rewrite install # or answer Yes at the init promptIt never rewrites compound commands, redirections or watch modes.
Track it with repowise saved, or the Costs page in the dashboard. Full guide:
Distill.
repowise serveAPI on http://localhost:7337, dashboard on http://localhost:3000. Node.js
20+, --no-ui and the Docker image are covered in
Quickstart.
Ctrl+K / Cmd+K opens a command palette from any page, which is the fastest way
to move between views and repos.
An index-only repo has a full Docs section rendered from structure; repowise generate rewrites any of it as model prose later. Chat needs a provider.
Everything else works off the parsed graph and git history alone.
Every view and what it answers: Dashboard.
First-time setup is in the Quickstart. When you want the
subsystem pages written as prose, all at once or a piece at a time, each run
behind a cost estimate, put the key in .repowise/.env and run:
repowise generate # the unwritten subsystem pages, behind one estimate
repowise generate --path src/api # or one area first
repowise generate --stale # refresh pages the last update marked stale
repowise generate --all # or rewrite every pagerepowise update --full does the whole wiki in one pass instead. Add semantic
search with repowise reindex once an embedder is configured.
cd /path/to/workspace/ # parent dir containing backend/, frontend/, ...
repowise init . # finds the repos, asks which to indexThe post-commit hook choice applies to every selected repo.
Cross-repo contracts and co-change come out of this automatically. See Workspaces.
The post-commit hook init installed keeps the index current on every commit.
For changes you pull, or if you skipped the hook:
git pull && repowise update # catch up by hand
repowise watch # or sync continuously while you coderepowise risk main..HEAD # size-and-spread percentile and bug-fix record
repowise impacted-tests main..HEAD # the tests your changes exercise
repowise health --trend # did anything you touched get worseget_risk in PR mode also shows structural dependency reach (review candidates,
not proven runtime breakage), companion files that historically move with the
ones you touched, and where test evidence is missing.
repowise risk origin/main..their-branch
repowise health --file path/to/the/scariest/file.pyTo run the same checks on every pull request, with gates, annotations and SARIF, use the GitHub Action: see CI.
Index with a provider so they get the wiki, then hand them either the dashboard or their editor:
repowise init --provider anthropic
repowise serve # browsable wiki, graph, healthWith the MCP server connected, their agent can answer "why is this like this" instead of them interrupting someone.
export REPOWISE_SKIP_EDITOR_SETUP=1 # no hooks or editor files on the runner
repowise init --yes --no-prose # free, no keys in CI, no questions
repowise risk "$BASE_SHA..$HEAD_SHA" # gate or annotate on change size
repowise export --format markdown --output ./docs/wiki/ # static hostingTo gate a pull request on the coverage of the lines it changed, run the tests with a coverage report and add:
repowise coverage check "origin/$BASE_BRANCH...HEAD" --report coverage/lcov.info --fail-under 80It needs no index and no key, only git and the report. A shallow clone needs
full history for the merge-base. Exit 1 means below the gate, 2 means it could not
run. See Patch coverage in CI.
repowise init --provider openai --model gpt-5.6-luna --force # regenerate
repowise update --provider gemini # just future updatesOr edit provider / model in .repowise/config.yaml. The parse, graph, git and
health layers are provider-independent, so switching only affects generated prose.
repowise init --dry-run shows the estimate before anything is spent; more
levers, including memory on very large repositories, are in
Troubleshooting.
Start with repowise doctor, and repowise doctor --repair to fix what it
safely can. Install problems, interrupted runs, very large repositories,
empty results and semantic search are covered in
Troubleshooting.
- MCP Tools for what your agent can actually ask
- Code Health for what the score measures and how it is validated
- Workspaces for multi-repo intelligence
- Config for every setting and environment variable
- CLI Reference for every command and flag
- Architecture for how repowise is built