@rynfar/meridian 1.54.0 → 1.55.0

package/README.md

@@ -49,106 +49,7 @@ ANTHROPIC_API_KEY=x ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
 
 The API key value is a placeholder — Meridian authenticates through the Claude Code SDK, not API keys. Most Anthropic-compatible tools require this field to be set, but any value works.
 
-### NixOS / Nix Flake
-
-Meridian provides a Nix flake for declarative installation.
-
-**Add to your flake inputs:**
-
-```nix
-{
-  inputs.meridian.url = "github:rynfar/meridian";
-}
-```
-
-**Install the package** (via overlay or directly):
-
-```nix
-# Option A: overlay
-nixpkgs.overlays = [ meridian.overlays.default ];
-environment.systemPackages = [ pkgs.meridian ];
-
-# Option B: direct reference
-environment.systemPackages = [ meridian.packages.${system}.meridian ];
-```
-
-**OpenCode plugin** -- the plugin file is included at `${pkgs.meridian}/lib/meridian/plugin/meridian.ts`. Since this path lives in the Nix store, you need to make it available to OpenCode:
-
-If you generate your OpenCode config from Nix (e.g. via Home Manager), interpolate the path directly:
-
-```nix
-# home-manager example
-xdg.configFile."opencode/opencode.json".text = builtins.toJSON {
-  plugin = [ "${pkgs.meridian}/lib/meridian/plugin/meridian.ts" ];
-};
-```
-
-If you don't manage your OpenCode config through Nix, symlink the plugin to a stable path and reference that instead:
-
-```nix
-# configuration.nix or home-manager
-environment.etc."meridian/plugin/meridian.ts".source =
-  "${pkgs.meridian}/lib/meridian/plugin/meridian.ts";
-```
-
-Then in `~/.config/opencode/opencode.json`:
-
-```json
-{ "plugin": ["/etc/meridian/plugin/meridian.ts"] }
-```
-
-> **Important:** Do not use `meridian setup` on NixOS. It writes an absolute Nix store path (e.g. `/nix/store/...-meridian-1.x.x/lib/...`) into your OpenCode config, which will break on the next `nixos-rebuild switch` or `home-manager switch` when the store path changes. Use one of the approaches above instead.
-
-> **Note:** Meridian's package depends on the unfree `claude-code` from nixpkgs instead of bundling its own binary. The flake accepts the unfree license when it builds the package and exports the finished derivation, so consuming it through the overlay or `packages.<system>.meridian` does not re-run nixpkgs' unfree check and needs no `allowUnfree` setting.
-
-**Home Manager service** -- run Meridian as a user systemd service:
-
-```nix
-# flake.nix
-{
-  inputs.meridian.url = "github:rynfar/meridian";
-}
-
-# home-manager config
-{
-  imports = [ meridian.homeModules.default ];
-
-  services.meridian = {
-    enable = true;
-    settings = {
-      port = 3456;
-      host = "127.0.0.1";
-      # passthrough = true;
-      # defaultAgent = "opencode";
-      # sonnetModel = "sonnet";
-      # Load plugins from the Nix store (rendered to a plugins.json manifest).
-      # The official scrub plugins ship prebuilt via the meridian overlay:
-      # pluginConfig = [ { path = pkgs.meridianPlugins.opencode-scrub.path; } ];
-      # pluginDir = "/path/to/extra/plugins";
-    };
-    # Extra env vars not covered by settings
-    # environment = {
-    #   MERIDIAN_MAX_CONCURRENT = "20";
-    # };
-  };
-}
-```
-
-The service starts automatically on login. Manage it with `systemctl --user {start,stop,restart,status} meridian`.
-
-The module manages only the systemd user service — it does **not** put the `meridian` CLI on your `$PATH`. If you also want to run `meridian` from a shell, add the package yourself:
-
-```nix
-home.packages = [ config.services.meridian.package ];
-```
-
-The plugin path is also available as `config.services.meridian.opencode.pluginPath` for use in your OpenCode config:
-
-```nix
-xdg.configFile."opencode/opencode.json".text = builtins.toJSON {
-  plugin = [ config.services.meridian.opencode.pluginPath ];
-};
-```
+Using a different agent, NixOS, or Docker? See the [documentation](#documentation) below.
 
 ## Why Meridian?
 
@@ -158,6 +59,19 @@ The Claude Agent SDK provides programmatic access to Claude. But your favorite c
   <img src="assets/how-it-works.svg" alt="How Meridian works" width="920"/>
 </p>
 
+## Documentation
+
+| Guide | What's in it |
+|-------|--------------|
+| [Agent Setup](docs/agents.md) | Per-agent config: OpenCode, Crush, Droid, Cline, Aider, Codex CLI, Open WebUI, Cherry Studio, ForgeCode, Pi, Claude Code, Claude Design MCP, adapter instances |
+| [Configuration](docs/configuration.md) | Environment variables, endpoints, API key auth, SDK feature toggles, passthrough mode, CLI commands |
+| [Multi-Profile Support](docs/profiles.md) | Multiple Claude accounts, headless login, sticky session routing |
+| [Deployment](docs/deployment.md) | NixOS / Nix flake, Home Manager service, Docker |
+| [Plugins](docs/plugins.md) | Plugin system and the official scrub plugins |
+| [Development](docs/development.md) | Architecture overview, testing, programmatic API |
+| [`MONITORING.md`](MONITORING.md) | Telemetry, token usage, and prompt cache health |
+| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Module map and dependency rules |
+
 ## Features
 
 - **Standard Anthropic API** — drop-in compatible with any tool that supports a custom `base_url`
@@ -169,8 +83,8 @@ The Claude Agent SDK provides programmatic access to Claude. But your favorite c
 - **Auto token refresh** — expired OAuth tokens are refreshed automatically; requests continue without interruption
 - **Passthrough mode** — forward tool calls to the client instead of executing internally
 - **Multimodal** — images, documents, file attachments, and multimodal tool results pass through to Claude
-- **Multi-profile** — switch between Claude accounts instantly, no restart needed; opt-in [sticky session routing](#sticky-session-routing) distributes sessions across accounts while keeping per-account prompt caches warm
-- **Adapter instances** — run several configurations of the same adapter side by side (per-instance thinking, system prompt, passthrough) selected by header or match rules — see [Adapter instances](#adapter-instances)
+- **Multi-profile** — switch between Claude accounts instantly, no restart needed; opt-in [sticky session routing](docs/profiles.md#sticky-session-routing) distributes sessions across accounts while keeping per-account prompt caches warm
+- **Adapter instances** — run several configurations of the same adapter side by side (per-instance thinking, system prompt, passthrough) selected by header or match rules — see [Adapter instances](docs/agents.md#adapter-instances)
 - **Telemetry dashboard** — real-time performance metrics at `/telemetry`, including token usage and prompt cache efficiency ([`MONITORING.md`](MONITORING.md))
 - **Cost estimation** — estimated API-equivalent value of your traffic, per model and per profile, using current list prices with configurable overrides (`~/.config/meridian/model-pricing.json`, editable at `/settings`)
 - **Envelope integrity auditing** — Meridian validates its own wire output on every response (no dangling blocks, no undelivered or empty tool calls) and surfaces violations on the dashboard
@@ -178,882 +92,25 @@ The Claude Agent SDK provides programmatic access to Claude. But your favorite c
 - **Prometheus metrics** — `GET /metrics` endpoint for scraping request counters and duration histograms
 - **SDK feature toggles** *(experimental)* — unlock Claude Code features (memory, dreaming, CLAUDE.md) for any connected agent
 
-## SDK Feature Toggles (Experimental)
-
-Meridian can expose Claude Code features to any connected agent. Capabilities like auto-memory, dreaming, and CLAUDE.md — normally exclusive to Claude Code — become available to OpenCode, Crush, Droid, and any other harness routed through Meridian. Each agent keeps its own toolchain while gaining access to these additional features.
-
-Configure per-adapter at **`/settings`** in the Meridian web UI. Changes take effect on the next request — no restart needed. Config is persisted to `~/.config/meridian/sdk-features.json`.
-
-### Available features
-
-| Setting | Options | Description |
-|---|---|---|
-| **Claude Code Prompt** | on / off | Include the SDK's built-in system prompt (tool usage rules, safety guidelines, coding best practices) |
-| **Client Prompt** | on / off | Include the system prompt sent by the connecting agent (e.g. OpenCode or Crush instructions) |
-| **CLAUDE.md** | off / project / full | Load instruction files — `off`: none, `project`: `./CLAUDE.md` only, `full`: `~/.claude/CLAUDE.md` + `./CLAUDE.md` |
-| **Memory** | on / off | Auto-memory: read and write memories across sessions |
-| **Auto-Dream** | on / off | Background memory consolidation between sessions |
-| **Thinking** | disabled / adaptive / enabled | Extended thinking mode for complex reasoning |
-| **Thinking Passthrough** | on / off | Forward thinking blocks to the client for display |
-| **Shared Memory** | on / off | Share memory directory with Claude Code (`~/.claude`) instead of isolated storage |
-
-### System prompts
-
-The system prompt controls are independent — any combination works:
-
-- **Both enabled** (recommended): Claude Code instructions come first, followed by your agent's specific instructions. This gives Claude the full context it needs for features like memory and tool use to work correctly.
-- **Claude Code only**: Just the base Claude Code prompt without agent-specific instructions.
-- **Client only**: Just your agent's prompt, passed through as a raw string.
-- **Neither**: No system prompt at all — Claude operates with just the user message.
-
-> **Note:** For features like memory and dreaming to work well, the Claude Code system prompt should be enabled — it contains the instructions Claude needs to read and write memories correctly.
-
-## Passthrough Mode and Tool Calling
-
-The core question is **who executes the tools** — the SDK or the client?
-
-- **Passthrough mode** (default for OpenCode and Pi) — Claude generates tool calls, but Meridian captures them and sends them back to the client for execution. The client runs the tool using its own implementation, with its own sandboxing, file tracking, and UI, then sends the result in the next request. This is how OpenCode, oh-my-opencagent (OMO), and most coding agents work — they have their own read/write/bash tools and need to stay in control of what runs on the user's machine.
-- **Internal mode** — Claude Code handles everything. The SDK executes tools directly on the host, runs its full agent loop, and returns the final result. This is for clients that are purely chat interfaces (Open WebUI, simple API consumers) with no tool execution of their own.
-
-Most users don't need to configure anything — the adapter sets the right mode automatically. To override:
-
-```bash
-MERIDIAN_PASSTHROUGH=1 meridian   # force passthrough
-MERIDIAN_PASSTHROUGH=0 meridian   # force internal
-```
-
-### How tool calling works in passthrough
-
-1. The client sends a request with tool definitions (read, write, edit, bash, glob, grep)
-2. Meridian registers these as MCP tools so the SDK can generate proper `tool_use` blocks
-3. The SDK produces a tool call → Meridian captures it and returns it to the client
-4. The client executes the tool locally and sends the result back
-
-For large tool sets (>15 tools), non-core tools are automatically deferred via the SDK's ToolSearch mechanism. Core tools (read, write, edit, bash, glob, grep) are always loaded eagerly. The deferral threshold is configurable with `MERIDIAN_DEFER_TOOL_THRESHOLD`.
-
-**Digest-turn elimination** — after a tool call is captured, the SDK would normally invoke the model one more time to "digest" the denial before ending the turn. That extra invocation is discarded by the proxy but fully billed — measured at ~400+ wasted output tokens and 2–3× extra latency per tool step (and on always-thinking models like Fable, a full thinking pass each time). Meridian now aborts the SDK query the moment every tool call's denial is persisted, so the digest turn never generates. Sessions remain resumable and tool-result attribution is unaffected. Kill switch: `MERIDIAN_PASSTHROUGH_EARLY_STOP=0` restores the old behavior.
-
-### Known limitations
-
-- **Single tool round-trip per request** — in passthrough mode, the SDK is configured with `maxTurns=3` (or 4 for deferred tools). Multi-step agentic loops where Claude needs several consecutive tool calls require the client to re-send after each round.
-- **Blocked tools** — 10 built-in SDK tools (Read, Write, Bash, etc.) are blocked to prevent conflicts with the client's own tools. 19 additional Claude Code-only tools (CronCreate, EnterWorktree, Agent, etc.) are blocked because they require capabilities that external clients don't support.
-- **Subagent extraction** — Meridian parses the client's Task tool description to extract subagent names and build SDK AgentDefinitions. If the client's agent framework uses a non-standard format, subagent routing may not work automatically.
-- **Scratchpad suppression (passthrough)** — the Claude CLI advertises a proxy-host scratchpad directory that clients can't use; OpenCode 1.18+ permission-blocks writes to it. Meridian suppresses it in passthrough mode (`CLAUDE_CODE_SESSION_KIND=bg` on the subprocess). Kill switch: `MERIDIAN_SUPPRESS_SCRATCHPAD=0`.
-- **Anthropic server tools not supported** — native server-side tools (`web_search_*`, `web_fetch_*`) are a raw Anthropic API feature (billed to an API key) that emits `server_tool_use` / `web_search_tool_result` blocks the Claude Max / Agent SDK path cannot produce. A request carrying one is rejected with a `400` explaining the fix. If a plugin needs server-side web search (e.g. [`opencode-websearch`](https://github.com/emilsvennesson/opencode-websearch)), give it its **own** provider pointed at `https://api.anthropic.com` with your `ANTHROPIC_API_KEY` — don't route that call through Meridian.
-
-### Troubleshooting: "aborted" tool calls
-
-Two very different things can carry the word "abort" — one is normal, one is always a bug:
-
-- **Normal (invisible):** Meridian intentionally stops its internal SDK subprocess after your tool calls are captured — this is the optimization that avoids a wasted, billed model turn per tool call. It never appears in your client; log lines like `passthrough.early_stop` or `sdk_termination reason=aborted` in Meridian's own logs are calm, expected bookkeeping.
-- **A bug (report it):** an **empty tool call in your client UI** — `tool {}` with "Tool execution aborted" — is never expected behavior, on any version. It means a call was cut off in transit.
-
-**The definitive check:** the `/telemetry` dashboard's **Envelope** card. Meridian audits its own output on every response — green "wire contract clean" means every tool call was delivered intact regardless of what internal logs say. If it shows red, the logs contain `ENVELOPE VIOLATION` lines with request IDs — include those in a bug report and it can usually be root-caused directly.
-
-## Multi-Profile Support
-
-Meridian can route requests to different Claude accounts. Each **profile** is a named auth context — a separate Claude login with its own OAuth tokens. Switch between personal and work accounts, or share a single Meridian instance across teams.
-
-### Adding profiles
-
-```bash
-# Add your personal account
-meridian profile add personal
-# → Opens browser for Claude login
-
-# Add your work account (sign out of claude.ai first, then sign into the work account)
-meridian profile add work
-```
-
-> **⚠ Important:** Claude's OAuth reuses your browser session. Before adding a second account, sign out of claude.ai and sign into the other account first.
-
-#### Headless / SSH: complete Claude OAuth with a pasted code
-
-When you still want a normal Claude Max browser-login profile but the Meridian host cannot open a browser (SSH, WSL, containers, remote servers), use `--headless`. Meridian prints a Claude OAuth URL, prompts for the returned code, exchanges it with PKCE, and saves the resulting credentials into the profile's isolated `CLAUDE_CONFIG_DIR`:
-
-```bash
-meridian profile add work --headless
-```
-
-Open the printed URL in a browser, sign in to the target Claude account, then paste the returned code at Meridian's `Paste code:` prompt. For an existing browser-login profile:
-
-```bash
-meridian profile login work --headless
-```
-
-#### Headless / CI: register an OAuth token
-
-When a browser isn't available (containers, CI runners, remote shells), generate a long-lived OAuth token with `claude setup-token` and register it as a profile:
-
-```bash
-# Prompt for the token (input is hidden — paste the value from `claude setup-token`)
-meridian profile add ci --oauth-token
-
-# Or pass it inline
-meridian profile add ci --oauth-token sk-ant-oat01-...
-```
-
-OAuth-token profiles store the token in `profiles.json` and feed it to the SDK via `CLAUDE_CODE_OAUTH_TOKEN` — no Keychain entry, no browser handshake. To prevent the SDK's 401-recovery from silently falling back to the host's `~/.claude` credentials, OAuth-token profiles also pin `CLAUDE_CONFIG_DIR` to an isolated per-profile directory under `~/.config/meridian/profiles/<name>/`. That directory holds only SDK state (sessions, settings) — never `.credentials.json`, since the token is delivered through the env.
-
-### Switching profiles
-
-```bash
-# CLI (while proxy is running)
-meridian profile switch work
-
-# Per-request header (any agent)
-curl -H "x-meridian-profile: work" ...
-```
-
-You can also switch profiles from the web UI — click an account card on the home page (`http://127.0.0.1:3456/`) or use the Profiles page at `/profiles`. The site header on every page shows which profile is active.
-
-### Sticky session routing
-
-With multiple profiles (e.g. two Claude Max subscriptions), Meridian can distribute sessions across profiles automatically while preserving **session affinity** — Anthropic's prompt caching is per-account, so a session must stay on one account to keep its ~99% cache hit rate:
-
-```bash
-MERIDIAN_ROUTING=sticky meridian     # or set "routing": "sticky" in ~/.config/meridian/settings.json
-```
-
-- Each session is assigned to a profile by rendezvous hashing of its session id — **deterministic and stateless**, so assignments survive proxy restarts with no state to lose
-- Adding/removing a profile only reassigns the sessions belonging to the changed arm — everything else keeps its warm cache
-- A session's subagent/fork requests share its assignment (same session id → same account)
-- The `x-meridian-profile` header still overrides everything, per request
-- Default is `active` (all traffic to the active profile — the pre-existing behavior); sticky is opt-in
-
-Request logs show the assignment (`profile=work(sticky)`), and `GET /profiles/list` reports the current `routing` mode.
-
-### Profile commands
-
-| Command | Description |
-|---------|-------------|
-| `meridian profile add <name> [--headless]` | Add a profile and authenticate via Claude OAuth; `--headless` prints a URL, prompts for the returned code, and stores the exchanged credentials |
-| `meridian profile add <name> --oauth-token [TOKEN]` | Add a headless profile from a `claude setup-token` value (prompts when `TOKEN` is omitted) |
-| `meridian profile list` | List profiles and auth status |
-| `meridian profile switch <name>` | Switch the active profile (requires running proxy) |
-| `meridian profile login <name> [--headless]` | Re-authenticate an expired profile (browser-login profiles only); `--headless` uses the URL/code flow |
-| `meridian profile remove <name>` | Remove a profile and its credentials |
-
-### How it works
-
-Each profile stores its credentials in an isolated `CLAUDE_CONFIG_DIR` under `~/.config/meridian/profiles/<name>/`. OAuth-token profiles use the same isolated directory layout — but the token itself lives in `~/.config/meridian/profiles.json` and is fed to the SDK via `CLAUDE_CODE_OAUTH_TOKEN`, so the per-profile dir holds only SDK state (sessions, settings) and never the credential. When a request arrives, Meridian resolves the profile in priority order:
-
-1. `x-meridian-profile` request header (per-request override)
-2. Active profile (set via `meridian profile switch` or the web UI)
-3. First configured profile
-
-Session state is scoped per profile — switching accounts won't cross-contaminate conversation history.
-
-### Environment variable configuration
-
-For advanced setups (CI, Docker), profiles can also be provided via environment variable:
-
-```bash
-export MERIDIAN_PROFILES='[
-  {"id":"personal","claudeConfigDir":"/path/to/config1"},
-  {"id":"work","claudeConfigDir":"/path/to/config2"},
-  {"id":"ci","oauthToken":"sk-ant-oat01-..."}
-]'
-export MERIDIAN_DEFAULT_PROFILE=personal
-meridian
-```
-
-Profile shapes:
-
-- `claudeConfigDir` — points at a `~/.claude`-style directory; uses Claude Max OAuth from that dir
-- `apiKey` (with optional `baseUrl`) — direct Anthropic API access; sets `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
-- `oauthToken` — long-lived token from `claude setup-token`; sets `CLAUDE_CODE_OAUTH_TOKEN`, no config dir needed
-
-When `MERIDIAN_PROFILES` is set, it takes precedence over disk-configured profiles. When unset, Meridian auto-discovers profiles from `~/.config/meridian/profiles.json` on each request.
-
-Related environment variables:
-
-- `MERIDIAN_ROUTING=sticky` — enable [sticky session routing](#sticky-session-routing) across profiles (default `active`)
-- `MERIDIAN_ADAPTER_INSTANCES='{...}'` — define [adapter instances](#adapter-instances) inline instead of via `~/.config/meridian/adapter-instances.json`
-
-## Agent Setup
-
-### OpenCode
-
-**Step 1: Run `meridian setup` (required, one time)**
-
-```bash
-meridian setup
-```
-
-This adds the Meridian plugin to your OpenCode global config (`~/.config/opencode/opencode.json`). The plugin enables:
-
-- **Session tracking** — reliable conversation continuity across requests
-- **Safe model defaults** — Opus uses 1M context (included with Max subscription); Sonnet uses 200k to avoid Extra Usage charges ([details](#configuration))
-- **Subagent model selection** — subagents automatically use `sonnet`/`opus` (200k), preserving rate-limit budget
-
-If the plugin is missing, Meridian warns at startup and reports `"plugin": "not-configured"` in the health endpoint.
-
-**Step 2: Start**
-
-```bash
-ANTHROPIC_API_KEY=x ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
-```
-
-Or set these in your shell profile so they're always active:
-
-```bash
-export ANTHROPIC_API_KEY=x
-export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
-```
-
-#### oh-my-opencagent (OMO)
-
-[oh-my-opencagent](https://github.com/nicobailey/oh-my-opencagent) adds multi-agent orchestration on top of OpenCode. It works transparently through Meridian with no extra configuration — OMO uses the same OpenCode headers and tool format, so Meridian detects it automatically.
-
-Meridian parses OMO's Task tool descriptions to extract subagent names (explore, code-review, etc.) and builds SDK AgentDefinitions so Claude can route to the correct agent. Internal orchestration markers (`<!-- OMO_INTERNAL_INITIATOR -->`, `[SYSTEM DIRECTIVE: OH-MY-OPENCODE ...]`) are stripped automatically to prevent context leakage.
-
-OMO requires **passthrough mode** (the default for OpenCode) — subagent delegation flows through tool calls that must be forwarded back to the client.
-
-### Crush
-
-Add a provider to `~/.config/crush/crush.json`:
-
-```json
-{
-  "providers": {
-    "meridian": {
-      "id": "meridian",
-      "name": "Meridian",
-      "type": "anthropic",
-      "base_url": "http://127.0.0.1:3456",
-      "api_key": "dummy",
-      "models": [
-        { "id": "claude-fable-5",    "name": "Claude Fable 5 (1M)",     "context_window": 1000000, "default_max_tokens": 32768, "can_reason": true, "supports_attachments": true },
-        { "id": "claude-opus-4-8",   "name": "Claude Opus 4.8 (1M)",    "context_window": 1000000, "default_max_tokens": 32768, "can_reason": true, "supports_attachments": true },
-        { "id": "claude-opus-4-7",   "name": "Claude Opus 4.7 (1M)",    "context_window": 1000000, "default_max_tokens": 32768, "can_reason": true, "supports_attachments": true },
-        { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6 (1M)",  "context_window": 1000000, "default_max_tokens": 64000, "can_reason": true, "supports_attachments": true },
-        { "id": "claude-opus-4-6",   "name": "Claude Opus 4.6 (1M)",    "context_window": 1000000, "default_max_tokens": 32768, "can_reason": true, "supports_attachments": true },
-        { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5", "context_window": 200000,  "default_max_tokens": 16384, "can_reason": true, "supports_attachments": true }
-      ]
-    }
-  }
-}
-```
-
-```bash
-crush run --model meridian/claude-sonnet-4-6 "refactor this function"
-crush --model meridian/claude-opus-4-6       # interactive TUI
-```
-
-Crush is automatically detected from its `Charm-Crush/` User-Agent — no plugin needed.
-
-### Droid (Factory AI)
-
-Add Meridian as a custom model provider in `~/.factory/settings.json`:
-
-```json
-{
-  "customModels": [
-    { "model": "claude-fable-5",          "name": "Fable 5 (Meridian)",    "provider": "anthropic", "baseUrl": "http://127.0.0.1:3456", "apiKey": "x" },
-    { "model": "claude-opus-4-8",         "name": "Opus 4.8 (Meridian)",   "provider": "anthropic", "baseUrl": "http://127.0.0.1:3456", "apiKey": "x" },
-    { "model": "claude-opus-4-7",         "name": "Opus 4.7 (Meridian)",   "provider": "anthropic", "baseUrl": "http://127.0.0.1:3456", "apiKey": "x" },
-    { "model": "claude-sonnet-4-6",       "name": "Sonnet 4.6 (Meridian)", "provider": "anthropic", "baseUrl": "http://127.0.0.1:3456", "apiKey": "x" },
-    { "model": "claude-opus-4-6",         "name": "Opus 4.6 (Meridian)",   "provider": "anthropic", "baseUrl": "http://127.0.0.1:3456", "apiKey": "x" },
-    { "model": "claude-haiku-4-5-20251001", "name": "Haiku 4.5 (Meridian)", "provider": "anthropic", "baseUrl": "http://127.0.0.1:3456", "apiKey": "x" }
-  ]
-}
-```
-
-Then pick any `custom:claude-*` model in the Droid TUI. No plugin needed — Droid is automatically detected.
-
-### Cline
-
-**1. Authenticate:**
-
-```bash
-cline auth --provider anthropic --apikey "dummy" --modelid "claude-sonnet-4-6"
-```
-
-**2. Set the proxy URL** in `~/.cline/data/globalState.json`:
-
-```json
-{
-  "anthropicBaseUrl": "http://127.0.0.1:3456",
-  "actModeApiProvider": "anthropic",
-  "actModeApiModelId": "claude-sonnet-4-6"
-}
-```
-
-**3. Run:**
-
-```bash
-cline --yolo "refactor the login function"
-```
-
-No plugin needed — Cline uses the standard Anthropic SDK.
-
-### Aider
-
-```bash
-ANTHROPIC_API_KEY=x ANTHROPIC_BASE_URL=http://127.0.0.1:3456 \
-  aider --model anthropic/claude-sonnet-4-6
-```
-
-> **Note:** `--no-stream` is incompatible due to a litellm parsing issue — use the default streaming mode.
-
-### Codex CLI
-
-Codex CLI ≥ 0.96 dropped `wire_api = "chat"` and speaks only the OpenAI **Responses API** (`/v1/responses`), which Meridian serves. Add a provider to `~/.codex/config.toml`:
-
-```toml
-model = "claude-sonnet-5"
-model_provider = "meridian"
-
-[model_providers.meridian]
-name = "Meridian"
-base_url = "http://127.0.0.1:3456/v1"
-wire_api = "responses"
-env_key = "MERIDIAN_KEY"    # any value unless MERIDIAN_API_KEY is set
-```
-
-```bash
-MERIDIAN_KEY=x codex "refactor this function"
-MERIDIAN_KEY=x codex exec "run the tests and summarize failures"   # non-interactive
-```
-
-Codex is a tool-driving agent — Meridian runs the `/v1/responses` endpoint in **passthrough** mode automatically (Codex executes its own shell/apply-patch tools), so no `MERIDIAN_PASSTHROUGH` change is needed. A harmless `Model metadata for 'claude-sonnet-5' not found` warning from Codex is expected — it doesn't recognize non-OpenAI model ids but works regardless.
-
-`model_reasoning_effort` is supported and won't stall the CLI, but Claude's private thinking isn't yet carried **across** turns — the Responses API's encrypted-reasoning envelope is OpenAI-specific and incompatible with Claude's signed thinking blocks, so cross-turn reasoning continuity is deferred (each turn still reasons with full context including tool results). Verified on Codex 0.144 with plain, tool-driving, and reasoning-enabled turns.
-
-### OpenAI-compatible tools (Open WebUI, Continue, etc.)
-
-Meridian speaks the OpenAI protocol natively — no LiteLLM or translation proxy needed.
-
-**`POST /v1/chat/completions`** — accepts OpenAI chat format, returns OpenAI completion format (streaming and non-streaming)
-
-- `image_url` parts are supported when provided as **data URLs** (`data:image/...;base64,...`)
-- multimodal tool flows where a tool returns `tool_result.content = [text, image]` are preserved through the structured multimodal path instead of being flattened to text
-
-**`GET /v1/models`** — returns available Claude models in OpenAI format
-
-Point any OpenAI-compatible tool at `http://127.0.0.1:3456` with any API key value:
-
-```bash
-# Open WebUI: set OpenAI API base to http://127.0.0.1:3456, API key to any value
-# Continue: set apiBase to http://127.0.0.1:3456 with provider: openai
-# Any OpenAI SDK: set base_url="http://127.0.0.1:3456", api_key="dummy"
-```
-
-> **Note:** Multi-turn conversations work by packing prior turns into the system prompt. Each request is a fresh SDK session — OpenAI clients replay full history themselves and don't use Meridian's session resumption.
-
-### Cherry Studio
-
-[Cherry Studio](https://github.com/CherryHQ/cherry-studio) is a desktop chat client. Point it at Meridian by setting the Anthropic API base URL to `http://127.0.0.1:3456` (any API key value works).
-
-Because Cherry Studio is a chat client rather than a coding agent, select the `cherry` adapter so Claude's **built-in web search** is available (coding-agent adapters block it in favour of their own):
-
-```bash
-MERIDIAN_DEFAULT_AGENT=cherry meridian
-```
-
-The `cherry` adapter runs in internal mode: Claude executes `WebSearch`/`WebFetch` itself and Meridian returns the grounded answer — the internal tool calls are hidden from the client. This resolves the "no WebSearch/WebFetch tool exposed" error (#481).
-
-> Cherry Studio doesn't send a Meridian-specific header, so set `MERIDIAN_DEFAULT_AGENT=cherry` on a Meridian dedicated to it, or send `x-meridian-agent: cherry` if your setup allows custom headers.
-
-### ForgeCode
-
-Add a custom provider to `~/forge/.forge.toml`:
-
-```toml
-[[providers]]
-id            = "meridian"
-url           = "http://127.0.0.1:3456/v1/messages"
-models        = "http://127.0.0.1:3456/v1/models"
-api_key_vars  = "MERIDIAN_FORGE_KEY"
-response_type = "Anthropic"
-auth_methods  = ["api_key"]
-
-[session]
-provider_id = "meridian"
-model_id    = "claude-opus-4-6"
-```
-
-Set the API key env var. Any value works unless you've enabled authentication with `MERIDIAN_API_KEY`, in which case use your auth key here:
-
-```bash
-export MERIDIAN_FORGE_KEY=x
-```
-
-Then log in and select the model:
-
-```bash
-forge provider login meridian    # enter any value when prompted
-forge config set provider meridian --model claude-opus-4-6
-```
-
-Start Meridian with the ForgeCode adapter:
-
-```bash
-MERIDIAN_DEFAULT_AGENT=forgecode meridian
-```
-
-ForgeCode uses reqwest's default User-Agent, so automatic detection isn't possible. The `MERIDIAN_DEFAULT_AGENT` env var tells Meridian to use the ForgeCode adapter for all unrecognized requests. If you run other agents alongside ForgeCode, use the `x-meridian-agent: forgecode` header instead (add `[providers.headers]` to your `.forge.toml`).
-
-### Pi
-
-Pi uses the `@mariozechner/pi-ai` library which supports a configurable `baseUrl` on the model. Add a provider-level override in `~/.pi/agent/models.json`:
-
-```json
-{
-  "providers": {
-    "anthropic": {
-      "baseUrl": "http://127.0.0.1:3456",
-      "apiKey": "x",
-      "headers": {
-        "x-meridian-agent": "pi"
-      }
-    }
-  }
-}
-```
-
-Pi mimics Claude Code's User-Agent, so automatic detection isn't possible. The `x-meridian-agent: pi` header in the config above tells Meridian to use the Pi adapter. Alternatively, if Pi is your only agent, you can set `MERIDIAN_DEFAULT_AGENT=pi` as an env var instead.
-
-Pi runs in passthrough mode by default — it executes its own tools and Meridian just forwards the `tool_use` blocks. Opt out with `MERIDIAN_PASSTHROUGH=0`.
-
-### Claude Code
-
-Claude Code can point at Meridian like any other Anthropic API client. The
-common use case is sharing a single Claude Max subscription from one host
-across other machines on your network — run Meridian on the box that is
-logged into Claude Max, then run Claude Code anywhere else against it.
-
-```bash
-# On another machine (or the same one)
-ANTHROPIC_AUTH_TOKEN=x ANTHROPIC_BASE_URL=http://meridian-host:3456 claude
-```
-
-> **Note:** Use `ANTHROPIC_AUTH_TOKEN` (or `ANTHROPIC_API_KEY`) — Claude Code
-> treats both as bearer credentials. Set the value to your `MERIDIAN_API_KEY`
-> if you've enabled authentication, otherwise any string works.
-
-> ⚠️ **Security for multi-machine setups.** If you expose Meridian beyond
-> loopback (e.g. bind to `0.0.0.0` or a LAN IP), **set `MERIDIAN_API_KEY` to a
-> strong secret** and require it on clients. An unprotected network-accessible
-> proxy is a Claude Max credential leak — anyone who can reach the port can
-> burn your subscription.
-
-Claude Code is detected automatically via its `claude-cli/*` User-Agent.
-Requests flow through the Claude Code adapter which:
-
-- Parses the client's real working directory from its `Primary working directory:` system-prompt line so Claude answers path-related questions with your local path, not the proxy host's.
-- Leaves the SDK subprocess cwd on the proxy host (Claude Code's local paths don't exist there).
-- Runs in passthrough mode by default — Claude Code executes its own tools on the machine it runs on; Meridian just forwards tool_use blocks.
-
-### Adapter instances
-
-Run several configurations of the same adapter side by side — e.g. a passthrough variant with thinking enabled and one without, or a dedicated config for a specific client. Define instances in `~/.config/meridian/adapter-instances.json` (or the `MERIDIAN_ADAPTER_INSTANCES` env var as a JSON string):
-
-```jsonc
-{
-  "oc-thinky":  { "base": "opencode", "features": { "thinking": "enabled" } },
-  "lite-plain": { "base": "passthrough", "passthrough": true,
-                  "match": { "userAgentPrefix": "litellm/" } },
-  "team-webui": { "base": "opencode", "features": { "codeSystemPrompt": false },
-                  "match": { "header": { "x-team": "alpha" } } }
-}
-```
-
-- **`base`** — which built-in adapter provides the behavior (tool handling, session tracking, transforms). Existing plugins and transforms scoped to the base adapter apply to its instances automatically.
-- **`features`** — per-instance overrides of the [SDK feature toggles](#sdk-feature-toggles-experimental) (thinking, system prompts, memory, ...) layered over the base's settings. Same keys as the settings UI.
-- **`passthrough`** — per-instance passthrough mode, overriding the adapter default and `MERIDIAN_PASSTHROUGH`.
-- **`match`** — optional automatic selection: exact header values and/or a User-Agent prefix. Match rules outrank built-in User-Agent detection (that's their purpose). Without `match`, select the instance per request with `x-meridian-agent: <instance-name>`.
-
-Built-in adapter names are reserved and can't be shadowed. With no instances configured, detection is exactly the built-in chain. Config file changes apply within ~5s, no restart needed.
-
-### Claude Design MCP
-
-Meridian proxies the Claude Design MCP API (`api.anthropic.com/v1/design/*`), so MCP clients can use Claude Design tools through your local endpoint.
-
-**1. Add the MCP server.** For Claude Code:
-
-```bash
-claude mcp add -s user --transport http claude-design http://127.0.0.1:3456/v1/design/mcp
-```
-
-Any other MCP client: point it at `http://127.0.0.1:3456/v1/design/mcp` (streamable HTTP).
-
-**2. Grant Claude Design consent (one time, per Anthropic account).** Tool calls return a `needs_consent` error until you enable it: open [claude.ai/design/settings](https://claude.ai/design/settings), find **"Claude product access"** ("Let other Claude products, like Claude Code, read and edit your Design projects"), and switch it **On**. This is a setting on the Anthropic account itself — with multiple Meridian profiles, the account behind the *profile handling the request* is the one that needs the toggle.
-
-That's it — your existing Claude Max login covers auth (`initialize`, `tools/list`, and tool calls are all verified working with a plain Max token). Verify with a quick handshake:
-
-```bash
-curl -s -X POST http://127.0.0.1:3456/v1/design/mcp -H 'content-type: application/json' \
-  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-```
-
-**Multiple profiles:** design requests use the active profile by default. To pin design traffic to a specific profile regardless of which is active, register the server with a profile header:
-
-```bash
-claude mcp add -s user --transport http --header "x-meridian-profile: personal" \
-  claude-design http://127.0.0.1:3456/v1/design/mcp
-```
-
-**Fallback OAuth flow:** if the upstream ever rejects your token with an `auth_error` (scope enforcement has varied over time), `/design-login` obtains a dedicated token with the `user:design:read`/`user:design:write` scopes:
-
-```bash
-curl http://127.0.0.1:3456/design-login          # returns an authorize URL — open it in your browser
-curl -X POST http://127.0.0.1:3456/design-login \
-  -H 'content-type: application/json' \
-  -d '{"code": "<code-from-browser>"}'           # paste the code you were shown
-```
-
-The design token is stored at `~/.config/meridian/design-token.json` (mode `0600`, global across profiles) and refreshed automatically when it expires.
-
-> Contributed by [@sittitep](https://github.com/sittitep) (#543).
-
-### Any Anthropic-compatible tool
-
-```bash
-export ANTHROPIC_API_KEY=x
-export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
-```
-
 ## Tested Agents
 
 | Agent | Status | Notes |
 |-------|--------|-------|
-| [OpenCode](https://github.com/anomalyco/opencode) | ✅ Verified | Requires `meridian setup` — full tool support, session resume, streaming, subagents |
-| [ForgeCode](https://forgecode.dev) | ✅ Verified | Provider config (see above) — passthrough tool execution, session resume, streaming |
-| [Droid (Factory AI)](https://factory.ai/product/ide) | ✅ Verified | BYOK config (see above) — full tool support, session resume, streaming |
-| [Crush](https://github.com/charmbracelet/crush) | ✅ Verified | Provider config (see above) — full tool support, session resume, headless `crush run` |
-| [Cline](https://github.com/cline/cline) | ✅ Verified | Config (see above) — full tool support, file read/write/edit, bash, session resume |
+| [OpenCode](https://github.com/anomalyco/opencode) | ✅ Verified | Requires `meridian setup` ([setup](docs/agents.md#opencode)) — full tool support, session resume, streaming, subagents |
+| [ForgeCode](https://forgecode.dev) | ✅ Verified | Provider config (see [Agent Setup](docs/agents.md)) — passthrough tool execution, session resume, streaming |
+| [Droid (Factory AI)](https://factory.ai/product/ide) | ✅ Verified | BYOK config (see [Agent Setup](docs/agents.md)) — full tool support, session resume, streaming |
+| [Crush](https://github.com/charmbracelet/crush) | ✅ Verified | Provider config (see [Agent Setup](docs/agents.md)) — full tool support, session resume, headless `crush run` |
+| [Cline](https://github.com/cline/cline) | ✅ Verified | Config (see [Agent Setup](docs/agents.md)) — full tool support, file read/write/edit, bash, session resume |
 | [Aider](https://github.com/paul-gauthier/aider) | ✅ Verified | Env vars — file editing, streaming; `--no-stream` broken (litellm bug) |
 | [Open WebUI](https://github.com/open-webui/open-webui) | ✅ Verified | OpenAI-compatible endpoints — set base URL to `http://127.0.0.1:3456` |
-| [Pi](https://github.com/mariozechner/pi-coding-agent) | ✅ Verified | models.json config (see above) — full tool support via passthrough; detected via `x-meridian-agent: pi` header |
+| [Pi](https://github.com/mariozechner/pi-coding-agent) | ✅ Verified | models.json config (see [Agent Setup](docs/agents.md)) — full tool support via passthrough; detected via `x-meridian-agent: pi` header |
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Verified | `ANTHROPIC_BASE_URL` — remote clients share a Max subscription over the network; client CWD preserved in system prompt |
-| [Cherry Studio](https://github.com/CherryHQ/cherry-studio) | ✅ Verified | `cherry` adapter (see above) — chat client with Claude's built-in web search via internal mode |
-| [Codex CLI](https://github.com/openai/codex) | ✅ Verified | `/v1/responses` (see above) — Responses-API provider, passthrough tool execution; verified on 0.144 (plain + tool-driving turns) |
+| [Cherry Studio](https://github.com/CherryHQ/cherry-studio) | ✅ Verified | `cherry` adapter (see [Agent Setup](docs/agents.md)) — chat client with Claude's built-in web search via internal mode |
+| [Codex CLI](https://github.com/openai/codex) | ✅ Verified | `/v1/responses` (see [Agent Setup](docs/agents.md)) — Responses-API provider, passthrough tool execution; verified on 0.144 (plain + tool-driving turns) |
 | [Continue](https://github.com/continuedev/continue) | 🔲 Untested | OpenAI-compatible endpoints should work — set `apiBase` to `http://127.0.0.1:3456` |
 
 Tested an agent or built a plugin? [Open an issue](https://github.com/rynfar/meridian/issues) and we'll add it.
 
-## Architecture
-
-```
-src/proxy/
-├── server.ts              ← HTTP orchestration (routes, SSE streaming, concurrency)
-├── adapter.ts             ← AgentAdapter interface
-├── adapters/
-│   ├── detect.ts          ← Agent detection from request headers
-│   ├── opencode.ts        ← OpenCode adapter
-│   ├── forgecode.ts       ← ForgeCode adapter
-│   ├── crush.ts           ← Crush adapter
-│   ├── droid.ts           ← Droid adapter
-│   ├── pi.ts              ← Pi adapter
-│   ├── cherry.ts          ← Cherry Studio adapter (internal mode + web search)
-│   ├── claudecode.ts      ← Claude Code adapter (remote clients sharing a Max host)
-│   ├── openai.ts          ← OpenAI-endpoint adapter (/v1/chat/completions)
-│   ├── codex.ts           ← Codex CLI adapter (/v1/responses, forced passthrough)
-│   └── passthrough.ts     ← LiteLLM passthrough adapter
-├── query.ts               ← SDK query options builder
-├── errors.ts              ← Error classification
-├── models.ts              ← Model mapping (sonnet/opus/haiku, agentMode)
-├── tokenRefresh.ts        ← Cross-platform OAuth token refresh
-├── openai.ts              ← OpenAI ↔ Anthropic format translation (pure)
-├── openaiResponses.ts     ← OpenAI Responses API ↔ Anthropic translation (pure)
-├── setup.ts               ← OpenCode plugin configuration
-├── session/
-│   ├── lineage.ts         ← Per-message hashing, mutation classification (pure)
-│   ├── fingerprint.ts     ← Conversation fingerprinting
-│   └── cache.ts           ← LRU session caches
-├── profiles.ts            ← Multi-profile: resolve, list, switch auth contexts
-├── profileCli.ts          ← CLI commands for profile management
-├── sessionStore.ts        ← Cross-proxy file-based session persistence
-└── passthroughTools.ts    ← Tool forwarding mode
-telemetry/
-├── ...
-├── profileBar.ts          ← Shared site header (brand, nav, status, active profile)
-└── profilePage.ts         ← Profile management page
-plugin/
-└── meridian.ts            ← OpenCode plugin (session headers + agent mode)
-```
-
-### Session Management
-
-Every incoming request is classified:
-
-| Classification | What Happened | Action |
-|---------------|---------------|--------|
-| **Continuation** | New messages appended | Resume SDK session |
-| **Compaction** | Agent summarized old messages | Resume (suffix preserved) |
-| **Undo** | User rolled back messages | Fork at rollback point |
-| **Diverged** | Completely different conversation | Start fresh |
-
-Sessions are stored in-memory (LRU) and persisted to `~/.cache/meridian/sessions.json` for cross-proxy resume.
-
-### Agent Detection
-
-Agents are identified from request headers automatically:
-
-| Signal | Adapter |
-|---|---|
-| `x-meridian-agent` header | Explicit override (any adapter) |
-| `x-opencode-session` or `x-session-affinity` header | OpenCode |
-| `opencode/` User-Agent | OpenCode |
-| `factory-cli/` User-Agent | Droid |
-| `Charm-Crush/` User-Agent | Crush |
-| `claude-cli/` User-Agent | Claude Code (unless `MERIDIAN_DEFAULT_AGENT` overrides — Pi mimics this UA) |
-| `litellm/` UA or `x-litellm-*` headers | LiteLLM passthrough |
-| *(anything else)* | `MERIDIAN_DEFAULT_AGENT` env var, or OpenCode |
-
-### Adding a New Agent
-
-Implement the `AgentAdapter` interface in `src/proxy/adapters/`. See [`adapters/opencode.ts`](src/proxy/adapters/opencode.ts) for a reference.
-
-## API Key Authentication
-
-By default, Meridian binds to `127.0.0.1` and requires no authentication — anyone on localhost can use it. If you expose Meridian over a network (Tailscale, LAN, Docker with port mapping), you can enable API key authentication to prevent unauthorized access.
-
-```bash
-MERIDIAN_API_KEY=your-secret-key meridian
-```
-
-When set:
-- All API routes (`/v1/messages`, `/v1/chat/completions`, etc.) and admin routes (`/telemetry`, `/metrics`, `/profiles`) require a matching key
-- `/` and `/health` remain open (monitoring tools need unauthenticated health checks)
-- Keys are accepted via `x-api-key` header or `Authorization: Bearer` header
-
-Clients just set their `ANTHROPIC_API_KEY` to the shared secret — since most tools already send this header, no workflow changes are needed:
-
-```bash
-ANTHROPIC_API_KEY=your-secret-key ANTHROPIC_BASE_URL=http://meridian-host:3456 opencode
-```
-
-## Configuration
-
-| Variable | Alias | Default | Description |
-|----------|-------|---------|-------------|
-| `MERIDIAN_API_KEY` | — | unset | Shared secret for API key authentication. When set, all API and admin routes require a matching `x-api-key` or `Authorization: Bearer` header. `/` and `/health` remain open. |
-| `MERIDIAN_PORT` | `CLAUDE_PROXY_PORT` | `3456` | Port to listen on |
-| `MERIDIAN_HOST` | `CLAUDE_PROXY_HOST` | `127.0.0.1` | Host to bind to |
-| `MERIDIAN_PASSTHROUGH` | `CLAUDE_PROXY_PASSTHROUGH` | unset | Forward tool calls to client instead of executing |
-| `MERIDIAN_MAX_CONCURRENT` | `CLAUDE_PROXY_MAX_CONCURRENT` | `10` | Maximum concurrent SDK sessions |
-| `MERIDIAN_MAX_SESSIONS` | `CLAUDE_PROXY_MAX_SESSIONS` | `1000` | In-memory LRU session cache size |
-| `MERIDIAN_MAX_STORED_SESSIONS` | `CLAUDE_PROXY_MAX_STORED_SESSIONS` | `10000` | File-based session store capacity |
-| `MERIDIAN_WORKDIR` | `CLAUDE_PROXY_WORKDIR` | `cwd()` | Default working directory for SDK |
-| `MERIDIAN_IDLE_TIMEOUT_SECONDS` | `CLAUDE_PROXY_IDLE_TIMEOUT_SECONDS` | `120` | HTTP keep-alive timeout |
-| `MERIDIAN_TELEMETRY_SIZE` | `CLAUDE_PROXY_TELEMETRY_SIZE` | `1000` | Telemetry ring buffer size |
-| `MERIDIAN_NO_FILE_CHANGES` | `CLAUDE_PROXY_NO_FILE_CHANGES` | unset | Disable "Files changed" summary in responses |
-| `MERIDIAN_SONNET_MODEL` | `CLAUDE_PROXY_SONNET_MODEL` | `sonnet` | Sonnet context tier: `sonnet` (200k, default) or `sonnet[1m]` (1M, requires Extra Usage†) |
-| `MERIDIAN_1M_CONTEXT_SUPPORT` | `CLAUDE_PROXY_1M_CONTEXT_SUPPORT` | unset | Set to `0`/`false`/`no` to disable 1M context entirely — every model resolves to its 200k base variant, so Meridian never requests the extended window (avoids Extra Usage on 1M). |
-| `MERIDIAN_DEFAULT_AGENT` | — | `opencode` | Default adapter for unrecognized agents: `opencode`, `forgecode`, `pi`, `crush`, `droid`, `cherry`, `claudecode`, `passthrough`. Requires restart. |
-| `MERIDIAN_ROUTING` | — | `active` | Session-to-profile routing: `active` (all traffic to the active profile) or `sticky` ([sticky session routing](#sticky-session-routing)) |
-| `MERIDIAN_PASSTHROUGH_EARLY_STOP` | — | `1` | Set to `0` to disable [digest-turn elimination](#how-tool-calling-works-in-passthrough) and restore the old end-of-turn behavior |
-| `MERIDIAN_SUPPRESS_SCRATCHPAD` | — | `1` | Set to `0` to let the SDK advertise its proxy-host scratchpad directory in passthrough mode |
-| `MERIDIAN_PRICING_CONFIG` | `CLAUDE_PROXY_PRICING_CONFIG` | `~/.config/meridian/model-pricing.json` | Path to the model pricing overrides file used by cost estimation |
-| `MERIDIAN_PROFILES` | — | unset | JSON array of profile configs (overrides disk discovery). See [Multi-Profile Support](#multi-profile-support). |
-| `MERIDIAN_DEFER_TOOL_THRESHOLD` | — | `15` | Number of tools before non-core tools are deferred via ToolSearch. Set to `0` to disable. |
-| `MERIDIAN_TELEMETRY_PERSIST` | `CLAUDE_PROXY_TELEMETRY_PERSIST` | unset | Enable SQLite telemetry persistence. Data survives proxy restarts. |
-| `MERIDIAN_TELEMETRY_DB` | `CLAUDE_PROXY_TELEMETRY_DB` | `~/.config/meridian/telemetry.db` | SQLite database path (when persistence is enabled) |
-| `MERIDIAN_TELEMETRY_RETENTION_DAYS` | `CLAUDE_PROXY_TELEMETRY_RETENTION_DAYS` | `7` | Days to retain telemetry data before cleanup |
-| `MERIDIAN_DEFAULT_PROFILE` | — | *(first profile)* | Default profile ID when no header is sent |
-| `MERIDIAN_ADAPTER_INSTANCES` | — | unset | JSON [adapter instance](#adapter-instances) definitions, overriding `~/.config/meridian/adapter-instances.json` |
-| `MERIDIAN_BETA_POLICY` | — | `allow-safe` | Client `anthropic-beta` header handling: `allow-safe`, `strip-all`, or `allow-all` |
-| `MERIDIAN_DEFAULT_{FABLE,OPUS,SONNET,HAIKU}_MODEL` | — | canonical ids | Pin the model id the SDK resolves for each tier alias (e.g. `MERIDIAN_DEFAULT_OPUS_MODEL`) |
-| `MERIDIAN_SESSION_DIR` | `CLAUDE_PROXY_SESSION_DIR` | `~/.cache/meridian` | Directory for the persisted session store |
-| `MERIDIAN_DEBUG` | `CLAUDE_PROXY_DEBUG` | unset | Set to `1` for verbose request/session logging |
-| `MERIDIAN_SILENT` | `CLAUDE_PROXY_SILENT` | unset | Set to `1` to suppress startup output (used by embedding plugins) |
-| `MERIDIAN_PLUGIN_DIR` | — | `~/.config/meridian/plugins` | Plugin auto-discovery directory |
-| `MERIDIAN_PLUGIN_CONFIG` | — | `~/.config/meridian/plugins.json` | Plugin manifest path |
-
-†Sonnet 1M requires Extra Usage on all plans including Max ([docs](https://code.claude.com/docs/en/model-config#extended-context)). Opus 1M is included with Max/Team/Enterprise at no extra cost.
-
-## Endpoints
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /` | Landing page |
-| `POST /v1/messages` | Anthropic Messages API |
-| `POST /messages` | Alias for `/v1/messages` |
-| `POST /v1/chat/completions` | OpenAI-compatible chat completions |
-| `POST /v1/responses` | OpenAI Responses API (Codex CLI ≥ 0.96) |
-| `GET /v1/models` | OpenAI-compatible model list |
-| `GET/POST /v1/design/*` | Claude Design MCP proxy (see [Claude Design MCP](#claude-design-mcp)) |
-| `GET/POST /design-login` | OAuth flow for the design scopes |
-| `GET /health` | Auth status, mode, plugin status |
-| `POST /auth/refresh` | Manually refresh the OAuth token |
-| `GET /telemetry` | Performance dashboard |
-| `GET /telemetry/requests` | Recent request metrics (JSON) |
-| `GET /telemetry/summary` | Aggregate statistics (JSON) |
-| `GET /telemetry/logs` | Diagnostic logs (JSON) |
-| `GET /metrics` | Prometheus exposition format metrics |
-| `GET /profiles` | Profile management page |
-| `GET /profiles/list` | List profiles with auth status (JSON) |
-| `POST /profiles/active` | Switch the active profile |
-| `GET /v1/usage/quota` | Usage windows for the active profile (JSON) |
-| `GET /v1/usage/quota/all` | Usage windows for every profile (JSON) |
-| `GET /settings` | SDK feature toggles + model pricing UI |
-| `GET /plugins` | Plugin management page (`/plugins/list`, `POST /plugins/reload` for JSON/actions) |
-
-Health response example:
-
-```json
-{
-  "status": "healthy",
-  "version": "1.50.0",
-  "auth": { "loggedIn": true, "email": "you@example.com", "subscriptionType": "max" },
-  "mode": "internal",
-  "plugin": { "opencode": "configured" }
-}
-```
-
-`plugin.opencode` is `"configured"` when `meridian setup` has been run, `"not-configured"` otherwise.
-
-## Plugins
-
-Extend Meridian's behavior with composable plugins — no core modifications needed.
-
-**Quick start:** Drop a `.ts` or `.js` file in `~/.config/meridian/plugins/` and restart.
-
-```ts
-// ~/.config/meridian/plugins/my-plugin.ts
-export default {
-  name: "my-plugin",
-  onRequest(ctx) {
-    // modify request context
-    return { ...ctx, systemContext: ctx.systemContext + "\nBe concise." }
-  },
-}
-```
-
-- **Manage plugins** at `http://localhost:3456/plugins`
-- **Reload without restart:** `POST /plugins/reload`
-- **Full guide:** See [PLUGINS.md](PLUGINS.md)
-
-### Official plugins
-
-Content-scoped scrubbers maintained alongside Meridian. Core stays a clean
-proxy — anything that rewrites client prompt content ships as one of these
-opt-in plugins instead:
-
-| Plugin | What it does |
-|--------|--------------|
-| [`@rynfar/meridian-plugin-hermes-scrub`](https://github.com/rynfar/meridian-plugin-hermes-scrub) | Strips Hermes Agent's `# Finishing the job` harness block from the system prompt. Fixes empty-stream responses when proxying Hermes, and avoids its coding-harness fingerprint. |
-| [`@rynfar/meridian-plugin-pi-scrub`](https://github.com/rynfar/meridian-plugin-pi-scrub) | Strips Pi's coding-agent-harness prompt line that Anthropic meters as Extra Usage. |
-| [`@rynfar/meridian-plugin-opencode-scrub`](https://github.com/rynfar/meridian-plugin-opencode-scrub) | Strips OpenCode harness boilerplate from the system prompt before it reaches Claude. |
-
-**Nix users:** the flake packages all three prebuilt — `pkgs.meridianPlugins.<name>` via the `meridian` overlay (or `meridian.legacyPackages.${system}.meridianPlugins`), each exposing `.path` for a `plugins.json` entry or the home-manager `pluginConfig` option. Pins are refreshed by a scheduled workflow that rebuilds every plugin before bumping.
-
-Everyone else: install into Meridian's config dir and register the built file in
-`~/.config/meridian/plugins.json`:
-
-```bash
-cd ~/.config/meridian
-npm install @rynfar/meridian-plugin-hermes-scrub
-```
-
-```json
-{
-  "plugins": [
-    { "path": "/Users/you/.config/meridian/node_modules/@rynfar/meridian-plugin-hermes-scrub/dist/index.js", "enabled": true }
-  ]
-}
-```
-
-Paths must be absolute — the loader does not expand `~`.
-
-Both plugin locations are configurable for the standalone CLI: `MERIDIAN_PLUGIN_DIR` overrides the auto-discovery directory and `MERIDIAN_PLUGIN_CONFIG` the manifest path (useful for Nix, containers, or running several instances with different plugin sets).
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `meridian` | Start the proxy server |
-| `meridian setup` | Configure the OpenCode plugin in `~/.config/opencode/opencode.json` |
-| `meridian profile add <name> [--headless]` | Add a profile and authenticate via Claude OAuth; `--headless` prints a URL, prompts for the returned code, and stores the exchanged credentials |
-| `meridian profile add <name> --oauth-token [TOKEN]` | Add a headless profile from a `claude setup-token` value (prompts when `TOKEN` is omitted) |
-| `meridian profile list` (alias `profile ls`) | List all profiles and their auth status |
-| `meridian profile switch <name>` | Switch the active profile (requires running proxy) |
-| `meridian profile login <name> [--headless]` | Re-authenticate an expired profile (browser-login profiles only); `--headless` uses the URL/code flow |
-| `meridian profile remove <name>` | Remove a profile and its credentials |
-| `meridian refresh-token` | Manually refresh the Claude OAuth token (exits 0/1) |
-
-## Programmatic API
-
-```typescript
-import { startProxyServer } from "@rynfar/meridian"
-
-const instance = await startProxyServer({
-  port: 3456,
-  host: "127.0.0.1",
-  silent: true,
-})
-
-// instance.server — underlying http.Server
-await instance.close()
-```
-
-## Docker
-
-Claude Code authentication requires a browser, which isn't available inside containers. Authenticate on your local machine first, then mount the credentials into Docker.
-
-### Single account
-
-```bash
-# 1. Authenticate locally (one time)
-claude login
-
-# 2. Run with mounted credentials
-docker run -v ~/.claude:/home/claude/.claude -p 3456:3456 meridian
-```
-
-Meridian refreshes OAuth tokens automatically — once the credentials are mounted, no further browser access is needed.
-
-> **macOS hosts:** mounting `~/.claude` does **not** carry credentials into the container — on macOS the CLI stores OAuth tokens in the Keychain, not in files, so the container sees an empty credential store and requests fail with an authentication error. Use an [OAuth-token profile](#oauth-token-profiles-in-docker-no-volume-mount) instead (recommended), or run `claude login` once inside the container (`docker exec -it <name> claude login`).
-
-### Multiple profiles in Docker
-
-Authenticate each profile locally, then pass them to Docker via the `MERIDIAN_PROFILES` environment variable:
-
-```bash
-# 1. Authenticate each account locally
-meridian profile add personal
-meridian profile add work    # sign out of claude.ai first, sign into work account
-
-# 2. Run Docker with profile configs pointing to mounted credential directories
-docker run \
-  -v ~/.config/meridian/profiles/personal:/profiles/personal \
-  -v ~/.config/meridian/profiles/work:/profiles/work \
-  -e 'MERIDIAN_PROFILES=[{"id":"personal","claudeConfigDir":"/profiles/personal"},{"id":"work","claudeConfigDir":"/profiles/work"}]' \
-  -e MERIDIAN_DEFAULT_PROFILE=personal \
-  -p 3456:3456 meridian
-```
-
-Switch profiles at runtime via the `x-meridian-profile` header or `meridian profile switch` (see [Multi-Profile Support](#multi-profile-support)).
-
-### OAuth-token profiles in Docker (no volume mount)
-
-If you'd rather not mount a credential directory, generate a long-lived OAuth token on the host with `claude setup-token` and pass it as a profile. There's nothing to mount — the token alone is the credential:
-
-```bash
-docker run \
-  -e 'MERIDIAN_PROFILES=[{"id":"ci","oauthToken":"sk-ant-oat01-..."}]' \
-  -e MERIDIAN_DEFAULT_PROFILE=ci \
-  -p 3456:3456 meridian
-```
-
-This is the recommended path for CI runners, ephemeral containers, and cross-host deployments where browser-based login isn't reachable. Treat the token like any other secret — inject it via your platform's secret store rather than committing it to your image or compose file.
-
-## Testing
-
-```bash
-npm test       # unit + integration tests
-npm run build  # build with bun + tsc
-```
-
-| Tier | What | Speed |
-|------|------|-------|
-| Unit | Pure functions, no mocks | Fast |
-| Integration | HTTP layer with mocked SDK | Fast |
-| E2E | Real proxy + real Claude Max ([`E2E.md`](E2E.md)) | Manual |
-
 ## FAQ
 
 **Is this allowed by Anthropic's terms?**
@@ -1078,7 +135,7 @@ curl -X POST http://127.0.0.1:3456/auth/refresh
 **I'm getting `400 You're out of extra usage` on tool-bearing requests. What do I do?**
 This error class ([#516](https://github.com/rynfar/meridian/issues/516), historical) came from Anthropic's server-side classifier gating certain requests behind Extra Usage. It had two distinct triggers, both now addressed:
 
-- **Harness fingerprints** — identity lines in a client's system prompt (e.g. pi's "coding agent harness" line) were metered as Extra Usage. The [official scrub plugins](#official-plugins) strip these and remain recommended for the affected harnesses.
+- **Harness fingerprints** — identity lines in a client's system prompt (e.g. pi's "coding agent harness" line) were metered as Extra Usage. The [official scrub plugins](docs/plugins.md#official-plugins) strip these and remain recommended for the affected harnesses.
 - **Tool-definition presence** — reported in mid-2026 as triggering independently of prompt content; as of July 2026 this no longer reproduces on Max accounts (verified with Extra Usage disabled, tools present, and an unscrubbed fingerprint prompt). It appears to have been resolved upstream in Anthropic's billing policy.
 
 If you still hit the error on a current release, first check `GET /v1/usage/quota` to rule out genuinely exhausted quota, then try disabling the connecting client's system prompt for the affected adapter while keeping the Claude Code prompt enabled (in the `/settings` UI under **SDK Feature Toggles**, or `PATCH /settings/api/features/<adapter>` with `{"clientSystemPrompt":false,"codeSystemPrompt":true}`) — and please report it on [#516](https://github.com/rynfar/meridian/issues/516) with your plan type, since remaining occurrences are likely account-cohort specific (Team plans are treated differently by the API).

package/dist/{cli-mqht6rs9.js → cli-w63v1ftp.js}

@@ -9988,7 +9988,7 @@ function introSection(h){
   meta.push('port '+location.port);
   return '<div class="intro">'
     +'<h2>Harness Claude, your way.</h2>'
-    +'<p>Meridian bridges any Anthropic-API agent to your Claude subscription — point the agent’s <code>ANTHROPIC_BASE_URL</code> at <code>http://'+esc(location.host)+'</code> and every request routes through the active account below. Setup guides for each agent live in the <a href="https://github.com/rynfar/meridian#readme">README</a>.</p>'
+    +'<p>Meridian bridges any Anthropic-API agent to your Claude subscription — point the agent’s <code>ANTHROPIC_BASE_URL</code> at <code>http://'+esc(location.host)+'</code> and every request routes through the active account below. Setup guides for each agent live in the <a href="https://github.com/rynfar/meridian/blob/main/docs/agents.md">Agent Setup guide</a>.</p>'
     +'<div class="intro-meta">'+meta.join(' · ')+'</div>'
     +'</div>';
 }
@@ -12330,8 +12330,8 @@ function extractPiCwd(body) {
 }
 var piAdapter = {
   name: "pi",
-  getSessionId(_c) {
-    return;
+  getSessionId(c) {
+    return c.req.header("x-session-affinity");
   },
   extractWorkingDirectory(body) {
     return extractPiCwd(body);
@@ -12596,6 +12596,9 @@ var codexAdapter = {
   name: "codex",
   usesPassthrough() {
     return true;
+  },
+  getSessionId(c) {
+    return c.req.header("x-codex-session");
   }
 };
 
@@ -20013,7 +20016,7 @@ function createProxyServer(config = {}) {
         const lastMessage = Array.isArray(body.messages) ? body.messages[body.messages.length - 1] : undefined;
         const lastIsToolResult = Array.isArray(lastMessage?.content) && lastMessage.content.some((b) => b?.type === "tool_result");
         const isClientDrivenLoop = adapterBase !== "claude-code" && !agentSessionId && lastIsToolResult;
-        const isIndependentSession = requestSource?.startsWith("fork-") || requestSource?.startsWith("subagent-") || isClientDrivenLoop || false;
+        const isIndependentSession = !agentSessionId && (requestSource?.startsWith("fork-") || requestSource?.startsWith("subagent-")) || isClientDrivenLoop || false;
         if (!isIndependentSession && profileSessionId) {
           const pendingStore = pendingSessionStores.get(profileSessionId);
           if (pendingStore) {
@@ -22231,6 +22234,10 @@ data: ${JSON.stringify({
       "Content-Type": "application/json",
       "x-meridian-agent": "codex"
     };
+    const promptCacheKey = rawBody.prompt_cache_key;
+    if (typeof promptCacheKey === "string" && promptCacheKey.length > 0) {
+      internalHeaders["x-codex-session"] = promptCacheKey;
+    }
     const xApiKey = c.req.header("x-api-key");
     if (xApiKey)
       internalHeaders["x-api-key"] = xApiKey;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   startProxyServer
-} from "./cli-mqht6rs9.js";
+} from "./cli-w63v1ftp.js";
 import"./cli-f0yqy2d2.js";
 import"./cli-sry5aqdj.js";
 import"./cli-xmweegb1.js";

package/dist/proxy/adapters/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../../src/proxy/adapters/codex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,eAAO,MAAM,YAAY,EAAE,YAM1B,CAAA"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../../src/proxy/adapters/codex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,eAAO,MAAM,YAAY,EAAE,YAgB1B,CAAA"}

package/dist/proxy/adapters/pi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pi.d.ts","sourceRoot":"","sources":["../../../src/proxy/adapters/pi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAyC9C,eAAO,MAAM,SAAS,EAAE,YA2HvB,CAAA;AAED,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"pi.d.ts","sourceRoot":"","sources":["../../../src/proxy/adapters/pi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAyC9C,eAAO,MAAM,SAAS,EAAE,YA+HvB,CAAA;AAED,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/proxy/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/proxy/server.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,CAAA;AAGvD,YAAY,EACV,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAA;AAKpB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAkDnG,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EAEpB,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAA+B,iBAAiB,EAAE,mBAAmB,EAAsC,MAAM,iBAAiB,CAAA;AAGzI,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,CAAA;AAgR7B,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAwrHhF;AAWD,wBAAgB,gCAAgC,IAAI,IAAI,CAavD;AAED,wBAAsB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmGhG"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/proxy/server.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,CAAA;AAGvD,YAAY,EACV,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAA;AAKpB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAkDnG,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EAEpB,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAA+B,iBAAiB,EAAE,mBAAmB,EAAsC,MAAM,iBAAiB,CAAA;AAGzI,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,CAAA;AAgR7B,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAysHhF;AAWD,wBAAgB,gCAAgC,IAAI,IAAI,CAavD;AAED,wBAAsB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmGhG"}

package/dist/server.js

@@ -11,7 +11,7 @@ import {
   runObserveHook,
   runTransformHook,
   startProxyServer
-} from "./cli-mqht6rs9.js";
+} from "./cli-w63v1ftp.js";
 import"./cli-f0yqy2d2.js";
 import"./cli-sry5aqdj.js";
 import"./cli-xmweegb1.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynfar/meridian",
-  "version": "1.54.0",
+  "version": "1.55.0",
   "description": "Local Anthropic API powered by your Claude Max subscription. One subscription, every agent.",
   "type": "module",
   "main": "./dist/server.js",