Agent setup runbook

You are a coding agent setting up Repowise for the user in the current repository. Follow the steps in order. Ask the user once, in step 5, and nothing else unless a step fails and tells you to.

Every Repowise docs page is also Markdown: append .md to its URL. The full index of pages is docs.repowise.dev/llms.txt, and Next steps below links the pages for everything after setup: workspaces, CI, hosted, upgrading and removal.

What Repowise is#

Repowise indexes a repository once and keeps the index current on every commit. The index holds the dependency graph, git history signals (hotspots, ownership, co-change), architectural decisions, code health scores, dead code, and documentation for every module. It runs on this machine. Without an LLM configured, no code leaves it and nothing is billed.

Once it is set up you query the index through MCP tools instead of grepping: get_overview (architecture map), get_answer (cited answers to code questions), get_context (docs, symbols and ownership for files and symbols), get_symbol, search_codebase, get_risk and get_change_risk (what a change may break), get_why (the decisions behind the code), get_dead_code, and get_health.

The graph, git history, health, change risk, tests and dead code never call a model. Two optional additions make the rest much stronger:

Rules#

• Never ask the user to paste an API key into this conversation. Never print, echo or log a key's value. Refer to a key by its environment variable name only.
• Never spend money on an LLM until the user has approved a cost estimate.
• Run every command from the repository root.

1. Check the prerequisites#

git rev-parse --show-toplevel   # must succeed: Repowise indexes a git repository
repowise --version              # prints a version if Repowise is installed

• git rev-parse fails: stop and tell the user Repowise needs a git repository.
• repowise --version prints a version: skip to step 3.

Repowise needs Python 3.11 or newer. uv provides a suitable Python by itself. For pipx or pip, check python3 --version (python --version on Windows).

2. Install#

Use the first installer that is available:

uv tool install repowise          # if uv is on PATH
pipx install repowise             # else, if pipx is on PATH
python3 -m pip install repowise   # else (on Windows: python -m pip install repowise)

Confirm with repowise --version. If the shell says command not found, see Command not found.

3. Check for an existing index#

If a .repowise/ directory exists at the repository root, the repository is already indexed:

repowise status

Do not re-index. In step 4, skip repowise init and run repowise agents add --target=<id> --yes for your host, where <id> is one of claude-code, codex, cursor, vscode, opencode, hermes, copilot, kiro (any other client: repowise agents print-config claude-code). Then continue with step 5.

4. Index and connect your host#

You know which host you are running in. Run its commands:

What these do:

• --no-prose builds every layer and the documentation from code, with no model calls and no spend, even when an API key is set in the environment. Always index this way first.
• --yes skips the plan screen and never prompts. It installs a post-commit hook that runs repowise update after each commit (repowise hook uninstall removes it), and points the global repowise MCP entry at this repo, printing the old and new target.
• The exit code tells you the outcome: 0 ready, 2 finished with gaps (the last line names the command that fills them), 130 interrupted (run repowise init --resume). Anything else is a failure: run repowise doctor. To parse progress, add --progress json: one JSON event per line on stdout, ending on a summary line with the status, mode, spend and next commands.
• init registers the MCP server: .mcp.json and .claude/CLAUDE.md for Claude Code, .vscode/mcp.json for VS Code, and the Claude Code entry and hooks in ~/.claude/settings.json. --codex adds .codex/config.toml, .codex/hooks.json and a managed AGENTS.md. repowise agents add writes the host's own config file.

Run init in the background. A small repository takes under a minute; a few thousand files can take several minutes, longer than many tool timeouts, so wait for the process to exit rather than relying on a fixed timeout. While a first run is going, repowise status reports the index as incomplete. In CI, a sandbox, or a repository the user only wants to try, add --no-editor-setup so only .repowise/ is written.

On Claude Code the user can also install the plugin, which adds slash commands and skills. You cannot run slash commands yourself, so mention it and move on:

/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowise

5. Ask about an LLM and semantic search#

First, list which API key variables are already set. Print names only, never values:

env | cut -d= -f1 | grep -E '_API_KEY$'
grep -oE '^(export )?[A-Z_]+_API_KEY' .repowise/.env 2>/dev/null

Get-ChildItem Env: | Where-Object Name -like '*_API_KEY' | Select-Object -ExpandProperty Name

Then ask the user. Recommend an LLM, and offer the provider that costs them nothing extra first: in Claude Code that is claude_cli, in Codex it is codex_cli, in GitHub Copilot CLI it is copilot_cli, since you are already logged in. Suggested wording:

Repowise is indexed and connected, and every tool works now. Two choices
before I finish:

1. An LLM (recommended). get_answer writes cited answers instead of returning
   search hits, the docs explain why each module is shaped the way it is, and
   decisions are mined from the history. I can use your <Claude | Codex>
   subscription, so there is no API bill, or an API key. I will show you the
   estimate before anything runs.
   Or no LLM: free, and nothing leaves this machine.

2. Semantic search (recommended). Search and get_answer match by meaning, not
   only by words. It needs a Gemini, OpenAI, OpenRouter or Eden AI key (embedding
   calls are cheap), or Ollama running locally. Or keyword search only.

If a key is already set, name it, for example: "I see GEMINI_API_KEY is set; it covers both choices." Still wait for the answer. Do not spend because a key happens to be present.

If the user picks no LLM and keyword search, go to step 7.

Supported providers:

6. Apply the choices#

Do the parts the user said yes to, in this order.

Get the key in place#

Skip this for a provider whose key variable is "None" in the table, and when the variable is already set.

Make sure the per-repo key file is ignored by git before anyone writes to it:

git check-ignore -q .repowise/.env || printf '\n# repowise API keys (local)\n.repowise/.env\n' >> .gitignore

git check-ignore -q .repowise/.env; if ($LASTEXITCODE -ne 0) { Add-Content .gitignore "`n# repowise API keys (local)`n.repowise/.env" }

Then tell the user which variable to set and how, and wait until they say it is done:

• This repository, persistent (recommended): open .repowise/.env in an editor and add a line such as ANTHROPIC_API_KEY=.... Any provider's or embedder's key variable works here. init, update, generate, reindex, serve and the MCP server load this file at startup, and a variable already set in the shell wins over the file. It is the same file repowise init saves a key to (--save-key, on by default).
• Their shell: set the variable in the terminal that launches you, then restart you from that terminal. A running agent does not see variables set in another shell.

Confirm the key is visible without printing it:

grep -qE '^(export )?ANTHROPIC_API_KEY=' .repowise/.env && echo "set in .repowise/.env"
[ -n "$ANTHROPIC_API_KEY" ] && echo "set in this shell"

Show the cost, then generate#

repowise generate --provider anthropic --dry-run

Replace anthropic with the chosen provider id. Show the user the estimate and wait for an explicit yes. Subscription and local providers still get this step. Then:

repowise generate --provider anthropic --yes

--yes is required when no terminal is attached, which is the case for you.

Pin the provider for answers and updates#

get_answer, the MCP server and the post-commit repowise update read the provider from .repowise/config.yaml. Set it there, keeping every other key in the file:

# .repowise/config.yaml
provider: claude_cli   # the provider id you generated with

Without this, a subscription or local provider is not picked up, and get_answer keeps answering in degraded mode.

Turn on semantic search#

Pick the embedder from the key the user has, then re-embed the existing pages. This makes embedding calls only, no LLM calls:

repowise reindex --embedder gemini

reindex records the embedder in .repowise/config.yaml, so later updates and the MCP server keep using it.

7. Verify#

1. Most hosts load MCP servers only at startup. Ask the user to restart the session or reload the window. Claude Code may ask once to approve the project's repowise server, and /mcp shows its status. Cursor may ask to enable the server.
2. Call get_overview. A response with an architecture summary means the setup works.
3. If the tool is not available, or the call fails, run repowise doctor and follow Troubleshooting.

8. Report back#

Tell the user what you found, in this shape:

Repowise is set up in <repository>.

What this codebase is: <two or three sentences from get_overview>
Architecture: <the main modules or layers, from get_overview>
Hotspots: <the top three files and why, from get_overview>
Worth acting on: <up to three health findings from get_health, with file and finding>
Documentation: <Built from code | Written by <model>>
Answers: <written by <provider> | ranked evidence only (no LLM)>
Search: <semantic, <embedder> | keywords only>
Files added or changed: <from git status>

Optional next steps:
- Auto-sync is already on through a post-commit hook (repowise hook uninstall removes it).
- Health and change-risk gates in CI: https://docs.repowise.dev/ci.md
- For a team, Repowise Hosted at https://repowise.dev indexes on every push with nothing to install.

Next steps#

When the user asks for more after setup, read the matching page. Each link is the page's Markdown.

Troubleshooting#

Command not found after install#

The install location is not on PATH:

• uv: run uv tool update-shell, then open a new shell. uv tool dir --bin prints the directory.
• pipx: run pipx ensurepath, then open a new shell.
• pip: add the scripts directory under python3 -m site --user-base (bin on macOS and Linux, Scripts on Windows) to PATH.

The MCP host starts repowise by name from .mcp.json, so the host needs the same PATH. Restart it after fixing PATH.

MCP tools do not appear#

1. Restart the host. Most read their MCP config only at startup.
2. Run repowise doctor. It checks the Claude Code MCP entry and whether the MCP server responds.
3. Run repowise doctor --repair. It re-registers a stuck Claude Code MCP entry and refreshes the config of every wired agent.
4. Re-run the wiring for your host: repowise agents add --target=<id> --yes, where <id> is one of claude-code, codex, cursor, vscode, opencode, hermes, copilot, kiro.

Anything else#

Run repowise doctor and read Troubleshooting. Report the failing check to the user with the command output.