Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(quickstart): a human path and an agent path, serve first, and every mode with its upgrade command (#4250)
Raghav Chamadiya2ab409a2d8ed
diff --git a/README.md b/README.mdindex a8acf21ad..cb9ce0695 100644--- a/README.md+++ b/README.md@@ -105,14 +105,15 @@ index, and asks you before anything costs money. Prefer to do it yourself:```bashuv tool install repowise # or: pipx install repowise / pip install repowisecd /path/to/your/repo-repowise init --yes --no-prose # graph, git, health, dead code, docs. No key, no spend.-repowise serve # local dashboard + MCP server+repowise init --yes --no-prose # graph, git, health, dead code, documentation. No key, no spend.+repowise serve # dashboard + MCP server (needs Node 20+; first run downloads the UI)```-`init` wires Claude Code automatically. Then ask your agent *"Use Repowise-`get_overview` to summarize this repository"* or *"What breaks if I change-`src/auth.py`?"*-[Full setup, every agent, optional model-written docs →](docs/start/QUICKSTART.md)+`init` wires Claude Code for this repo and points the global repowise MCP entry+here (on the interactive plan screen, `s` keeps it where it is). Restart Claude Code or run `/mcp`, then ask+*"Use Repowise `get_overview` to summarize this repository"* or *"What breaks if I+change `src/auth.py`?"*+[Full setup, every agent, documentation written by a model →](docs/start/QUICKSTART.md)---@@ -457,8 +458,8 @@ Guides: **[code health](docs/layers/CODE_HEALTH.md)** ·## See all of it-`repowise serve` starts the full web dashboard next to the MCP server. No separate-setup, all local.+`repowise serve` starts the full web dashboard next to the MCP server, all local. It+needs Node.js 20+, and the first run downloads the UI.<table><tr>@@ -948,7 +949,7 @@ Doing a security review? **[docs/business/SECURITY_COMPLIANCE.md →](docs/busin## CLI```bash-repowise init [PATH] # index a codebase (asks; --yes --no-prose needs no key)+repowise init [PATH] # index a codebase (plan screen; --yes --no-prose needs no key)repowise generate [PATH] # write wiki pages with a model, on demandrepowise serve [PATH] # MCP server + local dashboardrepowise update [PATH] # incremental update (--workspace for every repo)diff --git a/docs/start/QUICKSTART.md b/docs/start/QUICKSTART.mdindex 2c030e8ba..f4f7aa719 100644--- a/docs/start/QUICKSTART.md+++ b/docs/start/QUICKSTART.md@@ -1,39 +1,24 @@# Quickstart-Index your repository and have your coding agent answer from that index. The-default setup needs no API key, makes no LLM calls and sends nothing off your-machine.+Index your repository, open the dashboard, and have your coding agent answer+from that index. The default run needs no API key, makes no model calls and+sends nothing off your machine.> Looking for one command's flags? See the> [CLI Reference](../reference/CLI_REFERENCE.md). For everyday workflows, see> the [User Guide](USER_GUIDE.md).-## Fastest path: let your agent do it+## Choose your path-Open your coding agent (Claude Code, Codex, Cursor, VS Code Copilot, OpenCode,-Hermes or any MCP client) in the repository and paste this line:--```text-Read https://docs.repowise.dev/setup.md and set up Repowise in this repository.-```--That page is a runbook written for agents. Following it, the agent will:--1. Install repowise with the first installer it finds: `uv tool install`, then- `pipx`, then `pip`.-2. Index the repository keyless (`repowise init --yes --no-prose`).-3. Wire the MCP server into the host it is running in.-4. Ask you one question: build the documentation from the index for free, or- have an LLM write it. If you pick an LLM, it asks which provider, tells you- which key variable to set in `.repowise/.env`, and shows you a cost estimate.- Nothing is spent until you approve that estimate.-5. Ask you to restart the host, then call `get_overview` to confirm the tools- work.+| You are | Go to |+|---|---|+| A person at a terminal | [Human path](#human-path) |+| A coding agent setting repowise up, or a person who wants one to | [Agent path](#agent-path) |-The agent never asks you to paste a key into the chat. The rest of this page-does the same steps by hand.+Both paths end on the same index. [Modes and upgrades](#modes-and-upgrades)+covers what to add later.-## By hand+## Human path### 1. Install@@ -45,88 +30,87 @@ pipx install repowisepython3 -m pip install repowise # Windows: python -m pip install repowise```-Check it with `repowise --version`. Every LLM provider SDK ships in the base-package, so there is nothing extra to pick at install time.--If the shell says `command not found`, the install directory is not on `PATH`:-run `uv tool update-shell` or `pipx ensurepath` and open a new shell.+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. IndexFrom the repository root:```bash-repowise init # interactive-repowise init --yes --no-prose # scripted: no questions, no key, no spend+repowise init```-Bare `repowise init` scans the repo and asks how to index it: **Everything**-(model-written docs), **No prose** (docs rendered from the code's structure, no-key) or **Advanced** (every indexing and generation option). It shows a cost-estimate and waits for your confirmation before any model call.+`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: no key, no model calls.+`m` picks a model, `e` edits the plan (advanced options, agents, the+post-commit hook), `s` connects only this repo, and `q` quits. A detected API+key or logged-in agent CLI is named on the model line and used only after `m`.-`--yes` never prompts. Pair it with `--no-prose` in scripts, CI and agent-setups: `--no-prose` keeps the run keyless even when an API key happens to be-set in the environment. Without it, `--yes` writes model prose whenever a key-is available, with the cost pre-approved.+`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 keyless run is the one to start with. It parses every file, builds the-dependency graph, reads git history, scores code health, finds dead code, and-renders a complete wiki from that structure. A large repository takes a few-minutes.+### 3. Open the dashboard-### 3. Connect your agent+```bash+repowise serve+```-Unless you pass `--no-editor-setup` (or set `REPOWISE_SKIP_EDITOR_SETUP=1`),-`init` wires these up for you, with or without `--yes`:+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 (about 50 MB, cached in+`~/.repowise/web/`). `--no-ui` starts the API alone, and the+[Docker image](../../docker/README.md) avoids installing Node. View by view:+[Dashboard](DASHBOARD.md).-| What | Where |-|---|---|-| MCP server for Claude Code and other clients that read it | `.mcp.json` at the repo root |-| Claude Code context file | `.claude/CLAUDE.md` |-| VS Code MCP entry | `.vscode/mcp.json` |-| Claude Code and Claude Desktop MCP registration | `~/.claude/settings.json` and the Claude Desktop config |-| Claude Code hooks (session briefing, post-edit context) | `~/.claude/settings.json` |-| Post-commit hook that runs `repowise update` | the repo's git `post-commit` hook |--`--no-editor-setup` skips every row: only `.repowise/` is written.-`--no-hook` skips just the post-commit hook. The command-rewrite hook for-[Distill](../agent/DISTILL.md) is offered as a question in an interactive run-and is left off under `--yes` unless you pass `--distill-hook`.+### 4. Connect your agent++`init` wires your editors unless you pass `--no-editor-setup` (or set+`REPOWISE_SKIP_EDITOR_SETUP=1`). What it writes:++| What | Where | When |+|---|---|---|+| MCP server entry | `.mcp.json`, `.vscode/mcp.json` (plus `.vscode/extensions.json`) | by default |+| Agent context files | `.claude/CLAUDE.md`, `AGENTS.md`, Copilot instructions under `.github/` | by default |+| Global repowise MCP entry for Claude Code and Claude Desktop | `~/.claude/settings.json` and the Claude Desktop config | by default; 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 |+| Claude Code hooks (session briefing, post-edit context) | `~/.claude/settings.json` | with the global entry |+| Post-commit hook that runs `repowise update` | the repo's git `post-commit` hook | by default; `e` turns it off, `--no-hook` skips it |++The global entry points at one repo at a time. Pressing `s` keeps it where it+is, and agents opened in this repo still connect through `.mcp.json`. Point it+here later with `repowise agents add --target=claude-code --scope=user`.+When machine-specific files such as `.claude/CLAUDE.md` would show up in+`git status`, `e` offers to add them to `.git/info/exclude` (off by default).Other hosts need one more command, run after `init`:| Host | Command ||---|---|-| Claude Code | nothing more |-| VS Code (Copilot) | nothing more; the [extension](../agent/VSCODE.md) adds editor features |-| Codex | `repowise agents add --target=codex --yes`, or add `--codex` to `init` (writes `.codex/config.toml`, `.codex/hooks.json` and `AGENTS.md`) |+| Claude Code, VS Code (Copilot) | nothing more; the [VS Code extension](../agent/VSCODE.md) adds editor features |+| Codex | `repowise agents add --target=codex --yes`, or `--codex` on `init` || Cursor | `repowise agents add --target=cursor --yes` || OpenCode | `repowise agents add --target=opencode --yes` || Hermes | `repowise agents add --target=hermes --yes` || GitHub Copilot CLI | `repowise agents add --target=copilot --yes` || Kiro | `repowise agents add --target=kiro --yes` |-| Any other MCP client | `repowise agents print-config claude-code`, then paste the entry into the client's MCP config |+| Any other MCP client | `repowise agents print-config claude-code`, then paste the entry into its MCP config |`repowise agents` lists every supported host and whether it is wired.-`--scope=project` or `--scope=user` limits `agents add` to repo-local or-per-machine config. Per-host details: [Agent integrations](../agent/INTEGRATIONS.md),-[Codex](../agent/CODEX.md), [OpenCode](../agent/OPENCODE.md),-[Hermes](../agent/HERMES.md).--On Claude Code, the plugin adds slash commands and skills on top:+Per-host details: [Agent integrations](../agent/INTEGRATIONS.md). On Claude+Code, the plugin adds slash commands and skills:```text/plugin marketplace add repowise-dev/repowise/plugin install repowise@repowise```-**Restart the host.** Most agents read MCP config only at startup. Claude Code-may ask once to approve the project's `repowise` server; `/mcp` shows its-status. Then ask the agent to call `get_overview`. An architecture summary back-means the setup works.+Then restart the host, or run `/mcp` in Claude Code. Most agents read MCP+config only at startup.-## First questions to ask+### 5. First questionsAsk in plain language. The agent picks the tool.@@ -139,67 +123,129 @@ Ask in plain language. The agent picks the tool.| "Which tests should I run for my branch against `main`?" | `get_change_risk`, `get_risk` |Every one of these works without an API key. What each tool returns:-[MCP Tools](../agent/MCP_TOOLS.md).--The same answers are on the command line:+[MCP Tools](../agent/MCP_TOOLS.md). The same answers on the command line:```bashrepowise health # lowest-scoring files, and whyrepowise dead-code # what nothing referencesrepowise risk main..HEAD # size and bug-fix record for your branch-repowise impacted-tests main..HEAD # tests your branch's changes exercise-```--## Open the dashboard--```bash-repowise serve```-The API starts on `http://localhost:7337` and the dashboard on-`http://localhost:3000`. The dashboard needs Node.js 20+; it downloads once-(about 50 MB) and is cached in `~/.repowise/web/`. `--no-ui` starts the API-alone, and the [Docker image](../../docker/README.md) avoids installing Node.-View by view: [Dashboard](DASHBOARD.md).+## Agent path-## Optional upgrades+A person can hand setup to their agent by pasting this line into Claude Code,+Codex, Cursor, VS Code Copilot, OpenCode, Hermes or any MCP client:-**Model-written docs.** A keyless index renders the subsystem pages from-structure. `repowise generate` rewrites them as prose that explains how the-code fits together, reusing the index you already have. Put the key in-`.repowise/.env` (gitignored; loaded by `generate`, `update` and the MCP-server), preview, then write:--```bash-repowise generate --provider anthropic --dry-run # cost estimate only-repowise generate --provider anthropic # asks before spending+```text+Read https://docs.repowise.dev/setup.md and set up Repowise in this repository.```-`--path <dir>` or `--page <id>` writes a subset. Providers that need no key:-`ollama` (local), `claude_cli` and `codex_cli` (your subscription login),-`opencode`. Full list and key variables: [Config](../reference/CONFIG.md).--**Semantic search.** Full-text search works on any index. For semantic search,-configure an embedder (`REPOWISE_EMBEDDER`, or `--embedder` on `init`) and run-`repowise reindex`.--**Resuming.** If a run was interrupted, or a provider outage left some pages-missing, `repowise init --resume` writes only the pages that are absent.+That runbook follows the steps below. An agent can also follow them directly.++1. **Install** with the first installer that exists: `uv tool install+ repowise`, then `pipx install repowise`, then `python -m pip install+ repowise`.+2. **Index without spending.** This command never prompts and never calls a+ model, whatever keys are set:++ ```bash+ repowise init --yes --no-prose+ ```++ It points the global repowise MCP entry at this repo and prints the old and+ new target. Add `--no-editor-setup` in CI, in a sandbox, or on a repo the+ person only wants to try: then only `.repowise/` is written.+3. **Run it in the background.** A small repo takes under a minute; a few+ thousand files can take several minutes, longer than many tool timeouts.+ Wait for the process to exit instead of relying on a fixed timeout. While+ a first run is still going, `repowise status` reports the index as+ incomplete, so read it after the process exits.+4. **Read the exit code.**++ | Code | Meaning | Next |+ |---|---|---|+ | `0` | Ready | continue |+ | `2` | Finished with gaps; everything is saved | the last line names what is missing and the command that adds it |+ | `130` | Interrupted | `repowise init --resume` |+ | other | Failed | `repowise doctor` |++ `repowise status --format json` then gives the mode, the counts and the+ next command. With `--progress json`, init writes one JSON event per line+ to stdout and ends on a summary line with the status, mode, spend and next+ commands.+5. **Reconnect.** MCP tools appear only after the host restarts, or after+ `/mcp` in Claude Code. Do not assume they are active in the current session.+6. **First tools.** Call `get_overview`. An architecture summary back means+ the setup works. Then `get_context`, `search_codebase` and `get_answer`.+7. **Offer a model, never spend unasked.** If the person wants written+ documentation, show the estimate with `repowise generate --dry-run`, and run+ `repowise generate` only after they approve it. The person puts the key in+ `.repowise/.env` (gitignored). Never ask for a key in the chat.++## Modes and upgrades++`repowise status` shows which mode an index is in.++| Mode | Reached by | You get | Not yet | Add it with |+|---|---|---|---|---|+| Index only | `init --mode fast` | graph, essential git history, health, dead code | documentation, full git history (blame, co-change) | `repowise update --full` (no key needed) |+| Built from code | `init --no-prose`, or no key | graph, full git history, health, dead code, documentation built from code, decisions from markers and ADRs, full-text search | written documentation, decisions from PRs, history and comments | `repowise generate` (needs a model) |+| Written by \<model\> | a model run, or an upgrade above | all of the above, written documentation, decisions from PRs, history and comments | nothing | |+| Semantic search, on top of either documentation mode | an embedder (see [the matrix](#providers-and-embedders)) | search by meaning as well as by text | | `repowise reindex --embedder <name>` |++`repowise update --full` with a model configured goes straight from Index only+to Written by \<model\>. Every upgrade reuses the index you already have and+shows a cost estimate before any model call.++### What a model adds++- Written documentation: subsystem and architecture pages that explain how the+ code fits together, in place of pages built from code.+- Decisions read from pull requests, git history and code comments.+ `repowise generate` reads the ones a keyless run skipped.+- Synthesized answers from `get_answer` and the dashboard chat.++Semantic search needs an embedder, which is separate from the model. Without+one, search is full-text, and every run names the command that turns it on.++### Providers and embedders++| Provider | Credential | Embedder of its own |+|---|---|---|+| `gemini` | `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) | yes |+| `openai` | `OPENAI_API_KEY` | yes |+| `openrouter` | `OPENROUTER_API_KEY` | yes |+| `edenai` | `EDENAI_API_KEY` | yes |+| `ollama` | none (local) | yes, with `OLLAMA_EMBEDDING_MODEL` |+| `anthropic`, `deepseek`, `kimi`, `litellm` | `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `KIMI_API_KEY`, `LITELLM_API_KEY` | no |+| `claude_cli`, `codex_cli`, `opencode` | your logged-in subscription | no |++When nothing names an embedder, repowise takes the first one with a key set,+in the order gemini, openai, openrouter, ollama, edenai, and every model run+prints which embedder it uses and why. init reads each logged-in Claude Code,+Codex or OpenCode's auth status and offers it with its call count, time and+billing (plan quota, or per token for an API key), Claude Code first. A Codex+signed in through ChatGPT stays in the picker but is not offered. An agent+CLI is used only when you pick it or pass `--provider`. Keys, models and base URLs:+[Config](../reference/CONFIG.md).## Keeping it fresh-The post-commit hook `init` installed runs `repowise update` after every-commit, so there is usually nothing to do. Other options:+The post-commit hook, when installed, runs `repowise update` after every commit.+Other options:```bashrepowise update # incremental catch-up, by handrepowise watch # update continuously while you edit-repowise status # what is indexed and how far behind HEAD+repowise status # mode, counts, and how far behind HEAD```-`repowise hook uninstall` removes the post-commit hook. Webhooks, polling and-workspace-wide sync: [Auto-Sync](../scale/AUTO_SYNC.md). A new `git worktree`-seeds its index from the main checkout: [Worktrees](../scale/WORKTREES.md).+`repowise hook uninstall` removes the post-commit hook. Webhooks and polling:+[Auto-Sync](../scale/AUTO_SYNC.md). Several repositories as one:+[Workspaces](../scale/WORKSPACES.md); `init` in a folder of repos opens the+same plan screen, where `r` chooses the repos, and `--repos a,b` picks them in+a script. A new `git worktree` seeds its index from+the main checkout: [Worktrees](../scale/WORKTREES.md).## Where to go next@@ -210,29 +256,22 @@ seeds its index from the main checkout: [Worktrees](../scale/WORKTREES.md).| Context that arrives without the agent asking | [Hooks](../agent/HOOKS.md) || Fewer tokens on test and build output | [Distill](../agent/DISTILL.md) || What the health score measures | [Code Health](../layers/CODE_HEALTH.md) |-| Unused files and exports | [Dead Code](../layers/DEAD_CODE.md) |-| Size and bug-fix record of a change | [Change Risk](../layers/CHANGE_RISK.md) || Gates and annotations on pull requests | [CI](CI.md) |-| Several repositories as one | [Workspaces](../scale/WORKSPACES.md) || Every setting and environment variable | [Config](../reference/CONFIG.md) |-| Something is not working | [Troubleshooting](TROUBLESHOOTING.md) |## TroubleshootingStart with `repowise doctor`. It checks the install, API keys, index drift,store health and each wired agent's MCP entry.-**`repowise: command not found` after install.** Run `uv tool update-shell`-(uv) or `pipx ensurepath` (pipx), open a new shell, and restart the agent-host, which starts `repowise` by name.--**The agent does not see the repowise tools.** Restart the host first. If they-are still missing, run `repowise doctor --repair`, which re-registers a stuck-Claude Code MCP entry and refreshes every wired agent's config. Failing that,-re-run `repowise agents add --target=<id> --yes`.--**The agent answers from old code.** `repowise status` shows drift and-`repowise update` catches up.--More, including large repositories, Windows encoding, empty results and-removing repowise: [Troubleshooting](TROUBLESHOOTING.md).+- **`repowise: command not found`.** Run `uv tool update-shell` or `pipx+ ensurepath`, open a new shell, and restart the agent host.+- **The agent does not see the tools.** Restart the host or run `/mcp`. Then+ `repowise doctor --repair`, or `repowise agents add --target=<id> --yes`.+- **The dashboard does not open.** Check that `node --version` is 20 or newer,+ then run `repowise serve --refresh-ui`.+- **The agent answers from old code.** `repowise status` shows drift and+ `repowise update` catches up.+- **A run stopped part way.** `repowise init --resume` continues it.++More: [Troubleshooting](TROUBLESHOOTING.md).diff --git a/docs/start/USER_GUIDE.md b/docs/start/USER_GUIDE.mdindex 97017147e..e048f9f84 100644--- a/docs/start/USER_GUIDE.md+++ b/docs/start/USER_GUIDE.md@@ -187,7 +187,7 @@ This is the main event, and it has its own docs. The short version:VS Code itself. Codex needs `--codex` on `init`; Cursor, OpenCode and Hermesneed `repowise agents add --target=<id>`. The Claude Code plugin is optionaland adds slash commands and skills. The per-host table is in-[Quickstart](QUICKSTART.md#3-connect-your-agent); [Codex](../agent/CODEX.md),+[Quickstart](QUICKSTART.md#4-connect-your-agent); [Codex](../agent/CODEX.md),[OpenCode](../agent/OPENCODE.md) and [Hermes](../agent/HERMES.md) have theirown guides.@@ -261,7 +261,7 @@ repowise serveAPI on `http://localhost:7337`, dashboard on `http://localhost:3000`. Node.js20+, `--no-ui` and the Docker image are covered in-[Quickstart](QUICKSTART.md#open-the-dashboard).+[Quickstart](QUICKSTART.md#3-open-the-dashboard).`Ctrl+K` / `Cmd+K` opens a command palette from any page, which is the fastest wayto move between views and repos.