# Quickstart

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](https://docs.repowise.dev/getting-started/for-agents) for what it does:

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

## Self-hosted

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

1. **Install**

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

   ```bash
   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.

2. **Index**

   From the repository root:

   ```bash
   repowise init
   ```

   `init` opens on one [plan screen](https://docs.repowise.dev/cli/indexing#the-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](https://docs.repowise.dev/intelligence/deterministic-wiki).

3. **Open the dashboard**

   ```bash
   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/`). The dashboard opens in your browser once it is up;
   `--no-open` skips that. `--no-ui` starts the API alone. View by view:
   [Dashboard](https://docs.repowise.dev/dashboard).

4. **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](https://docs.repowise.dev/getting-started/for-agents#other-agents).

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

   > **Note**
   >
   > **On VS Code?** The [Repowise extension](https://docs.repowise.dev/getting-started/vscode)
   > registers the MCP server for you and adds editor-native health signals,
   > refactoring CodeLens, and branch risk on top.

5. **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](https://docs.repowise.dev/installation/troubleshooting).

6. **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](https://docs.repowise.dev/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](https://docs.repowise.dev/installation/env-vars).

## Hosted (repowise.dev)

1. **Sign in**

   Open [repowise.dev](https://repowise.dev) and sign in with GitHub.

2. **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).

3. **Connect your editor**

   Open [**Settings → Editor**](https://www.repowise.dev/settings?tab=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.

4. **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.

> **Note**
>
> **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](https://docs.repowise.dev/hosted/vs-self-hosted).

## Multi-repo workspace

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

1. **Lay out the parent directory**

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

   Each subdirectory must be its own git repo.

2. **Initialise**

   ```bash
   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).

3. **Serve the workspace**

   ```bash
   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.

4. **Connect Claude Code**

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

Full guide: [Workspaces](https://docs.repowise.dev/multi-repo/workspace-setup).

## What to do next

- Skim the [MCP tools](https://docs.repowise.dev/mcp/overview) 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](https://docs.repowise.dev/cli/query).
- Read [How it works](https://docs.repowise.dev/getting-started/how-it-works) for the four
  intelligence layers behind those tools.
- Set up [Auto-sync](https://docs.repowise.dev/auto-sync) so the wiki stays current.
- Browse the [CLI reference](https://docs.repowise.dev/cli/overview) 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](https://docs.repowise.dev/cli/distill).

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

> **Note**
>
> **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](https://docs.repowise.dev/cli/agents).