# Agent setup runbook The step-by-step runbook a coding agent follows to install repowise, index the current repository, connect the MCP tools and report back, readable by anyone. 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. ## 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: | Addition | What it changes | Without it | |---|---|---| | An LLM provider | `get_answer` writes a cited answer; the docs explain why each module is shaped the way it is; decisions are mined from comments and history | `get_answer` returns ranked evidence marked `degraded`; docs are rendered from the code's structure | | An embedder | `get_answer` and `search_codebase` match by meaning, not only by words | Search matches keywords only | ## 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 ```bash 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: ```bash 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](https://docs.repowise.dev/getting-started/setup#command-not-found-after-install). ## 3. Check for an existing index If a `.repowise/` directory exists at the repository root, the repository is already indexed: ```bash repowise status ``` Do not re-index. In step 4, skip `repowise init` and run `repowise agents add --target= --yes` for your host, where `` 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: | Host | Commands | |---|---| | Claude Code | `repowise init --yes --no-prose` | | Codex | `repowise init --yes --no-prose --codex` | | Cursor | `repowise init --yes --no-prose`, then `repowise agents add --target=cursor --yes` | | VS Code (Copilot) | `repowise init --yes --no-prose` | | OpenCode | `repowise init --yes --no-prose`, then `repowise agents add --target=opencode --yes` | | Hermes | `repowise init --yes --no-prose`, then `repowise agents add --target=hermes --yes` | | GitHub Copilot CLI | `repowise init --yes --no-prose`, then `repowise agents add --target=copilot --yes` | | Any other MCP client | `repowise init --yes --no-prose`, then `repowise agents print-config claude-code` and add the printed server entry to the client's MCP config | 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: ```text /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: ```bash env | cut -d= -f1 | grep -E '_API_KEY$' grep -oE '^(export )?[A-Z_]+_API_KEY' .repowise/.env 2>/dev/null ``` ```powershell 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: ```text 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 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 or OpenRouter 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: | Provider | `--provider` | Key variable | |---|---|---| | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | | OpenAI, or an OpenAI-compatible endpoint | `openai` | `OPENAI_API_KEY`, plus `OPENAI_BASE_URL` or `openai: {base_url: ...}` in `.repowise/config.yaml` for a compatible endpoint. A server on this machine (LM Studio, vLLM) needs no key | | Google Gemini | `gemini` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | | Kimi | `kimi` | `KIMI_API_KEY` | | Eden AI | `edenai` | `EDENAI_API_KEY` | | LiteLLM proxy | `litellm` | `LITELLM_BASE_URL`, plus `LITELLM_API_KEY` if the proxy needs one | | Ollama, local | `ollama` | None. `OLLAMA_BASE_URL` if not `http://localhost:11434` | | Claude subscription | `claude_cli` | None. Uses the `claude` CLI's login | | Codex subscription | `codex_cli` | None. Uses the `codex` CLI's login | | GitHub Copilot subscription | `copilot_cli` | None. Uses the `copilot` CLI's login | | OpenCode | `opencode` | None | ## 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: ```bash git check-ignore -q .repowise/.env || printf '\n# repowise API keys (local)\n.repowise/.env\n' >> .gitignore ``` ```powershell 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: ```bash 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 ```bash 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: ```bash 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: ```yaml # .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: | Key or setup | Embedder | |---|---| | `GEMINI_API_KEY` | `gemini` | | `OPENAI_API_KEY` | `openai` | | `OPENROUTER_API_KEY` | `openrouter` | | Ollama running locally, with `OLLAMA_EMBEDDING_MODEL` set (for example `nomic-embed-text`) | `ollama` | ```bash 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](https://docs.repowise.dev/getting-started/setup#troubleshooting). ## 8. Report back Tell the user what you found, in this shape: ```text Repowise is set up in . What this codebase is: Architecture: Hotspots: Worth acting on: Documentation: > Answers: | ranked evidence only (no LLM)> Search: | keywords only> Files added or changed: 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= --yes`, where `` is one of `claude-code`, `codex`, `cursor`, `vscode`, `opencode`, `hermes`. ### Anything else Run `repowise doctor` and read [Troubleshooting](https://docs.repowise.dev/installation/troubleshooting). Report the failing check to the user with the command output.