Quickstart

Install#

pip install repowise

uv tool install repowise

Python 3.11+ required. Verify with repowise --version.

Index the repo#

cd path/to/your/repo
repowise init --yes

No API key needed. Repowise parses every file to an AST, builds the dependency graph, reads your git history, scores every file for code health, and finds dead code. It then renders a complete wiki from that structure: file, module, layer and cycle pages, the architecture diagram, the repo overview, API and infra pages, and the onboarding collection. No LLM calls, no key, no network.

This is the step worth doing first, because it costs nothing and answers the question "is this useful on my codebase". If you want to be explicit that this run must not spend anything, spell it out:

repowise init --yes --no-prose

Those pages are honest about where they came from. Each ends with a footer saying it was derived from structure, and the repo overview covers composition, entry points, clusters and dependencies rather than what the project does end to end. More in Deterministic wiki.

(Optional) Add a key for model-written docs#

The upgrade over the structure-rendered wiki is prose that explains why, plus semantic search. Bring your own key:

export ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY, or run fully offline with Ollama
repowise init

With a provider resolvable, init writes the wiki with a model and shows you a cost estimate before spending anything. See Environment variables for the full provider list.

Already indexed without a key? You do not need to start over. Upgrade the subsystem pages in place, a slice at a time with repowise generate --path <dir> or wholesale with repowise update --full.

Connect Claude Code#

repowise init already wrote .mcp.json at the project root and registered the server in ~/.claude/settings.json. Restart Claude Code and you're done.

To wire up another editor, the MCP server config is:

{
  "mcpServers": {
    "repowise": {
      "command": "repowise",
      "args": ["mcp", "/path/to/your/project"]
    }
  }
}

Drop it in ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, or any other MCP-aware client.

Verify it works#

In Claude Code, ask:

Give me a tour of this codebase.

The agent should call get_overview and reply with the architecture summary. If it falls back to Grep and Read instead, the MCP server isn't connected. See Troubleshooting.

(Optional) Browse the wiki locally#

repowise serve

Starts the MCP server and API on http://localhost:7337, plus a local dashboard at http://localhost:3000: interactive graph, hotspots, ownership, dead code, the generated wiki, decision records, and cost tracking. The dashboard needs Node.js 20+ (auto-downloaded and cached on first run); without it, repowise serve falls back to API-only mode.

(Optional) Auto-sync on commit#

repowise hook install

Installs a post-commit git hook that runs repowise update automatically. The wiki stays current without you thinking about it. Other sync methods (file watcher, GitHub webhook, polling) live in Auto-sync.

Sign in#

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.

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, asks which to include, 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 federated, so pass repo="backend" or repo="all" to any of the ten tools.

Connect Claude Code#

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