Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: publish verified no-key quickstart (README + repowise.dev) (#627)

Raghav Chamadiyadf2af71774d5
diff --git a/README.md b/README.md
index 457660ebe..cf4541612 100644
--- a/README.md
+++ b/README.md
@@ -380,67 +380,71 @@ the contributor recipe: **[docs/LANGUAGE_SUPPORT.md →](docs/LANGUAGE_SUPPORT.m
---
-## Quickstart
+<a id="quickstart"></a>
-```bash
-pip install repowise # or: uv tool install repowise
-```
+## Quick start (under 5 minutes, no API key)
-### Single repo
+*Index once, and give your agent the dependency graph + git history + code-health
+— not 40 greps.*
+
+**1. Install**
```bash
-cd your-project
-repowise init # builds all five intelligence layers (one-time)
-repowise serve # starts MCP server + local dashboard
+pip install repowise # Windows: python -m pip install repowise
+repowise --version # -> repowise, version 0.27.x
```
-### Multi-repo workspace
+**2. Index your repo — no LLM, no key**
```bash
-cd my-workspace/ # parent dir containing backend/, frontend/, shared-libs/
-repowise init . # scans for git repos, indexes each, runs cross-repo analysis
-repowise serve # workspace dashboard, Live System Map + per-repo pages
+cd /path/to/your/repo
+repowise init --index-only -y
```
-The workspace **Live System Map** renders your services and their typed
-relationships (HTTP / gRPC / events / package deps / co-change) as a
-code-derived, always-current diagram, health-colored, filterable, with
-drill-down to the underlying contracts. See
-[Workspaces](docs/WORKSPACES.md#live-system-map).
-
-`repowise init` automatically registers the MCP server, installs a PostToolUse
-hook in `~/.claude/settings.json`, generates `.mcp.json` at the project root, and
-offers a post-commit hook that keeps everything in sync. If the Codex CLI is
-installed and logged in, interactive runs also offer to write project-local
-`.codex/config.toml`, `.codex/hooks.json`, and a managed `AGENTS.md`;
-non-interactive runs require `--codex`. Skip Codex setup with `--no-codex`; force or
-skip `AGENTS.md` with `--agents` / `--no-agents`.
-
-**Claude Code plugin.** Prefer a one-command setup? Install the plugin from the
-marketplace: it registers the MCP server and hook and adds `/repowise:*` slash
-commands (`init`, `health`, `risk`, `dead-code`, `decision`, …):
-
-```text
+Builds the dependency graph, git history, code-health score, and dead-code findings
+in seconds. (Want the generated wiki + semantic search? Use
+`repowise init --provider gemini|anthropic|openai` with the matching key.)
+
+**3. Connect your agent** — the MCP server is `repowise mcp`, served from the repo dir.
+
+<details><summary><b>Claude Code</b></summary>
+
+```bash
+# Plugin (adds 9 tools + slash commands + skills):
/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowise
+
+# …or wire the MCP server directly:
+claude mcp add repowise -- repowise mcp
+```
+Or commit a project `.mcp.json`:
+```json
+{ "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp"] } } }
```
+</details>
-To add the MCP server to another editor manually:
+<details><summary><b>Codex CLI</b></summary>
-```json
-{
- "mcpServers": {
- "repowise": { "command": "repowise", "args": ["mcp", "/path/to/your/project"] }
- }
-}
+Add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.repowise]
+command = "repowise"
+args = ["mcp"]
```
+Or: `codex mcp add repowise -- repowise mcp`
+</details>
+
+**4. First real call.** Ask your agent: *"Use repowise `get_overview` to summarize this
+repo,"* or *"`get_context` for `src/auth.py`."* You get graph-grounded architecture and
+per-file triage instead of a flurry of greps. ✅
+
+> `get_overview` / `get_context` work in **index-only mode** (no key) — they synthesize
+> from the graph/git/health layers. `search_codebase` / `get_answer` / `get_why` need
+> full mode (the generated wiki).
-> **Init time:** the graph, git, dead-code, and code-health layers build in
-> minutes with **zero LLM calls**; run `repowise init --index-only` for a
-> queryable index almost immediately. The one-time cost is the documentation
-> layer (LLM-generated wiki pages, can run in the background). After that, every
-> commit-triggered update takes **under 30 seconds** and only regenerates the
-> pages your change touched.
+Ready for the full picture? Run `repowise init --provider …` for the generated wiki +
+semantic search, or skip key management entirely with the hosted tier at
+[repowise.dev](https://www.repowise.dev). Full walkthrough: [docs/QUICKSTART.md](docs/QUICKSTART.md).
**Docs:** [Quickstart](docs/QUICKSTART.md) · [User Guide](docs/USER_GUIDE.md) · [CLI Reference](docs/CLI_REFERENCE.md) · [Codex](docs/CODEX.md) · [MCP Tools](docs/MCP_TOOLS.md) · [Distill](docs/DISTILL.md) · [Workspaces](docs/WORKSPACES.md) · [Auto-Sync](docs/AUTO_SYNC.md) · [Upgrading](docs/UPGRADING.md) · [Config](docs/CONFIG.md)
diff --git a/website/getting-started.md b/website/getting-started.md
index 39a81933b..5b9c87934 100644
--- a/website/getting-started.md
+++ b/website/getting-started.md
@@ -20,6 +20,63 @@ The 60-second path to codebase intelligence.
---
+## Quick start (under 5 minutes, no API key)
+
+*Index once, and give your agent the dependency graph + git history + code-health — not 40 greps.*
+
+**1. Install**
+
+```bash
+pip install repowise # Windows: python -m pip install repowise
+repowise --version # -> repowise, version 0.27.x
+```
+
+**2. Index your repo — no LLM, no key**
+
+```bash
+cd /path/to/your/repo
+repowise init --index-only -y
+```
+
+Builds the dependency graph, git history, code-health score, and dead-code findings in seconds. (Want the generated wiki + semantic search? Use `repowise init --provider gemini|anthropic|openai` with the matching key.)
+
+**3. Connect your agent** — the MCP server is `repowise mcp`, served from the repo dir.
+
+<details markdown="block"><summary><b>Claude Code</b></summary>
+
+```bash
+# Plugin (adds 9 tools + slash commands + skills):
+/plugin marketplace add repowise-dev/repowise
+/plugin install repowise@repowise
+
+# …or wire the MCP server directly:
+claude mcp add repowise -- repowise mcp
+```
+Or commit a project `.mcp.json`:
+```json
+{ "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp"] } } }
+```
+</details>
+
+<details markdown="block"><summary><b>Codex CLI</b></summary>
+
+Add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.repowise]
+command = "repowise"
+args = ["mcp"]
+```
+Or: `codex mcp add repowise -- repowise mcp`
+</details>
+
+**4. First real call.** Ask your agent: *"Use repowise `get_overview` to summarize this repo,"* or *"`get_context` for `src/auth.py`."* You get graph-grounded architecture and per-file triage instead of a flurry of greps. ✅
+
+> `get_overview` / `get_context` work in **index-only mode** (no key) — they synthesize from the graph/git/health layers. `search_codebase` / `get_answer` / `get_why` need full mode (the generated wiki).
+
+Ready for the full picture? Run `repowise init --provider …` for the generated wiki + semantic search, or skip key management entirely with the [hosted tier](https://www.repowise.dev). The detailed setup paths below walk through each editor and mode.
+
+---
+
## Choose your path
There are three ways to set up repowise. Pick the one that fits how you work.