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.

feat(init): add --no-editor-setup to skip global MCP/hook registration (#1086)

Raghav Chamadiya629e35ee75ec
diff --git a/docs/agent/HOOKS.md b/docs/agent/HOOKS.md
index 5d4063b00..4a5d4adf6 100644
--- a/docs/agent/HOOKS.md
+++ b/docs/agent/HOOKS.md
@@ -60,6 +60,13 @@ repowise entries are migrated in place on the next `init` / `update`. All of the
route through the `repowise-augment` console script (a standalone entry point
that does not load the full CLI).
+`repowise init --no-editor-setup` skips this whole group, along with the MCP
+server registration that shares the same file. Reach for it when the repo is
+temporary (a scratch clone, a worktree, a benchmark loop) and you do not want
+that machine-wide config to move. `REPOWISE_SKIP_EDITOR_SETUP=1` is the same
+switch for CI. The index itself is identical either way. To register the repo
+afterwards, re-run `repowise init` in it without the flag.
+
### SessionStart, live freshness + relevant decisions
The generated `CLAUDE.md` is static between reindexes, so it can't say whether
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index d0a4a170f..093cd4cd4 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -14,6 +14,8 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport
**Auto-setup:** `repowise init` automatically registers the MCP server and installs proactive hooks for Claude Code. `repowise init --codex` writes project-local Codex MCP config and hooks.
+**Opting out:** each Claude config holds a single `repowise` MCP key, so indexing a second repo repoints it rather than adding a second entry. Pass `repowise init --no-editor-setup` (or set `REPOWISE_SKIP_EDITOR_SETUP=1`) for a repo you do not want registered: a scratch clone, a worktree, a CI or benchmark run. Nothing about the index changes, and re-running `repowise init` without the flag registers it later. `init` also prints a notice when it is about to repoint an existing entry.
+
---
## The ten flagship tools
diff --git a/docs/architecture/editor-files.md b/docs/architecture/editor-files.md
index 02c11a459..5d5d7e927 100644
--- a/docs/architecture/editor-files.md
+++ b/docs/architecture/editor-files.md
@@ -342,6 +342,60 @@ Both can be disabled:
repowise init --no-claude-md .
```
+**Project-local files vs. global registration:**
+
+`init` writes in two different places, and the flags split along that line.
+
+*Project-local*, all inside the repo, versionable, one set per repo:
+`.repowise/mcp.json`, `.mcp.json`, `.claude/CLAUDE.md`, `AGENTS.md`,
+`.vscode/mcp.json`, `.vscode/extensions.json`, `.codex/`. Three have an opt-out
+flag (`--no-claude-md`, `--agents`, `--codex`) and the VS Code pair is
+prompt-gated in an interactive run. Only `.repowise/mcp.json` and the root
+`.mcp.json` are written unconditionally.
+
+*Machine-wide*, outside the repo, one shared copy for every repo you index, all
+written by `register_editor_clients()` in `editor_setup.py`:
+
+- the `repowise` MCP entry in `~/.claude/settings.json` and in Claude Desktop's
+ config
+- the Claude Code PostToolUse and SessionStart hooks
+- `env.ENABLE_TOOL_SEARCH` in `~/.claude/settings.json` (skipped for repos on
+ the lean MCP tool profile, and never overwritten if you already set it)
+
+Only the Claude integration implements `register_client`; Codex and VS Code
+read project-local config, so theirs are no-ops.
+
+The distill command-rewrite hook is machine-wide too, but it is offered
+separately (`offer_distill_rewrite_hook`) because it is strictly opt-in.
+
+`--no-editor-setup` turns off that machine-wide group, including the rewrite
+hook offer, and leaves the project-local files alone:
+
+```bash
+# Index the repo, leave everything outside it untouched
+repowise init --no-editor-setup --yes .
+```
+
+Reach for it whenever the checkout or the binary running `init` is temporary:
+a scratch clone, a release smoke test from a throwaway venv, a git worktree, a
+benchmark loop over many repos. Each config holds a **single** `repowise` MCP
+key, so a second `init` replaces the entry rather than adding one beside it,
+and the breakage only shows up later, when the path it now points at is gone
+and the MCP server quietly stops loading. `init` prints a notice when it is
+about to repoint an existing entry, but the flag is how you avoid it.
+
+One exception, so the two flags do not cancel each other out: `--no-editor-setup
+--no-distill-hook` still records the `distill.commands.enabled: false` opt-out in
+this repo's `config.yaml`. That record is repo-local, and it is the only thing
+that gates an already-installed global rewrite hook off here.
+
+`REPOWISE_SKIP_EDITOR_SETUP=1` is the same switch as an env var, which is the
+better fit for CI and sandboxes where no one is passing flags by hand. Either
+source disables setup; the flag never re-enables what the env var turned off.
+Neither is persisted to `config.yaml`: this is a per-run decision about your
+machine, not a property of the repo, so a later `init` without the flag
+registers normally.
+
---
## 8. REST API
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 2699a1a86..528126bff 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -93,6 +93,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr
| `--agents` / `--no-agents` | Generate or skip managed `AGENTS.md` for Codex. Persists the preference. |
| `--codex` / `--no-codex` | Generate or skip project-local Codex MCP/hooks setup. Interactive runs prompt when Codex CLI is installed and logged in; non-interactive runs require `--codex`. |
| `--distill-hook` / `--no-distill-hook` | Install or skip the Distill command-rewrite hook (Claude Code PreToolUse). Strictly opt-in: interactive runs prompt (default No); `--no-distill-hook` also gates the repo off in config so a globally installed hook stays inert here. In workspace mode the verdict applies to every selected repo. See [DISTILL.md](../agent/DISTILL.md). |
+| `--editor-setup` / `--no-editor-setup` | Register repowise in your machine-wide editor config: the Claude Code (`~/.claude/settings.json`) and Claude Desktop MCP server entry, plus the Claude Code PostToolUse/SessionStart hooks. Default: on. `--no-editor-setup` indexes the repo without touching anything outside it, which is what you want for a scratch checkout, a throwaway venv, or a CI run: each config holds a single `repowise` MCP key, so a second `init` repoints it at the newest repo instead of adding a second entry. It also skips the `--distill-hook` offer, which installs a user-level hook, though `--no-distill-hook` still records its opt-out in this repo's config. Project-local files are unaffected. `REPOWISE_SKIP_EDITOR_SETUP=1` is the same switch for CI and sandboxes, and it wins: with it set, an explicit `--editor-setup` does not turn registration back on. |
| `--seed-from` | Seed the index from an explicit base checkout instead of the auto-detected one. Rarely needed: inside a linked git worktree the base is detected and seeded automatically. See [WORKTREES.md](../scale/WORKTREES.md). |
| `--no-seed` | Disable worktree auto-seeding and run a full init even inside a linked worktree. |
| `--yes` / `-y` | Skip confirmation prompts |
@@ -117,6 +118,7 @@ repowise init --language zh # wiki docs in Chinese
repowise init -x vendor/ -x "*.gen.go" # exclude patterns
repowise init --include-submodules # include submodules
repowise init --no-codex --no-agents # skip Codex project files
+repowise init --no-editor-setup --yes # index only, leave global MCP config alone
repowise init . # workspace mode
repowise init . --no-prose -x "node_modules/" # workspace, no LLM
repowise init . --no-workspace # force single-repo, even in a workspace root
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index ca799d660..5f654556c 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -528,7 +528,7 @@ Anonymous usage telemetry is **enabled by default** (opt-out).
| Variable | Description |
|----------|-------------|
| `REPOWISE_GIT_WINDOW_ANCHOR` | Set to `head` to anchor git "now" to the latest commit instead of wall-clock time |
-| `REPOWISE_SKIP_EDITOR_SETUP` | Skip the interactive editor/MCP setup step |
+| `REPOWISE_SKIP_EDITOR_SETUP` | Truthy value stops `init` writing to your machine-wide editor config: the Claude Code / Claude Desktop MCP entry, the Claude Code hooks, and the distill rewrite-hook offer. Same switch as `init --no-editor-setup` ([CLI_REFERENCE.md](CLI_REFERENCE.md#repowise-init-path)); the env var is the one to use for CI, sandboxes, and benchmark runs that index many repos. Project-local files (`.repowise/mcp.json`, `CLAUDE.md`, Codex config) are written either way |
| `REPOWISE_CHANGELOG` | Override the changelog source used by the "what's new" check |
---
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py b/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py
index f44b40589..c65e9fbe9 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py
@@ -15,6 +15,7 @@ def offer_distill_rewrite_hook(
flag: bool | None,
*,
yes: bool = False,
+ no_editor_setup: bool = False,
) -> None:
"""Opt-in install of the distill command-rewrite hook (Claude Code).
@@ -33,18 +34,30 @@ def offer_distill_rewrite_hook(
selected repo for the workspace flow. Recording the verdict everywhere
matters because the hook treats any repo with ``.repowise/`` and no
config as enabled (with the ``ask`` posture).
+
+ Installing the hook writes user-level config, so ``--no-editor-setup`` (or
+ the equivalent env var) suppresses both the install and the prompt. An
+ explicit ``--no-distill-hook`` still records its opt-out: that record is
+ repo-local, and it is the only thing that gates an already-installed global
+ hook off *here*, so dropping it would leave the hook rewriting commands in
+ a repo the user just opted out of.
"""
- import os
+ from repowise.cli.editor_setup import is_editor_setup_disabled
if not repo_paths:
return
- if os.environ.get("REPOWISE_SKIP_EDITOR_SETUP", "").strip().lower() not in (
- "",
- "0",
- "false",
- "no",
- ):
+
+ if is_editor_setup_disabled(no_editor_setup):
+ if flag:
+ console_obj.print(
+ " [dim]Rewrite hook not installed: editor setup is off for this "
+ "run. Run 'repowise hook rewrite install' to set it up.[/dim]"
+ )
+ elif flag is False:
+ _record_distill_verdict(console_obj, repo_paths, enabled=False)
+ # `flag is None` decided nothing, so it writes nothing.
return
+
# --yes with an undecided flag: skip the interactive prompt entirely.
if flag is None and yes:
return
@@ -52,7 +65,6 @@ def offer_distill_rewrite_hook(
return
from repowise.cli.agent_adapters.claude_code import ClaudeCodeAdapter
- from repowise.cli.helpers import save_distill_commands_enabled as _save_distill_enabled
adapter = ClaudeCodeAdapter()
if flag is None:
@@ -90,9 +102,22 @@ def offer_distill_rewrite_hook(
" [dim]Skipped. Run 'repowise hook rewrite install' later to set up.[/dim]"
)
+ _record_distill_verdict(console_obj, repo_paths, enabled=bool(flag))
+
+
+def _record_distill_verdict(
+ console_obj: Any,
+ repo_paths: list[Path],
+ *,
+ enabled: bool,
+) -> None:
+ """Persist ``distill.commands.enabled`` for every repo in this run."""
+
+ from repowise.cli.helpers import save_distill_commands_enabled
+
for repo_path in repo_paths:
try:
- _save_distill_enabled(repo_path, enabled=bool(flag))
+ save_distill_commands_enabled(repo_path, enabled=enabled)
except Exception as exc: # init must not crash on a config write
console_obj.print(
f" [yellow]Could not record distill verdict for {repo_path.name}: {exc}[/yellow]"
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index b2af374c7..ca6767a07 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -505,6 +505,22 @@ def _run_generation_phase(
"In workspace mode the verdict applies to every selected repo."
),
)
+ "--editor-setup/--no-editor-setup",
+ "editor_setup",
+ default=True,
+ help=(
+ "Register repowise with your machine-wide editor config: the Claude "
+ "Code / Claude Desktop MCP server entry, the Claude Code hooks, and "
+ "the distill rewrite-hook offer. Default: on. Use --no-editor-setup to "
+ "index a repo without touching anything outside it — there is one "
+ "global 'repowise' MCP key, so a second init would otherwise repoint "
+ "it at this repo. Project-local files are unaffected (see "
+ "--no-claude-md, --no-codex). REPOWISE_SKIP_EDITOR_SETUP=1 does the "
+ "same thing for CI and sandboxes, and wins: with it set, --editor-setup "
+ "does not turn registration back on."
+ ),
+)
@click.option(
"--include-submodules",
is_flag=True,
@@ -664,6 +680,7 @@ def init_command(
agents_md: bool | None,
codex_setup: bool | None,
distill_hook: bool | None,
+ editor_setup: bool,
include_submodules: bool,
no_workspace: bool,
init_all: bool,
@@ -807,6 +824,7 @@ def init_command(
agents_md=agents_md,
codex_setup=codex_setup,
distill_hook=distill_hook,
+ editor_setup=editor_setup,
include_submodules=include_submodules,
provider_name=provider_name,
model=model,
@@ -1426,7 +1444,7 @@ def init_command(
repo_path,
options=editor_options,
)
- register_editor_clients(console, repo_path)
+ register_editor_clients(console, repo_path, no_editor_setup=not editor_setup)
# Inherit the workspace's distill rewrite-hook verdict NOW, before the
# config fingerprint below is computed. `repowise update` runs the same
@@ -1531,7 +1549,13 @@ def init_command(
# Opt-in distill command-rewrite hook for Claude Code. The workspace flow
# runs its own offer across all selected repos inside _workspace_init.
- offer_distill_rewrite_hook(console, [repo_path], distill_hook, yes=yes)
+ offer_distill_rewrite_hook(
+ console,
+ [repo_path],
+ distill_hook,
+ yes=yes,
+ no_editor_setup=not editor_setup,
+ )
# ---- Completion panel (last, so it reflects what setup actually did) ----
# Snapshot the editor-setup state now that client registration and the two
@@ -1544,6 +1568,7 @@ def init_command(
repo_path,
interactive=(sys.stdin.isatty() and not yes),
first_index=_first_index,
+ no_editor_setup=not editor_setup,
)
show_completion(
repo_path=repo_path,
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
index 831fd1016..7ca917101 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
@@ -537,6 +537,7 @@ def _workspace_init(
agents_md: bool | None,
codex_setup: bool | None,
distill_hook: bool | None,
+ editor_setup: bool,
include_submodules: bool,
# Generation params (passed through from init_command)
provider_name: str | None = None,
@@ -770,7 +771,7 @@ def _workspace_init(
primary_entry = ws_config.get_primary()
if primary_entry:
primary_path = (root / primary_entry.path).resolve()
- register_editor_clients(console, primary_path)
+ register_editor_clients(console, primary_path, no_editor_setup=not editor_setup)
# Step 7: Completion summary
elapsed = time.monotonic() - start
@@ -802,5 +803,11 @@ def _workspace_init(
# failed) because ensure_repowise_dir already created `.repowise/` in
# each, and the hook treats any repo with `.repowise/` and no recorded
# verdict as enabled — a decline must gate every one of them off.
- offer_distill_rewrite_hook(console, [r.path for r in selected], distill_hook, yes=yes)
+ offer_distill_rewrite_hook(
+ console,
+ [r.path for r in selected],
+ distill_hook,
+ yes=yes,
+ no_editor_setup=not editor_setup,
+ )
console.print()
diff --git a/packages/cli/src/repowise/cli/editor_integrations/claude.py b/packages/cli/src/repowise/cli/editor_integrations/claude.py
index 7571554f4..4aa7c4429 100644
--- a/packages/cli/src/repowise/cli/editor_integrations/claude.py
+++ b/packages/cli/src/repowise/cli/editor_integrations/claude.py
@@ -47,12 +47,19 @@ class ClaudeCodeSetup:
def register_client(self, console_obj: Any, repo_path: Path) -> None:
from repowise.cli.editor_integrations.claude_config import (
+ describe_mcp_registration_change,
enable_tool_search_in_claude_code,
install_claude_code_hooks,
register_with_claude_code,
register_with_claude_desktop,
)
+ # Read-only probe first: the merge below silently repoints the single
+ # global "repowise" entry, so say so before it happens.
+ clobber = describe_mcp_registration_change(repo_path)
+ if clobber:
+ console_obj.print(f" [yellow]![/yellow] {clobber}")
+
desktop = register_with_claude_desktop(repo_path)
if desktop:
console_obj.print(f" [green]✓[/green] Claude Desktop MCP registered ({desktop})")
diff --git a/packages/cli/src/repowise/cli/editor_integrations/claude_config.py b/packages/cli/src/repowise/cli/editor_integrations/claude_config.py
index e082d6f53..b861acf99 100644
--- a/packages/cli/src/repowise/cli/editor_integrations/claude_config.py
+++ b/packages/cli/src/repowise/cli/editor_integrations/claude_config.py
@@ -96,6 +96,77 @@ def register_with_claude_code(repo_path: Path) -> Path | None:
return settings_path if merge_mcp_entry(settings_path, entry) else None
+def _stored_repowise_entry(config_path: Path | None) -> dict | None:
+ """Read the current ``mcpServers.repowise`` entry, or None if absent."""
+ if config_path is None or not config_path.exists():
+ return None
+ try:
+ existing = load_existing_config(config_path)
+ except Exception:
+ # A config we can't parse is one registration will fail on anyway;
+ # the probe stays silent rather than guessing at what it holds.
+ return None
+ servers = existing.get("mcpServers")
+ if not isinstance(servers, dict):
+ return None
+ entry = servers.get("repowise")
+ return entry if isinstance(entry, dict) else None
+
+
+def _entry_repo_target(entry: dict) -> str | None:
+ """The repo path an existing MCP entry points at (``mcp <path> …``)."""
+ args = entry.get("args")
+ if not isinstance(args, list) or len(args) < 2:
+ return None
+ return str(args[1])
+
+
+def describe_mcp_registration_change(repo_path: Path) -> str | None:
+ """Warn when registering would repoint an existing ``repowise`` MCP entry.
+
+ Both Claude configs hold a single ``repowise`` key, so an ``init`` from a
+ second repo *replaces* the entry rather than adding one alongside it. That
+ write is silent, and only surfaces later when the binary or repo it points
+ at is gone and the MCP server stops loading. This is a read-only probe run
+ before registration; it returns a one-line notice when the stored command
+ or repo target differs from what is about to be written, else None.
+ """
+ new_entry = generate_mcp_config(
+ _resolve_mcp_target(repo_path), command=resolve_repowise_command()
+ )["mcpServers"]["repowise"]
+ new_command = new_entry.get("command")
+ new_target = _entry_repo_target(new_entry)
+
+ for config_path in (_claude_code_settings_path(), _claude_desktop_config_path()):
+ stored = _stored_repowise_entry(config_path)
+ if stored is None:
+ continue
+ # Both fields are reported when both move, which is the usual shape of
+ # the mistake: a second repo indexed by a second install. Naming only
+ # one would hide half of what is about to change.
+ changes = [
+ (label, was, now)
+ for label, was, now in (
+ ("repo", _entry_repo_target(stored), new_target),
+ ("command", stored.get("command"), new_command),
+ )
+ if was != now
+ ]
+ if not changes:
+ continue
+ fields = " and ".join(label for label, _was, _now in changes)
+ lines = [f"Replacing the existing repowise MCP {fields} in {config_path}:"]
+ for label, was, now in changes:
+ # A hand-edited entry can be missing either field outright.
+ lines.append(f" {label} was: {was if was is not None else '(not set)'}")
+ lines.append(f" {label} now: {now}")
+ lines.append(
+ " There is one 'repowise' entry per config; pass --no-editor-setup to leave it alone."
+ )
+ return "\n".join(lines)
+ return None
+
+
def enable_tool_search_in_claude_code() -> Path | None:
"""Set ``env.ENABLE_TOOL_SEARCH=true`` in ~/.claude/settings.json.
diff --git a/packages/cli/src/repowise/cli/editor_setup.py b/packages/cli/src/repowise/cli/editor_setup.py
index d9b4a0e1a..10bedf178 100644
--- a/packages/cli/src/repowise/cli/editor_setup.py
+++ b/packages/cli/src/repowise/cli/editor_setup.py
@@ -19,10 +19,25 @@ from typing import Any, Protocol
# Intended for headless / CI / benchmark indexing, where indexing many repos —
# or transient git worktrees — must not mutate the developer's global config or
# repoint the single global "repowise" MCP entry at a path that will be deleted.
+# `init --no-editor-setup` is the interactive spelling of the same switch.
_SKIP_EDITOR_SETUP_ENV = "REPOWISE_SKIP_EDITOR_SETUP"
-def _editor_setup_disabled() -> bool:
+def is_editor_setup_disabled(no_editor_setup: bool = False) -> bool:
+ """Whether global editor registration should be skipped for this run.
+
+ Disabled when ``init --no-editor-setup`` was passed *or* the
+ ``REPOWISE_SKIP_EDITOR_SETUP`` env var is set to anything but an explicit
+ off value. The flag never re-enables what the env var turned off. It is
+ per-run and never persisted to config, so a later ``init`` without it
+ registers normally.
+
+ Named with the ``is_`` prefix to stay distinct from
+ :attr:`EditorSetupOutcome.editor_setup_disabled`, which records the same
+ fact for one finished run.
+ """
+ if no_editor_setup:
+ return True
return os.environ.get(_SKIP_EDITOR_SETUP_ENV, "").strip().lower() not in (
"",
"0",
@@ -42,7 +57,7 @@ class EditorSetupOutcome:
"""
#: repowise registered a Claude Code MCP entry this run (init always does,
- #: unless setup was skipped for a headless/CI run).
+ #: unless setup was skipped for a headless/CI run or by --no-editor-setup).
claude_code_connected: bool = False
#: the git post-commit auto-sync hook is present for this repo.
autosync_hook_installed: bool = False
@@ -53,7 +68,8 @@ class EditorSetupOutcome:
interactive: bool = False
#: no prior index existed before this run (first-time onboarding).
first_index: bool = True
- #: REPOWISE_SKIP_EDITOR_SETUP was set (CI/benchmark) — nothing was wired up.
+ #: editor setup was turned off for this run — via --no-editor-setup or the
+ #: REPOWISE_SKIP_EDITOR_SETUP env var (CI/benchmark) — so nothing was wired up.
editor_setup_disabled: bool = False
@@ -62,6 +78,7 @@ def detect_editor_setup_outcome(
*,
interactive: bool,
first_index: bool,
+ no_editor_setup: bool = False,
) -> EditorSetupOutcome:
"""Read the ground-truth editor-setup state for the completion panel.
@@ -69,7 +86,7 @@ def detect_editor_setup_outcome(
Every probe is a cheap local file read and is defensive: a failure degrades
to "not set up" rather than crashing ``init``.
"""
- disabled = _editor_setup_disabled()
+ disabled = is_editor_setup_disabled(no_editor_setup)
autosync = False
try:
@@ -244,11 +261,12 @@ def register_editor_clients(
console_obj: Any,
repo_path: Path,
*,
+ no_editor_setup: bool = False,
integrations: tuple[EditorSetupIntegration, ...] | None = None,
) -> None:
"""Register editor clients with repowise MCP and hooks where supported."""
- if _editor_setup_disabled():
+ if is_editor_setup_disabled(no_editor_setup):
return
for integration in _resolve_integrations(integrations):
integration.register_client(console_obj, repo_path)
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/README.md b/packages/core/src/repowise/core/ingestion/git_indexer/README.md
index 8fc6c4f0a..c137bf5ff 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/README.md
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/README.md
@@ -37,6 +37,7 @@ prior-defect window) is measured relative to a single reference "now":
`REPOWISE_SKIP_EDITOR_SETUP=1` is the companion guard that lets `init` index a
transient worktree without touching the developer's global editor config.
+`init --no-editor-setup` is the same switch as a flag, for one-off runs.
## Public API
diff --git a/packages/server/src/repowise/server/mcp_server/_failure_shield.py b/packages/server/src/repowise/server/mcp_server/_failure_shield.py
index 2da2d7341..63b243ece 100644
--- a/packages/server/src/repowise/server/mcp_server/_failure_shield.py
+++ b/packages/server/src/repowise/server/mcp_server/_failure_shield.py
@@ -36,8 +36,10 @@ def _shape_not_indexed() -> dict[str, Any]:
"remedy": (
"The user can build one by running 'repowise init --yes' in the "
"repo root. No API key is required: without one it renders the "
- "whole wiki from the code's structure. Indexing is the user's "
- "decision — suggest it once, do not run it yourself."
+ "whole wiki from the code's structure. Suggest --no-editor-setup "
+ "too if this is a scratch clone, fixture, or worktree, so init "
+ "leaves their global MCP config pointed where it is. Indexing is "
+ "the user's decision — suggest it once, do not run it yourself."
),
"guidance": (
"Until an index exists, every repowise tool will return this "
diff --git a/plugins/claude-code/DEVELOPER.md b/plugins/claude-code/DEVELOPER.md
index 7c86aba83..188dfdff2 100644
--- a/plugins/claude-code/DEVELOPER.md
+++ b/plugins/claude-code/DEVELOPER.md
@@ -98,6 +98,11 @@ If you change the bundled hook's command or matcher, keep it in step with the
installer in
`packages/cli/src/repowise/cli/editor_integrations/claude_config.py`.
+A user who runs `repowise init --no-editor-setup` (or sets
+`REPOWISE_SKIP_EDITOR_SETUP=1`) gets no hooks from the installer at all. The
+plugin's bundled copy still fires, which is the point: the plugin is how you get
+the enrichment without letting `init` write to your global settings.
+
## Local development
```bash
diff --git a/plugins/claude-code/commands/init.md b/plugins/claude-code/commands/init.md
index 45d9c43ef..a5a770df3 100644
--- a/plugins/claude-code/commands/init.md
+++ b/plugins/claude-code/commands/init.md
@@ -57,11 +57,11 @@ Skip provider selection entirely. Construct:
repowise init --no-prose --yes
```
-Jump to Step 5.
+Jump to Step 3b.
### If Full mode:
-Move to Step 4.
+Move to Step 3b, then Step 4.
### If "show me flags":
@@ -96,6 +96,13 @@ 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
@@ -111,6 +118,38 @@ Dry run:
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 this repo, and the user may want it pointed back.
+
+Then continue to Step 4 for the model-written wiki, or Step 5 otherwise.
+
## Step 4: Provider selection (model-written wiki only)
**Skip this entire step unless the user chose the model-written wiki.** A
@@ -179,6 +218,11 @@ After init completes successfully:
2. Run `repowise status` to show the summary
3. Tell the user:
- "Repowise has indexed your codebase. The MCP tools are now active — I can answer questions about your architecture, ownership, dependencies, and more."
+ **Only if you did not pass `--no-editor-setup`.** With that flag nothing was
+ registered, so say instead: "The index is built. I did not register it as
+ your global MCP server (this looked like a temporary checkout). The
+ repowise plugin's tools still work here; to make this the repo the MCP
+ server points at, re-run `repowise init` without `--no-editor-setup`."
- "Try asking me something like 'how does the auth module work?' or 'what depends on utils.py?'"
- "Run `/repowise:status` anytime to check the health of your index."
- "Run `/repowise:update` after making code changes to keep the wiki in sync."
diff --git a/plugins/claude-code/skills/codebase-exploration/SKILL.md b/plugins/claude-code/skills/codebase-exploration/SKILL.md
index d881421c3..fe7b623af 100644
--- a/plugins/claude-code/skills/codebase-exploration/SKILL.md
+++ b/plugins/claude-code/skills/codebase-exploration/SKILL.md
@@ -52,6 +52,9 @@ Otherwise the response is current — act on it.
## Error handling
- "No repositories found. Run 'repowise init' first." → suggest `/repowise:init`.
+ Add `--no-editor-setup` if this repo is a scratch clone, a fixture, or a
+ worktree: `init` otherwise repoints the user's single global `repowise` MCP
+ entry at it.
- `get_answer`/`search_codebase` come back empty → the repo may have a
template-rendered wiki. Fall back to `get_context` with explicit paths, and note
that model-written pages (`repowise generate`, or `/repowise:init` with an LLM
diff --git a/plugins/codex/skills/codebase-exploration/SKILL.md b/plugins/codex/skills/codebase-exploration/SKILL.md
index eb1984b74..d98ea1936 100644
--- a/plugins/codex/skills/codebase-exploration/SKILL.md
+++ b/plugins/codex/skills/codebase-exploration/SKILL.md
@@ -44,6 +44,10 @@ Otherwise the response is current — act on it.
## Error Handling
- If tools report that no repositories were found, suggest running `repowise init`.
+ Add `--no-editor-setup` if this repo is a scratch clone, a fixture, or a worktree:
+ `init` otherwise registers repowise in the user's machine-wide editor config, which
+ holds a single entry and so gets repointed at whichever repo was indexed last. The
+ Codex config this skill relies on is project-local and is written either way.
- If `get_answer`/`search_codebase` come back empty, the repository may have a
template-rendered wiki; fall back to `get_context` with specific paths, and note
that model-written pages (`repowise generate`, or `repowise init` with an LLM
diff --git a/tests/unit/cli/test_editor_setup.py b/tests/unit/cli/test_editor_setup.py
index 0b45607c6..fa068c6ab 100644
--- a/tests/unit/cli/test_editor_setup.py
+++ b/tests/unit/cli/test_editor_setup.py
@@ -69,6 +69,167 @@ def test_register_editor_clients_skipped_when_env_set(monkeypatch) -> None:
assert registered == [Path("repo")] # runs when unset
+def test_register_editor_clients_skipped_by_flag(monkeypatch) -> None:
+ """--no-editor-setup skips registration with the env var unset.
+
+ The flag is the interactive spelling of REPOWISE_SKIP_EDITOR_SETUP: a user
+ who wants "index this repo, don't touch my machine" should not have to know
+ about an env var.
+ """
+ from repowise.cli.editor_setup import register_editor_clients
+
+ registered: list[Path] = []
+
+ class FakeIntegration:
+ def configure_options(self, c: Any, o: Any) -> Any:
+ return o
+
+ def write_project_files(self, c: Any, p: Path, o: Any) -> None:
+ pass
+
+ def register_client(self, c: Any, p: Path) -> None:
+ registered.append(p)
+
+ def refresh_project_files(self, c: Any, p: Path, o: Any) -> None:
+ pass
+
+ integrations = (FakeIntegration(),)
+ monkeypatch.delenv("REPOWISE_SKIP_EDITOR_SETUP", raising=False)
+
+ register_editor_clients(
+ _silent_console(),
+ Path("repo"),
+ no_editor_setup=True,
+ integrations=integrations,
+ )
+ assert registered == []
+
+ # Default (flag off, env unset) still registers.
+ register_editor_clients(_silent_console(), Path("repo"), integrations=integrations)
+ assert registered == [Path("repo")]
+
+
+def test_editor_setup_disabled_resolves_flag_or_env(monkeypatch) -> None:
+ """Either source disables; neither leaves setup on."""
+ from repowise.cli.editor_setup import is_editor_setup_disabled
+
+ monkeypatch.delenv("REPOWISE_SKIP_EDITOR_SETUP", raising=False)
+ assert is_editor_setup_disabled() is False
+ assert is_editor_setup_disabled(True) is True
+
+ monkeypatch.setenv("REPOWISE_SKIP_EDITOR_SETUP", "1")
+ assert is_editor_setup_disabled() is True
+ # The flag never re-enables what the env var turned off.
+ assert is_editor_setup_disabled(False) is True
+
+ # Falsy env spellings leave setup on.
+ for value in ("", "0", "false", "no"):
+ monkeypatch.setenv("REPOWISE_SKIP_EDITOR_SETUP", value)
+ assert is_editor_setup_disabled() is False
+
+
+def _patch_distill_offer(monkeypatch: Any) -> tuple[list[str], list[bool]]:
+ """Stub the rewrite hook's user-level writes; return the two call logs.
+
+ ``install_rewrite_hook`` is stubbed rather than left live so that a
+ regression in the gate fails the assertion instead of installing a real
+ PreToolUse hook in the ~/.claude/settings.json of whoever runs pytest.
+ """
+ from repowise.cli.agent_adapters import claude_code as cc_module
+
+ installs: list[str] = []
+ verdicts: list[bool] = []
+
+ class _Adapter:
+ def detect(self) -> bool:
+ return True
+
+ def install_rewrite_hook(self) -> str:
+ installs.append("installed")
+ return "settings.json"
+
+ monkeypatch.setattr(cc_module, "ClaudeCodeAdapter", _Adapter)
+ monkeypatch.setattr(
+ "repowise.cli.helpers.save_distill_commands_enabled",
+ lambda _path, *, enabled: verdicts.append(enabled),
+ )
+ monkeypatch.delenv("REPOWISE_SKIP_EDITOR_SETUP", raising=False)
+ return installs, verdicts
+
+
+def test_distill_rewrite_install_skipped_by_flag(monkeypatch, tmp_path: Path) -> None:
+ """--no-editor-setup suppresses the install, which is user-level.
+
+ ``--distill-hook`` would otherwise install without prompting. Nothing is
+ recorded: with no hook installed there is nothing for a verdict to gate,
+ and "enabled" is already the posture of any repo with a `.repowise/`.
+ """
+ from repowise.cli.commands.init_cmd._interactive import offer_distill_rewrite_hook
+
+ installs, verdicts = _patch_distill_offer(monkeypatch)
+
+ console = _silent_console()
+ offer_distill_rewrite_hook(console, [tmp_path], True, yes=True, no_editor_setup=True)
+ assert installs == []
+ assert verdicts == []
+ # The user asked for the hook and did not get it; say so.
+ assert "not installed" in console.file.getvalue()
+
+
+def test_distill_optout_recorded_despite_no_editor_setup(monkeypatch, tmp_path: Path) -> None:
+ """--no-editor-setup must not swallow --no-distill-hook's opt-out record.
+
+ The verdict lives in this repo's config.yaml, and it is the only thing that
+ gates a *globally* installed rewrite hook off for this repo. Dropping the
+ write would leave the hook rewriting commands in a repo the user just
+ opted out of.
+ """
+ from repowise.cli.commands.init_cmd._interactive import offer_distill_rewrite_hook
+
+ installs, verdicts = _patch_distill_offer(monkeypatch)
+
+ offer_distill_rewrite_hook(
+ _silent_console(),
+ [tmp_path],
+ False,
+ yes=True,
+ no_editor_setup=True,
+ )
+ assert installs == []
+ assert verdicts == [False]
+
+
+def test_distill_offer_silent_when_undecided_and_setup_off(monkeypatch, tmp_path: Path) -> None:
+ """No flag plus no editor setup means nothing to install and nothing to ask."""
+ from repowise.cli.commands.init_cmd._interactive import offer_distill_rewrite_hook
+
+ installs, verdicts = _patch_distill_offer(monkeypatch)
+
+ offer_distill_rewrite_hook(
+ _silent_console(),
+ [tmp_path],
+ None,
+ no_editor_setup=True,
+ )
+ assert installs == []
+ assert verdicts == []
+
+
+def test_detect_editor_setup_outcome_flag_reports_disconnected(tmp_path: Path, monkeypatch) -> None:
+ """The completion panel reacts to the flag, not just the env var."""
+ from repowise.cli.editor_setup import detect_editor_setup_outcome
+
+ monkeypatch.delenv("REPOWISE_SKIP_EDITOR_SETUP", raising=False)
+ outcome = detect_editor_setup_outcome(
+ tmp_path,
+ interactive=False,
+ first_index=False,
+ no_editor_setup=True,
+ )
+ assert outcome.editor_setup_disabled is True
+ assert outcome.claude_code_connected is False
+
+
def test_detect_editor_setup_outcome_reads_ground_truth(
tmp_path: Path,
monkeypatch: Any,
@@ -295,6 +456,154 @@ def test_refresh_editor_project_files_delegates_to_integrations(tmp_path: Path)
assert calls == [("refresh", tmp_path, frozenset({"skip"}))]
+def _write_settings(path: Path, entry: dict) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps({"mcpServers": {"repowise": entry}}), encoding="utf-8")
+
+
+def test_describe_mcp_registration_change_warns_on_repoint(
+ tmp_path: Path,
+ monkeypatch: Any,
+) -> None:
+ """A second init from another repo replaces the single 'repowise' entry.
+
+ That write is silent and only surfaces later, when the repo or binary it
+ points at is gone. The probe names both sides before the merge happens.
+ """
+ settings = tmp_path / "home" / ".claude" / "settings.json"
+ other_repo = str((tmp_path / "other-repo").resolve()).replace("\\", "/")
+ _write_settings(
+ settings,
+ {"command": "repowise", "args": ["mcp", other_repo, "--transport", "stdio"]},
+ )
+
+ monkeypatch.setattr(claude_config, "_claude_code_settings_path", lambda: settings)
+ monkeypatch.setattr(claude_config, "_claude_desktop_config_path", lambda: None)
+ monkeypatch.setattr(claude_config, "resolve_repowise_command", lambda: "repowise")
+
+ this_repo = tmp_path / "this-repo"
+ this_repo.mkdir()
+ notice = claude_config.describe_mcp_registration_change(this_repo)
+
+ assert notice is not None
+ assert other_repo in notice
+ assert str(this_repo.resolve()).replace("\\", "/") in notice
+ assert "--no-editor-setup" in notice
+
+
+def test_describe_mcp_registration_change_silent_when_unchanged(
+ tmp_path: Path,
+ monkeypatch: Any,
+) -> None:
+ """Re-running init on the same repo is not a clobber and stays quiet."""
+ settings = tmp_path / "home" / ".claude" / "settings.json"
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ repo_arg = str(repo.resolve()).replace("\\", "/")
+ _write_settings(
+ settings,
+ {"command": "repowise", "args": ["mcp", repo_arg, "--transport", "stdio"]},
+ )
+
+ monkeypatch.setattr(claude_config, "_claude_code_settings_path", lambda: settings)
+ monkeypatch.setattr(claude_config, "_claude_desktop_config_path", lambda: None)
+ monkeypatch.setattr(claude_config, "resolve_repowise_command", lambda: "repowise")
+
+ assert claude_config.describe_mcp_registration_change(repo) is None
+
+
+def test_describe_mcp_registration_change_silent_on_first_run(
+ tmp_path: Path,
+ monkeypatch: Any,
+) -> None:
+ """No stored entry means nothing is being replaced."""
+ monkeypatch.setattr(
+ claude_config, "_claude_code_settings_path", lambda: tmp_path / "missing.json"
+ )
+ monkeypatch.setattr(claude_config, "_claude_desktop_config_path", lambda: None)
+ monkeypatch.setattr(claude_config, "resolve_repowise_command", lambda: "repowise")
+
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ assert claude_config.describe_mcp_registration_change(repo) is None
+
+
+def test_describe_mcp_registration_change_warns_on_command_repoint(
+ tmp_path: Path,
+ monkeypatch: Any,
+) -> None:
+ """Same repo, different binary — the release-smoke-test case."""
+ settings = tmp_path / "home" / ".claude" / "settings.json"
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ repo_arg = str(repo.resolve()).replace("\\", "/")
+ _write_settings(
+ settings,
+ {
+ "command": "C:/Users/dev/.venv/Scripts/repowise.exe",
+ "args": ["mcp", repo_arg, "--transport", "stdio"],
+ },
+ )
+
+ monkeypatch.setattr(claude_config, "_claude_code_settings_path", lambda: settings)
+ monkeypatch.setattr(claude_config, "_claude_desktop_config_path", lambda: None)
+ monkeypatch.setattr(
+ claude_config, "resolve_repowise_command", lambda: "C:/tmp/throwaway/repowise.exe"
+ )
+
+ notice = claude_config.describe_mcp_registration_change(repo)
+ assert notice is not None
+ assert "C:/Users/dev/.venv/Scripts/repowise.exe" in notice
+ assert "C:/tmp/throwaway/repowise.exe" in notice
+
+
+def test_describe_mcp_registration_change_reports_both_fields(
+ tmp_path: Path,
+ monkeypatch: Any,
+) -> None:
+ """A new repo indexed by a new install moves both fields; name both."""
+ settings = tmp_path / "home" / ".claude" / "settings.json"
+ other = str((tmp_path / "other").resolve()).replace("\\", "/")
+ _write_settings(
+ settings,
+ {"command": "old-repowise", "args": ["mcp", other, "--transport", "stdio"]},
+ )
+
+ monkeypatch.setattr(claude_config, "_claude_code_settings_path", lambda: settings)
+ monkeypatch.setattr(claude_config, "_claude_desktop_config_path", lambda: None)
+ monkeypatch.setattr(claude_config, "resolve_repowise_command", lambda: "new-repowise")
+
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ notice = claude_config.describe_mcp_registration_change(repo)
+
+ assert notice is not None
+ assert "repo and command" in notice
+ assert "old-repowise" in notice and "new-repowise" in notice
+ assert other in notice
+
+
+def test_describe_mcp_registration_change_handles_truncated_entry(
+ tmp_path: Path,
+ monkeypatch: Any,
+) -> None:
+ """A hand-edited entry with no args must not print 'was: None'."""
+ settings = tmp_path / "home" / ".claude" / "settings.json"
+ _write_settings(settings, {"command": "repowise", "args": ["mcp"]})
+
+ monkeypatch.setattr(claude_config, "_claude_code_settings_path", lambda: settings)
+ monkeypatch.setattr(claude_config, "_claude_desktop_config_path", lambda: None)
+ monkeypatch.setattr(claude_config, "resolve_repowise_command", lambda: "repowise")
+
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ notice = claude_config.describe_mcp_registration_change(repo)
+
+ assert notice is not None
+ assert "None" not in notice
+ assert "(not set)" in notice
+
+
def test_codex_project_setup_writes_project_config_hooks_and_agents(
tmp_path: Path,
monkeypatch: Any,
diff --git a/website/cli-reference.md b/website/cli-reference.md
index 361523088..8586c92f9 100644
--- a/website/cli-reference.md
+++ b/website/cli-reference.md
@@ -64,6 +64,8 @@ repowise init [PATH] [OPTIONS]
| `--no-claude-md` | flag | false | Skip generating `.claude/CLAUDE.md` |
| `--agents` / `--no-agents` | flag | config | Generate or skip managed `AGENTS.md` for Codex |
| `--codex` / `--no-codex` | flag | prompt/skip | Generate or skip project-local Codex MCP config and hooks |
+| `--distill-hook` / `--no-distill-hook` | flag | prompt/skip | Install or skip the Claude Code command-rewrite hook that routes noisy commands through `repowise distill` |
+| `--editor-setup` / `--no-editor-setup` | flag | true | Register the MCP server and hooks in your global Claude Code / Claude Desktop config. `--no-editor-setup` indexes the repo and leaves everything outside it untouched |
| `--yes` / `-y` | flag | false | Skip the cost confirmation prompt |
### Examples