PatrickSys · Oct 16, 2026 · Oct 16, 2026
diff --git a/README.md b/README.md
@@ -4,28 +4,19 @@
 
 Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns. Search, examples and project memory run locally by default.
 
-## Set up your AI client
+## Set up your coding tools
 
 **These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
-Use Node.js 22 or newer. Choose your coding tool and run its command once; the examples target the 2.4.0 release:
+Automatic multi-tool setup is awaiting publication. The unpinned prompt below uses npm's latest release and will support this flow once these changes are released; until then, use the published setup guide above.
 
-```bash
-# Claude Code
-claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0
-
-# Codex CLI
-codex mcp add codebase-context -- npx -y codebase-context@2.4.0
-
-# OpenCode 1.x (keep the quoted separator on Windows)
-opencode mcp add codebase-context '--' npx -y codebase-context@2.4.0
-```
+Use Node.js 22 or newer. Copy this prompt to your coding agent:
 
-Start a new agent session in your project, then ask:
+> Set up Codebase Context for this repository and any other repositories I explicitly name. Read https://github.com/PatrickSys/codebase-context#readme and the installed init help. Detect my supported coding tools and configure all of them, using `npx --yes codebase-context init --yes` once per repository. Preserve existing settings and instructions; explain any conflicting entry you cannot safely preserve. Add only a short, relevant usage note where this repository keeps agent instructions. Pass each repository's actual directory with --root. Once available, call Codebase Context to find a real source symbol and open its returned file. Report what works; if a tool needs reopening or trust approval, give me that exact next step and do not claim it connected.
 
-> Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project, wait for indexing if needed, and open the relevant source files.
+To set up directly, run `npx --yes codebase-context@2.4.0 init` in your project. It shows Claude Code, Codex, Cursor and OpenCode together, with detected tools selected. Press Space to change the selection and Enter to apply it. With `--yes`, or without a terminal, it configures every detected tool. Use repeatable `--client` options to choose explicitly and `--root` to select another repository.
 
-Replace `[feature]` with something you want to find. The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model.
+Each tool starts its own local server when needed. Reopen the tools and approve the server or project trust if asked. The first search builds the repository's index; setup itself does not index or change agent instructions.
 
 ### New in 2.4.0
 
