uchebnick · uchebnick · Apr 26, 2026 · Apr 26, 2026
@@ -155,22 +155,25 @@ The first local `llama.cpp` run may download the default embedding model, fetch
 
 Each provider and model pair keeps its own active index snapshot. Rebuilding `openrouter/openai/text-embedding-3-small` does not replace the active `llama.cpp/embeddinggemma` snapshot until the new run finishes successfully.
 
-## MCP
+## MCP for Codex
 
-`unch` can run as a stdio MCP server for agents and editors:
+The recommended MCP setup is through the npm wrapper:
 
 ```bash
-unch start mcp
+npm install -g @uchebnick/unch
+unch codex install
 ```
 
-Configure MCP clients with command `unch`, arguments `start mcp`, and working directory set to the repository you want to search.
+Then restart Codex. The setup command registers the `unch` MCP server and installs the `unch` skill in `~/.codex/skills/unch/SKILL.md`.
 
-The server exposes:
+After restart, ask Codex a codebase question as usual. The skill tells Codex to use these MCP tools before broad file reads:
 
 - `workspace_status` to inspect the repository root, state directory, active provider/model, and index status
 - `search_code` to search indexed code symbols before opening many files
 - `index_repository` to build or refresh the index when needed
 
+Codex starts the stdio server for you with `unch start mcp`; you normally do not need to run that command by hand.
+
 ## What It Supports Today
 
 - Tree-sitter indexing for `Go`, `Rust`, `TypeScript`, `JavaScript`, and `Python`

@@ -7,7 +7,7 @@ latest stable release line and the current `main` branch.
 
 | Version | Supported |
 | --- | --- |
-| `v0.3.x` | Yes |
+| `v0.4.x` | Yes |
 | older releases | No |
 | `main` | Best effort |
 
@@ -51,4 +51,3 @@ This policy covers:
 
 Third-party services, GitHub-hosted infrastructure, and vulnerabilities in
 upstream dependencies may need to be reported upstream as well.
-
@@ -69,10 +69,11 @@ unch remote sync
 
 Use the command pages for the full flag reference and behavior notes.
 
-## Typical MCP flow
+## Typical MCP flow for Codex
 
 ```bash
-unch start mcp
+npm install -g @uchebnick/unch
+unch codex install
 ```
 
-Configure your MCP client with command `unch`, arguments `start mcp`, and working directory set to the repository root.
+Restart Codex after installation. Codex will start `unch start mcp` automatically through the registered MCP server and use the installed `unch` skill when code search helps.
@@ -1,36 +1,31 @@
 ---
 title: MCP
-description: Start the unch stdio MCP server for agents and editor integrations.
+description: Install and use unch MCP from Codex.
 ---
 
-## Usage
+## Codex setup
 
-```bash
-unch start mcp [flags]
-```
-
-From the repository root, the common case is:
+Install the npm wrapper and register unch with Codex:
 
 ```bash
-unch start mcp
+npm install -g @uchebnick/unch
+unch codex install
 ```
 
-MCP uses stdio, so stdout is reserved for protocol messages. Run this command as a child process from an MCP client rather than as an interactive terminal command.
+Then restart Codex.
 
-## Client configuration
+`unch codex install` does two things:
 
-Use:
+- registers the `unch` MCP server with Codex
+- writes the `unch` skill to `~/.codex/skills/unch/SKILL.md`
 
-- Name: `unch`
-- Command: `unch`
-- Arguments: `start`, `mcp`
-- Working directory: the repository you want to search
+The npm `postinstall` step does not modify Codex automatically. Run `unch codex install` explicitly when you want the integration.
+
+## How to use it
 
-The server uses:
+After restarting Codex, work in a repository and ask codebase questions normally. The installed skill tells Codex to call unch before broad file reads when semantic code search can help.
 
-- root: current working directory
-- state dir: `<root>/.semsearch`
-- provider/model: the same defaults as the CLI
+Codex starts the stdio MCP server for you. You normally do not need to run `unch start mcp` by hand.
 
 ## Tools
 
@@ -52,51 +47,19 @@ Builds or refreshes the index for the configured workspace.
 
 Agents should call this when no index exists, when search reports no active snapshot for the selected provider/model, or when the user explicitly asks to rebuild.
 
-## Flags
-
-### `--root`
-
-Repository root served by the MCP process. Defaults to `.`.
-
-### `--state-dir`
-
-Path to a custom `.semsearch` directory. Defaults to `<root>/.semsearch`.
-
-### `--model`
-
-Embedding model to use. Accepts `embeddinggemma`, `qwen3`, a `.gguf` path, or an OpenRouter model id when `--provider openrouter` is selected.
+## What Codex runs
 
-### `--provider`
+The registered MCP server uses:
 
-Embedding provider. Accepted values:
-
-- `llama.cpp`
-- `openrouter`
-
-### `--lib`
-
-Path to a `yzma` library directory, or one of its shared library files.
-
-### `--ctx-size`
-
-llama context size. `0` uses the selected model default.
-
-### `--verbose`
-
-Enable verbose `yzma` logging.
-
-## Examples
+- Name: `unch`
+- Command: `unch-mcp`
+- Arguments: none
 
-```bash
-unch start mcp
-unch start mcp --root ~/src/repo --state-dir ~/src/repo/.semsearch
-unch start mcp --root . --model qwen3
-unch start mcp --provider openrouter --model openai/text-embedding-3-small
-```
+`unch-mcp` is a small launcher for `unch start mcp`.
 
 ## Notes
 
-- Use one MCP process per repository workspace.
+- The installed skill passes the active repository directory into unch MCP tool calls.
 - The process reuses the same provider/model/runtime configuration across tool calls.
 - OpenRouter token lookup checks `OPENROUTER_API_KEY`, then `~/.config/unch/tokens.json`, then `.semsearch/tokens.json`.
 - The MCP server exposes tools only in this release; streamable HTTP is not supported yet.
@@ -22,18 +22,17 @@ Then restart Codex. The installer uses `codex mcp add` for the MCP server and wr
 
 The npm `postinstall` step does not modify your Codex config automatically. This is intentional: installing a package should not silently mutate `~/.codex/config.toml`.
 
-## MCP
+## MCP for Codex
 
-For MCP clients, use:
+Codex setup is explicit:
 
-- Name: `unch`
-- Command: `unch-mcp`
-- Arguments: leave empty
-- Working directory: the repository you want to search
+```bash
+unch codex install
+```
 
-`unch-mcp` is a small launcher for `unch start mcp`.
+Then restart Codex. Codex will start the MCP server through the registered `unch-mcp` command and use the installed `unch` skill when semantic code search helps.
 
-For Codex CLI specifically, `unch codex install` also creates a local reusable skill, so Codex knows when to call `workspace_status`, `search_code`, and `index_repository` in the right order.
+`unch-mcp` is a small launcher for `unch start mcp`; you normally do not need to run it by hand.
 
 Supported targets: