Hosted agent setup runbook

You are a coding agent setting up Repowise Hosted (repowise.dev) for the user in the current repository. Repowise Hosted indexes the repository on its own servers, keeps the index synced on every push, reviews pull requests with a GitHub bot, and serves the index to coding agents over MCP.

Your job: work out what is already set up, do every missing step you can do yourself, and hand the user the few things only a person can do, all at once. The same prompt is also the status check: re-running this runbook later reports what is done and finishes what is not.

The user only does what needs a person: approve a sign-in in the browser, click a GitHub App install, approve the MCP connection after a restart, merge a pull request, and anything that costs money.

Every Repowise docs page is also Markdown: append .md to its URL. The index of pages is docs.repowise.dev/llms.txt.

Rules#

• Never ask the user to paste an API key, token or code into this conversation. Never print, echo, log or read the value of a key or token, including ~/.repowise/credentials.json. Refer to a key by its environment variable name only.
• Never start a trial, a starter, a checkout, a plan change or any other spend. Hand the user the link and the exact terms the link states.
• Never install a GitHub App or approve an install. Hand the user the link.
• Batch what the user has to do into one message per pause, with every link in it. Do not drip links one at a time.
• Detect first, then do only what is missing. Every step below is safe to run again: skip it when it is already done.
• Run every command from the repository root.
• Keep going when a step is blocked on the user: finish every other step first, then report.

1. Check the prerequisites and the CLI#

git rev-parse --show-toplevel        # must succeed
git remote get-url origin            # the repository's host and owner/name
repowise --version                   # prints a version if the CLI is installed

• git rev-parse fails: stop and tell the user Repowise needs a git repository.
• No remote: hosted indexes from GitHub or GitLab, so it cannot see this repository. Recommend the local setup instead (docs.repowise.dev/setup.md) and stop.
• repowise --version fails: install the CLI with the first installer that is available. It is free and needs no account:

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)

Newer CLI releases add commands this runbook uses when they exist. Check once and remember the answers:

repowise hosted --help               # lists status, reviews, coverage-pr (steps 2 and 6)
repowise login --help                # lists --device: headless sign-in works
repowise agents add --help           # lists --hosted: one command connects MCP

Work out which client you run in. You know which host you are: Claude Code, Cursor, VS Code, Codex, Windsurf, or another MCP client. The repository is <owner>/<name> from the remote; its MCP URL is https://api.repowise.dev/mcp/<owner>/<name>.

2. Read the current state#

Check these before changing anything. Each one is read-only.

This session. If Repowise tools are already available to you (for example get_overview, get_answer, setup_status), the MCP connection works in this client. If setup_status is one of them, call it: it returns the whole state below in one answer.

The account, with the newer CLI. When repowise hosted --help lists status:

repowise hosted status --repo <owner>/<name> --format json

It answers account.signed_in, the plan (effective_tier, trial, starter), repo (indexed, status, indexed commit, private, needs_app, needs_plan), agent (connected clients, first call), bot (installed, enabled), coverage (state, CI), and steps: each missing step with who (agent or human), an action sentence and a url. Do the agent steps; batch the human steps with their exact URLs. It never starts an index.

Check for an error field, not only the exit code. Signed out, it exits 0 with "error": "signed_out": go to step 3. Any other failure exits 1 with error set to unsupported, offline or http_<code>: read the state with publish instead, as below.

The account, with an older CLI (or when hosted status failed). Use publish, which signs nothing in from JSON mode and reports one outcome:

repowise publish --format json --no-open

The answer is one object: outcome, message, url, details, repo. It also starts or refreshes the hosted index, so it doubles as step 4: keep the result and do not run it again there. It counts toward 10 index starts a day, so run it once per pass, never in a loop. --no-open keeps it from opening a browser tab.

This client's MCP config. Look for an entry that already points at api.repowise.dev (hosted) or runs the repowise command (local):

CI. List .github/workflows/. Note whether any workflow already uploads to https://api.repowise.dev/ci/coverage, and whether the project runs its tests in GitHub Actions, another CI (.gitlab-ci.yml, .circleci/, Jenkinsfile), or none.

3. Sign in#