@@ -37,32 +28,7 @@ Known limits: [Intel Mac indexing crash (#68)](https://github.com/PatrickSys/cod
 
 The existing [benchmark](https://github.com/PatrickSys/codebase-context/blob/master/docs/benchmark.md) reports 25.7% expected-file recovery versus jCodeMunch's 27.1% in a fixed retrieval comparison; it does not establish a winner or coding quality.
 
-For Codex Desktop, create or merge `.codex/config.toml` in the project you want to search:
-
-```toml
-[mcp_servers.codebase-context]
-command = "npx"
-args = ["-y", "codebase-context@2.4.0"]
-startup_timeout_sec = 120
-```
-
-Trust the project if asked, restart Codex, and start a new task there. Use the prompt above. Config placement alone does not establish successful first use; this no-folder recipe has not been accepted in a fresh native Desktop task.
-
-Other clients use their own setup commands:
-
-| Client                      | Shortest current setup                                                       |
-| --------------------------- | ---------------------------------------------------------------------------- |
-| Gemini CLI                  | `gemini mcp add --scope user codebase-context npx -y codebase-context@2.4.0` |
-| Cursor                      | Add `.cursor/mcp.json`                                                       |
-| VS Code with GitHub Copilot | Add `.vscode/mcp.json`                                                       |
-| GitHub Copilot CLI          | `copilot mcp add codebase-context -- npx -y codebase-context@2.4.0` |
-| Windsurf                    | Add `~/.codeium/windsurf/mcp_config.json`                                    |
-
-Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration and the interactive setup wizard's limitations.
-
-The [client setup guide](./docs/client-setup.md) has the exact commands and config for every client, plus what was checked locally and what still relies on official instructions.
-
-The default connection is `stdio` (standard input/output): your client starts the server when it needs it. HTTP is an advanced, client-dependent option; verify the setup guide and client support before relying on it.
+The [client setup guide](./docs/client-setup.md) covers detection, reruns, manual recipes for Gemini, GitHub Copilot and Windsurf, and advanced HTTP configuration. Existing custom entries are preserved and reported as conflicts. Config placement alone does not prove a client connected.
 
 ## What your agent gets
 

diff --git a/docs/cli.md b/docs/cli.md
@@ -46,7 +46,7 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.4.0 patterns
 - `reindex` — rebuild index (full or incremental)
 - `style-guide` — find style guide sections in docs
 - `memory list|add|remove` — manage team memory (stored in `.codebase-context/memory.json`)
-- MCP client registration — use the 2.4.0 recipes in the [client setup guide](./client-setup.md); `init` is an interactive HTTP setup wizard with the limitations described there
+- MCP client registration — `init` detects Claude Code, Codex, Cursor and OpenCode and configures the selected tools together. Use `init --yes` for all detected tools, repeat `--client <name>` to choose tools, and pass `--root <path>` for another repository. See the [client setup guide](./client-setup.md).
 
 ---
 

diff --git a/docs/client-setup.md b/docs/client-setup.md
@@ -2,13 +2,33 @@
 
 **These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
-Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target the 2.4.0 release.
+Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Use `init` to configure your supported coding tools for a repository. Each tool starts its own server with that repository selected; the agent can still select another repository with the `project` tool parameter. These recipes target the 2.4.0 release.
 
 Use Node.js 22 or newer, as required by the package.
 
 The copyable registration commands target PowerShell or a POSIX terminal. Windows Command Prompt was not tested; OpenCode's quoted separator is shell-dependent.
 
-## Client recipes for 2.4.0
+## Set up your coding tools
+
+Automatic multi-tool setup is awaiting publication. These instructions describe the implementation in this repository; the README's unpinned prompt depends on a published release containing it.
+
+Run `npx --yes codebase-context@2.4.0 init` from your repository, or copy the agent prompt in the [README](../README.md#set-up-your-coding-tools).
+
+Setup shows Claude Code, Codex, Cursor and OpenCode together. It checks their executables on PATH and their known user/project directories, respecting `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `XDG_CONFIG_HOME`. It does not read credentials or run tools to detect them. Detected tools start checked; Space toggles a choice and Enter configures the selected tools once. Cancel leaves files unchanged.
+
+With `--yes`, or without terminal input/output, setup configures every detected tool. If none is found, it writes nothing and asks you to select tools explicitly:
+
+```bash
+npx --yes codebase-context@2.4.0 init --client claude-code --client codex --root /path/to/repository --yes
+```
+
+`--root` takes priority over `CODEBASE_ROOT` and the current directory. Claude Code writes `.mcp.json`, Codex `.codex/config.toml`, Cursor `.cursor/mcp.json`, and OpenCode `opencode.json` inside that repository. All four start local servers with a version-pinned `npx` command; setup does not start a daemon or depend on the installer's cache location.
+
+Rerun the same command after moving a repository or updating the package. Identical entries stay unchanged. Setup updates recognized generated launch/root fields and preserves other settings. Custom or HTTP entries are left intact and reported as conflicts; all selected configs are checked before any are written. Resolve a conflict explicitly rather than removing unrelated settings.
+
+Reopen your tools and approve project trust or the server if asked. The first search builds the index. Setup writes MCP configs only; repository instructions belong to your agent and the README prompt. A successful setup exit does not by itself prove a client connected.
+
+## Manual client recipes for 2.4.0
 
 Claude Code, Codex CLI and OpenCode registration commands were checked again on October 6 without a project argument. The other clients retain their older config-shape evidence; no-folder native agent use is unverified for them. See the dated notes below.
 
@@ -75,7 +95,7 @@ Equivalent project config:
 [mcp_servers.codebase-context]
 command = "npx"
 args = ["-y", "codebase-context@2.4.0"]
-startup_timeout_sec = 120
+startup_timeout_sec = 300
 ```
 
 **What was checked:** The command ran with an isolated `CODEX_HOME`, wrote `config.toml`, and `codex mcp get` returned the same command and arguments.
@@ -92,7 +112,7 @@ Create or merge `.codex/config.toml` in the project you want to search. Preserve
 [mcp_servers.codebase-context]
 command = "npx"
 args = ["-y", "codebase-context@2.4.0"]
-startup_timeout_sec = 120
+startup_timeout_sec = 300
 ```
 
 Trust the project if asked, restart Codex and start a new task there. Use the first-use prompt above so the agent selects the current repository. The CLI command in the preceding section writes user-level config; this recipe uses a trusted project's config instead.
@@ -101,24 +121,6 @@ Trust the project if asked, restart Codex and start a new task there. Use the fi
 
 On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a folder, environment root or MCP roots, launched from an unrelated directory. That check does not verify the `2.4.0` package. Its first tool call returned `selection_required`; an explicit `project` call selected the prepared fixture, search found the expected symbol, context returned its map, and the runner host opened the returned source. A later call without `project` retained that selection. This is SDK/protocol and runner-host evidence with warmed caches and a pre-indexed fixture, not a native Desktop task.
 
-## Interactive setup wizard
-
-Run setup from the project you want the client to search:
-
-```bash
-# Claude Code
-npx -y codebase-context@2.4.0 init --client claude-code --yes
-
-# Codex
-npx -y codebase-context@2.4.0 init --client codex --yes
-```
-
-Claude Code writes `.mcp.json`; Codex writes `.codex/config.toml`. Both configs start the installed server with the selected project. Setup uses the current folder unless `--root` or `CODEBASE_ROOT` selects another one; `--root` takes priority.
-
-`--yes` writes the config without prompts. Run `init` without flags to choose a client interactively and optionally add project instructions. Cursor and OpenCode still use HTTP and need a separately running server.
-
-Existing settings are kept. If a different Codebase Context entry is already present, setup leaves the file unchanged and reports the conflict. Restart the client after setup and approve the server if asked. The first use builds the code index. Rerun setup if the Codebase Context installation moves, because the config uses its installed location.
-
 ## Optional fixed-folder setup and CLI preparation
 
 To set a default project before the first tool call, append its full path to the server arguments, for example `args = ["-y", "codebase-context@2.4.0", "C:/projects/my-app"]`. Use a quoted literal shell argument in registration commands. This makes the default fixed across repositories when the registration is user-scoped; explicit tool selection can still choose another allowed project.
@@ -129,8 +131,6 @@ To prepare the index separately, run from the project folder:
 npx -y codebase-context@2.4.0 reindex
 ```
 
-The interactive wizard limitations described above are still present in the 2.4.0 source. A successful wizard exit alone does not establish working client registration.
-
 ## Gemini CLI
 
 **Status:** Config written locally