Quickstart · repowise docs

Install repowise, index your repo with no API key, open the dashboard and connect your agent. Self-hosted, hosted (repowise.dev), or a multi-repo workspace.

Two ways to start. Self-hosted runs entirely on your machine and your code never leaves. Hosted uses managed infrastructure and a hosted MCP endpoint.

Handing setup to a coding agent? Paste this line into it, and see Set up with your agent for what it does:

Read https://docs.repowise.dev/setup.md and set up Repowise in this repository.

The default run needs no API key, makes no model calls and sends nothing off your machine.

Install

Python 3.11+ and Git are required. Use the first one you have:

uv tool install repowise          # uv brings its own Python
pipx install repowise
python3 -m pip install repowise   # Windows: python -m pip install repowise

Check it with repowise --version. If the shell says command not found, run uv tool update-shell or pipx ensurepath and open a new shell.

Index

From the repository root:

repowise init

init opens on one plan screen: what it found, what it will build, an ETA, and an opt-in model line with what a model adds and costs. Enter starts the free run, which builds the documentation from code with no key and no model calls. m picks a model, e edits the plan, s keeps the global MCP entry where it is, and q quits. A detected API key or logged-in agent CLI is named on the model line and used only after m.

repowise init --yes --no-prose does the free run with no questions. Without --no-prose, --yes uses a model when an API key is configured, with the cost pre-approved. A logged-in Claude Code, Codex or OpenCode is used only with --provider.

The free run parses every file, builds the dependency graph, reads your git history, scores code health, finds dead code, and renders the documentation from that structure. More in Deterministic wiki.

Open the dashboard

repowise serve

This is the first thing to run after init. The API starts on port 7337 and the dashboard on port 3000, or the next free port. The dashboard needs Node.js 20+, and its first run downloads the UI (cached in ~/.repowise/web/). --no-ui starts the API alone. View by view: Dashboard.

Connect your agent

init wires your editors unless you pass --no-editor-setup (or set REPOWISE_SKIP_EDITOR_SETUP=1):

What	Where
MCP server entry	`.mcp.json`, `.vscode/mcp.json` (plus `.vscode/extensions.json`)
Agent context files	`.claude/CLAUDE.md`, `AGENTS.md`, Copilot instructions under `.github/`
Global MCP entry for Claude Code and Claude Desktop, plus Claude Code hooks	`~/.claude/settings.json` and the Claude Desktop config. When it points at another repo, the plan screen shows the move and `s` keeps it; `--yes` points it here and prints the old and new repo
Post-commit hook that runs `repowise update`	The repo's git `post-commit` hook. `e` turns it off, `--no-hook` skips it

Codex, Cursor, OpenCode, Hermes, GitHub Copilot CLI and Kiro need one more command, repowise agents add --target=<id> --yes; any other MCP client takes the entry from repowise agents print-config claude-code. Per-host details: Set up with your agent.

Restart the host, or run /mcp in Claude Code. Most agents read MCP config only at startup.

On VS Code? The Repowise extension registers the MCP server for you and adds editor-native health signals, refactoring CodeLens, and branch risk on top.

Ask the first questions

Ask in plain language. The agent picks the tool, and every one of these works without an API key:

Ask	Tool it reaches for
"Give me a tour of this codebase."	`get_overview`
"What breaks if I change `src/auth.py`?"	`get_context` with callers, `get_risk`
"What code is dead here?"	`get_dead_code`
"What should we fix first?"	`get_health`
"Which tests should I run for my branch against `main`?"	`get_change_risk`

If the agent falls back to Grep and Read instead, the MCP server isn't connected. See Troubleshooting.

Keep it fresh

The post-commit hook runs repowise update after every commit. repowise watch updates while you edit, repowise status shows the mode and how far behind HEAD the index is, and repowise hook uninstall removes the hook. Webhooks and polling: Auto-sync.

Modes and upgrades

repowise status names the index's mode and the command that upgrades it. Every upgrade reuses the index you already have and shows a cost estimate before any model call.

Mode	Reached by	Not yet	Add it with
Index only	`init --mode fast`	Documentation, full git history (blame, co-change)	`repowise update --full` (no key needed)
Built from code	`init --no-prose`, or no key	Written documentation, decisions from PRs, history and comments	`repowise generate` (needs a model)
`Written by <model>`	A model run, or an upgrade above	Nothing
Semantic search, on either documentation mode	An embedder		`repowise reindex --embedder <name>`

A model writes the subsystem and architecture pages, reads decisions from pull requests, history and comments, and lets get_answer write cited answers. Preview the cost with repowise generate --dry-run; a Claude, Codex or GitHub Copilot subscription (claude_cli, codex_cli, copilot_cli) works with no API bill, and Ollama runs fully offline. Set provider: in .repowise/config.yaml so get_answer and post-commit updates use it too. Providers, keys and embedders: Environment variables.

Open repowise.dev and sign in with GitHub.

Index a repo

Click + Index a new repo and paste a GitHub URL. Public repos are free; private repos need the Repowise GitHub App installed (one click from the same dialog).

Indexing runs on managed infrastructure. You'll get an email when it's done, typically 10 to 30 minutes for the first index, seconds for each subsequent push (auto-synced via webhook).

Connect your editor

Open Settings → Editor, mint an API key, and copy the snippet for Claude Code, Cursor, Claude Desktop, VS Code, or Windsurf. Paste it into your MCP client config and restart.

Verify it works

Ask your agent: "What does this codebase do?" It should call get_overview against the hosted endpoint and answer in one round-trip.

Self-hosted vs hosted feature parity. You get every CLI command, every MCP tool, the full dashboard. The hosted version adds managed indexing, push-sync via webhooks, and a security scanning layer. See Hosted vs self-hosted.

If your product spans several repos, index them as a workspace and get cross-repo co-changes, API contract extraction, and federated MCP queries.

Lay out the parent directory

my-workspace/
├── backend/
├── frontend/
└── shared-libs/

Each subdirectory must be its own git repo.

Initialise

cd my-workspace/
repowise init .

Repowise scans for git repos and opens the same plan screen, where r chooses the repos and the primary. In a script, --repos backend,frontend picks them. It indexes each, then runs cross-repo analysis (co-change detection, API contract matching, package dependency mapping).

Serve the workspace

repowise serve

The dashboard shows aggregated stats, repo cards, contracts, and co-change pairs. The MCP server is workspace-aware, so pass repo="backend" to any tool, or repo="all" to the four that merge across the workspace (search_codebase, get_dead_code, get_overview, and get_why's search mode). Workspace mode also adds get_blast_radius and get_architecture on top of the core set.

Connect Claude Code

Same .mcp.json is written at the workspace root.

Full guide: Workspaces.

What to do next

Skim the MCP tools so you know what your agent can ask for.
Ask it something yourself: repowise ask "how does auth work?" or repowise search. See Query commands.
Read How it works for the four intelligence layers behind those tools.
Set up Auto-sync so the wiki stays current.
Browse the CLI reference for all the commands.
Wrap noisy commands (tests, builds, git log) with repowise distill for errors-first output, and check repowise saved for the tokens and dollars it's saved so far. See Distill.

Stuck? Run repowise doctor. It checks API keys, store drift, hook installation, and MCP registration. repowise doctor --repair fixes most issues automatically.

Changed your mind? repowise uninstall lists everything repowise wrote (MCP wiring, hooks, the index) and asks what to remove. repowise uninstall --dry-run shows the same list without changing anything. See CLI reference.