/init

description: Set up Repowise for this codebase. Installs if needed, asks about your preferences, and runs the indexing.
allowed-tools: Bash, Read, Write, AskFollowupQuestion

Repowise Init

You are helping the user set up Repowise for their codebase. Follow this sequence precisely.

Step 1: Check if repowise is installed

Run: `repowise --version`

If the command fails or is not found, ask the user:

"Repowise isn't installed yet. I can install it for you. Which do you prefer?"

• `pip install repowise` (recommended, includes every LLM provider SDK)
• "I'll install it myself"

If they want you to install it, run `pip install repowise`. If that fails, try `python -m pip install repowise`.

After install, verify with `repowise --version`.

If repowise IS found, print the version and move to Step 2.

Step 2: Check if this repo is already indexed

Check if `.repowise/` directory exists in the project root.

If it exists, tell the user: "This repo is already indexed by Repowise. Run `/repowise:status` to check health, or `/repowise:update` to refresh. If you want to re-index from scratch, I can run `repowise init --force`."

Then stop — do not continue to Step 3 unless the user asks to re-index.

If `.repowise/` doesn't exist, move to Step 3.

Step 3: Offer the mode, but do not block on it

Repowise needs **no API key at all**. Never make a key a precondition for setting it up, and never stop and wait if you cannot get an answer.

Tell the user:

"Repowise indexes your repo and writes a complete wiki with no API key. I'll run `repowise init --yes` unless you'd rather pick:

1. **Default (no key)** — full index plus a wiki rendered from your code's structure. Free, fast, nothing to configure. 2. **Model-written wiki** — everything above, but an LLM writes the wiki prose instead of rendering it from structure, which also enables decision mining. Needs a provider key (Anthropic, OpenAI, Gemini, or Ollama locally). You can start keyless and upgrade any page later with `repowise generate`. 3. **Show me the flags.**"

If the user does not answer, or you are running unattended, take option 1.

If Default (no key):

Skip provider selection entirely. Construct:

repowise init --no-prose --yes

Jump to Step 3b.

If Full mode:

Move to Step 3b, then Step 4.

If "show me flags":

Print the full flag reference:

repowise init [PATH]

Core flags:
  --provider NAME        LLM provider: anthropic, openai, gemini, ollama, litellm
  --model NAME           Model identifier override
  --prose / --no-prose   Write the subsystem (concept) pages as model prose
                         (--prose, needs a key), or render the whole wiki from
                         structure with no model and no spend (--no-prose).
                         Every other page is structural either way.
                         Default: prose when a key is available.
  --mode fast            Quick first pass on very large repos: no wiki at all.

Embeddings:
  --embedder NAME        Embedding provider: gemini, openai, mock (default: auto-detect)

Cost control:
  --concurrency N        Max parallel LLM calls (default: 10)
  --test-run             Limit to top 10 files by PageRank for quick validation

Exclusions:
  -x, --exclude PATTERN  Gitignore-style exclude patterns. Repeatable.
                         Example: -x 'vendor/**' -x 'generated/'
  --skip-tests           Skip test files
  --skip-infra           Skip infrastructure files (Dockerfile, Makefile, Terraform, shell)

Git:
  --commit-limit N       Max commits to analyze per file (default: 500, max: 10000)
  --follow-renames       Track files across renames (slower but more accurate history)

Editor integration:
  --editor-setup /       Register (default) or skip the global MCP server entry
  --no-editor-setup      and Claude Code hooks in ~/.claude/settings.json and
                         Claude Desktop's config, plus the distill rewrite-hook
                         offer. There is one 'repowise' MCP entry per config, so
                         a later init from another repo repoints it. See Step 3b.

Output:
  --no-claude-md         Don't generate/update CLAUDE.md
  -y, --yes              Skip cost confirmation prompt
  -v, --verbose          Show per-phase internals plus debug logs (quiet by default)

Recovery:
  --resume               Resume a previously interrupted init
  --force                Re-index from scratch, overwriting existing .repowise/

Dry run:
  --dry-run              Show generation plan and cost estimate without running

Then ask if they want you to construct a command or if they'll handle it.

Step 3b: Is this repo a keeper?

Every path reaches this step. It is about the repo, not the provider.

By default `init` registers repowise as the user's global MCP server, in `~/.claude/settings.json` and Claude Desktop's config. There is **one** `repowise` key in each file, so this repo replaces whatever repo is registered now. That is the right default for the repo someone actually works in, and the wrong one for a checkout that is about to disappear.

Add `--no-editor-setup` when either of these holds:

• the path is a scratch clone, a fixture, a sample, a vendored copy, or sits

under a temp directory

• it is a linked git worktree rather than the main checkout. Check with

`git rev-parse --git-common-dir`: a value other than `.git` means a worktree

Also add it if the user says they don't want their editor or MCP setup touched. Do **not** infer that from "just index it" or "don't ask me questions" — those are about prompts, not config.

The index, the wiki, and every project-local file are identical either way. Only the machine-wide registration is skipped, and it can be done later by re-running `repowise init` in that repo without the flag.

Whichever you pick, say which in one line so the user can correct you.

If `init` prints "Replacing the existing repowise MCP …", relay it. The global entry just moved to th