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 one question, in step 5, and nothing else unless a step fails and tells you to.

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.

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 (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 renders the documentation from the code's structure, with no model and no spend, even when an API key is set in the environment. Always index this way first.
• --yes never prompts. It also installs a post-commit hook that runs repowise update after each commit (repowise hook uninstall removes it).
• 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.

Indexing a large repository takes a few minutes. Let it finish.

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 the one question#

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. Suggested wording:

Repowise is indexed and connected. One choice before I finish:

1. No LLM (free). The documentation is built from the index. Nothing leaves
   this machine.
2. An LLM writes the documentation, explaining why the code is shaped the way
   it is. It uses your provider account or subscription, and I will show you
   the cost estimate before anything is spent.

If 2, which provider?

If a key is already set, name it in the question, for example: "I see ANTHROPIC_API_KEY is set. Should I use Anthropic?" Still wait for the answer. Do not spend because a key happens to be present.

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

Supported providers:

6. If the user chose an LLM#

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=.... Repowise loads this file for generate, update and the MCP server. 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.

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 the index | written by <provider>>
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
- For a team, Repowise Hosted at https://repowise.dev indexes on every push with nothing to install.

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.

Anything else#

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