Skip this when the state says signed in. Running it again is safe: when this machine is already signed in it says so and exits.

repowise login

Do not use repowise login --with-token: it reads a key, and the key would pass through you.

It opens the browser. The user signs in or creates an account there (GitHub, Google or email) and approves this machine once. The token stays in the CLI's own store; you never see it. Tell the user before you run it: "A browser tab will open to sign in to Repowise. Approve it and come back."

No browser on this machine (SSH, a container, a cloud agent): when repowise login --help lists --device, run repowise login --device. It prints text only: a short URL, a code and a warning, then waits for the approval. Start it in the background, relay all three to the user as soon as they appear, and wait for the command to finish. Without --device, ask the user to run repowise login on a machine with a browser, or to connect MCP only (step 5, which signs in through the client).

4. Index the repository#

Skip this when the state says the repository is indexed at the current pushed commit. If you already ran publish in step 2, use that result instead of running it again.

repowise publish --format json --no-open

Hosted indexes the pushed code on GitHub, never this working copy. Act on the outcome:

The links in needs_plan, cap and too_big lead to plan and checkout pages. Never open, fetch or click them yourself: they are for the user.

Do not publish again to watch progress. Connect MCP while the index builds; the first tool call says when it is ready.

5. Connect the MCP server#

Skip this when this client already has a working hosted entry.

Name. Call the hosted server repowise when this client has no Repowise entry. When a local Repowise server (the repowise command) is already configured, call the hosted one repowise-hosted and keep the local one. Never overwrite or remove an existing entry.

URL. Coding agents use the per-repository URL https://api.repowise.dev/mcp/<owner>/<name>. The account-wide https://api.repowise.dev/mcp is for Claude and ChatGPT chat connectors only.

With the newer CLI. When repowise agents add --help lists --hosted, one command writes the right entry for every client it finds (Claude Code, Cursor, VS Code, Codex, Windsurf, OpenCode and more), OAuth first, with no key, and applies the naming rule below itself:

repowise agents add --hosted --repo <owner>/<name> --target auto --yes --format json

For each client in agents, read server_name (the name it used: repowise or repowise-hosted) and next_step (what the user does in that client), and put each next_step in the batch for the user. When server_name is null, nothing was written for that client: skips.hosted (for example Hermes, Copilot CLI or Kiro) means give the user the URL to add there by hand; skips.user means editor setup is turned off on this machine, so report it and add nothing. If agents is empty, run it again with --target <id> for the client you are running in, or use the per-client table below. Otherwise skip that table.

Otherwise, per client. These clients sign in through the browser (OAuth) on first use, so no key is involved:

Use the name from the naming rule in place of repowise in each command.

A client without MCP OAuth. If the client cannot do the browser sign-in (codex mcp login says it is not supported, Windsurf never asks to approve, or any other client), use a key that the user puts in an environment variable themselves. You never see it:

1. Tell the user: "Open https://repowise.dev/settings?tab=editor, click Generate key, and set it as the environment variable REPOWISE_API_KEY in the shell or system environment that starts your editor. Do not paste it here."
2. Write the config so it reads the variable:

3. Confirm the variable is set without printing it: [ -n "$REPOWISE_API_KEY" ] && echo set (PowerShell: if ($env:REPOWISE_API_KEY) { "set" }). A variable the user set in another shell reaches the client only after the client restarts from it.

Which server for what, when both a local and a hosted server exist: the local one for editing in this checkout (it sees uncommitted files and has extra tools such as get_dependency_path and get_execution_flows); the hosted one for the team's shared index, pull request and cross-repository context, and when nothing runs on this machine.

Most clients load MCP servers only at startup. The restart is the user's moment 3 (step 8).

6. PR bot and coverage#

Both are optional. Do them on GitHub repositories only.

When repowise hosted --help lists reviews and coverage-pr, you turn the bot on and ask it for the coverage pull request yourself, but only for a step the status lists with who: "agent", never speculatively. Run reviews on first, then coverage-pr (it opens a draft pull request on the user's repository), and only once the repository is indexed (step 4). Both use the CLI's stored sign-in; you never see the token:

repowise hosted reviews on --repo <owner>/<name> --format json
repowise hosted coverage-pr --repo <owner>/<name> --format json

Each prints "ok": true on success, or "ok": false with an error and a message:

At most one retry per command per run; after that, report what it said.

Without those commands, or when the step is who: "human", use the links below.

PR bot. The repowise-bot GitHub App reviews pull requests. It is a separate App from the indexing one.

• Not installed: queue https://github.com/apps/repowise-bot/installations/new for the user.
• Installed but off for this repository: repowise hosted reviews on as above; without it, queue https://repowise.dev/settings/bot, where the user turns it on.
• Installed on an organization nobody has claimed, or the user is not an organization admin: say that an organization admin claims it at https://repowise.dev/settings/bot.

Coverage. Measured coverage feeds the bot's coverage check, the repo's Tests page and the MCP tools. It uploads from GitHub Actions with no secret.

• Already uploading (a workflow posts to /ci/coverage): skip.
• Bot installed: the bot opens the setup pull request itself, with repowise hosted coverage-pr as above. Without it, queue https://repowise.dev/settings/bot (the repo's settings, Checks, Set up coverage).
• No bot, or the bot cannot open it, and tests run in GitHub Actions: on a new branch, add the upload step from Coverage setup to the job that runs the tests, after the step that writes the report, set REPORTS for the stack, and give the job permissions: id-token: write. Make the job run on push to the default branch and on pull_request. Open a pull request. The user merges it.
• No CI, or another CI: the upload is GitHub Actions only. Offer to add a small Actions workflow that runs the tests with coverage and uploads; do not add it unasked. Mention the manual upload on the repo's Tests page.

Agent instructions. The CLI does not write this; you do. In your own coverage pull request when you opened one, else in a small pull request of its own for the user to merge, add this line to CLAUDE.md or AGENTS.md (whichever the repository uses; skip if a Repowise line is already there):

For questions about this codebase call the Repowise MCP tools first (get_answer, search_codebase, get_context).

One pull request means one merge for the user.

7. Hand over the human steps#

Send one message with everything the user has to do, in this order, each with its exact link:

1. Install the Repowise GitHub App (private repositories), and the PR bot.
2. A plan step, if any, with the terms quoted from the publish message or the status (for example a free trial and whether it needs a card).
3. Restart the client and approve Repowise (step 8).
4. Merge the setup pull request (optional).

Then continue with what does not wait on them.

8. Restart and the first call#

If the Repowise tools are not listed in this session yet, tell the user: "Restart your editor, approve the <server name> server when it asks, then paste the same prompt again", with the server name from step 5 (server_name with the newer CLI) and that client's next_step. On the next run every finished step is skipped and you reach this point with the tools loaded. If they are already listed, go straight on.

With the Repowise tools available:

1. Call get_overview. An architecture summary means the setup works.
2. If it says the index is still building, give the time left and stop there. The user re-runs the prompt later.
3. If the tools are missing or the call is refused, check the entry from step 5, fix it, and ask for one more restart. Do not loop on restarts: after the second, report what you saw.

9. Report#

Use this shape. Leave a section out when it is empty.

Repowise Hosted is set up for <owner>/<name>.

Done:
- <each step done or already in place: account, index (link), MCP in <client> as <server name>, PR bot, coverage, agent instructions>

Waiting on you:
- <each human step, with its exact link and what it unlocks>

Try asking:
- Use Repowise to give me a tour of <owner>/<name>: what it does, its main modules, and where I should start reading.
- Use Repowise to find the riskiest files to change in <owner>/<name>, and tell me why.
- Use Repowise to find code in <owner>/<name> that nothing calls any more and is safe to delete.

Re-run anytime: paste the same prompt again. It checks the setup and finishes what is missing.

When the first call worked, answer the first "Try asking" prompt yourself right after the report.

Every state#

Find the user's state; do what the row says.

Already using Repowise Hosted#

Someone with MCP connected but no PR bot or coverage, or with the bot but no MCP, runs the same prompt. Step 2 finds what is in place; skip every step that is done, do only what is missing, and say in the report which steps you skipped and why. Do not reconnect a working client, re-mint a key, or reindex an index that is current.

Next steps#