diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 562c4a5..e25d96f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,21 +1,21 @@ { - "name": "antonbabenko-claude-delegator", + "name": "antonbabenko-deliberation", "owner": { "name": "Anton Babenko", "url": "https://github.com/antonbabenko" }, "plugins": [ { - "name": "claude-delegator", + "name": "deliberation", "source": "./", - "description": "GPT (Codex CLI), Gemini (bundled MCP bridge), and Grok (xAI HTTP bridge) expert subagents for Claude Code. Seven specialized experts: Architect, Plan Reviewer, Scope Analyst, Code Reviewer, Security Analyst, Researcher, Debugger.", + "description": "Use when you want a delegated second opinion or implementation from GPT (Codex), Gemini, Grok (xAI), or OpenRouter (config-driven, 400+ models) - seven expert subagents (Architect, Plan Reviewer, Scope Analyst, Code Reviewer, Security Analyst, Researcher, Debugger) and bundled ask-gpt/ask-gemini/ask-grok/ask-openrouter/ask-all/consensus commands, advisory (read-only) or implementation (write; Grok and OpenRouter are advisory-only).", "version": "1.18.0", "author": { "name": "Anton Babenko", "url": "https://github.com/antonbabenko" }, - "homepage": "https://github.com/antonbabenko/claude-delegator", - "repository": "https://github.com/antonbabenko/claude-delegator", + "homepage": "https://github.com/antonbabenko/deliberation", + "repository": "https://github.com/antonbabenko/deliberation", "license": "MIT", "keywords": [ "delegation", @@ -27,11 +27,13 @@ "google", "grok", "xai", - "files", + "openrouter", "experts", "subagents", - "orchestration" + "orchestration", + "code-review", + "architecture" ] } ] -} +} \ No newline at end of file diff --git a/.claude-plugin/mcp.json b/.claude-plugin/mcp.json new file mode 100644 index 0000000..fac3b30 --- /dev/null +++ b/.claude-plugin/mcp.json @@ -0,0 +1,29 @@ +{ + "mcpServers": { + "codex": { + "command": "codex", + "args": ["mcp-server"], + "type": "stdio" + }, + "gemini": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/server/gemini/index.js"], + "type": "stdio" + }, + "grok": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/server/grok/index.js"], + "type": "stdio" + }, + "openrouter": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/server/openrouter/index.js"], + "type": "stdio" + }, + "deliberation": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/server/mcp/index.js"], + "type": "stdio" + } + } +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8f80b31..67806cf 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,13 +1,13 @@ { - "name": "claude-delegator", - "description": "GPT (Codex CLI), Gemini (bundled MCP bridge), and Grok (xAI HTTP bridge) expert subagents for Claude Code. Seven specialized experts: Architect, Plan Reviewer, Scope Analyst, Code Reviewer, Security Analyst, Researcher, Debugger.", + "name": "deliberation", + "description": "Use when you want a delegated second opinion or implementation from GPT (Codex), Gemini, Grok (xAI), or OpenRouter (config-driven, 400+ models) - seven expert subagents (Architect, Plan Reviewer, Scope Analyst, Code Reviewer, Security Analyst, Researcher, Debugger) and bundled ask-gpt/ask-gemini/ask-grok/ask-openrouter/ask-all/consensus commands, advisory (read-only) or implementation (write; Grok and OpenRouter are advisory-only).", "version": "1.18.0", "author": { "name": "Anton Babenko", "url": "https://github.com/antonbabenko" }, - "homepage": "https://github.com/antonbabenko/claude-delegator", - "repository": "https://github.com/antonbabenko/claude-delegator", + "homepage": "https://github.com/antonbabenko/deliberation", + "repository": "https://github.com/antonbabenko/deliberation", "license": "MIT", "keywords": ["delegation", "mcp", "codex", "gpt", "openai", "gemini", "antigravity", "agy", "google", "grok", "xai", "files", "experts", "subagents", "orchestration"] } diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 8c8a3a2..da77bd9 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -26,6 +26,13 @@ jobs: uses: actions/setup-node@v4 with: node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Typecheck + run: npm run typecheck - name: Run bridge tests run: node --test test/*.test.js diff --git a/CLAUDE.md b/CLAUDE.md index c780e8b..bb2961d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,13 +10,13 @@ A Claude Code plugin that provides GPT (via Codex CLI), Gemini 3 (via the Antigr ```bash # Test plugin locally (loads from working directory) -claude --plugin-dir /path/to/claude-delegator +claude --plugin-dir /path/to/deliberation # Run setup to test installation flow -/claude-delegator:setup +/deliberation:setup # Run uninstall to test removal flow -/claude-delegator:uninstall +/deliberation:uninstall ``` No build step, no dependencies. Codex exposes a native MCP server; Gemini, Grok, and OpenRouter use bundled zero-dependency Node bridges (`server/gemini/index.js`, `server/grok/index.js`, `server/openrouter/index.js`). The Gemini bridge wraps the Antigravity CLI (`agy`) in print mode. The OpenRouter bridge calls any OpenAI-compatible `/chat/completions` endpoint. @@ -25,7 +25,7 @@ No build step, no dependencies. Codex exposes a native MCP server; Gemini, Grok, ### Orchestration Flow -Claude acts as orchestrator—delegates to specialized experts based on task type. Supports both **single-shot** (independent calls) and **multi-turn** (context preserved via `threadId`). +Claude acts as orchestrator - delegates to specialized experts based on task type. Supports both **single-shot** (independent calls) and **multi-turn** (context preserved via `threadId`). ``` User Request → Claude Code → [Match trigger → Select expert & provider] @@ -44,7 +44,7 @@ User Request → Claude Code → [Match trigger → Select expert & provider] 1. **Match trigger** - Check `rules/triggers.md` for semantic patterns 2. **Read expert prompt** - Load from `prompts/[expert].md` 3. **Build 7-section prompt** - Use format from `rules/delegation-format.md` -4. **Call provider tool** - `mcp__codex__codex`, `mcp__gemini__gemini`, `mcp__grok__grok`, or `mcp__openrouter__openrouter` +4. **Call provider tool** - `mcp__deliberation-codex__codex`, `mcp__deliberation-gemini__gemini`, `mcp__deliberation-grok__grok`, or `mcp__deliberation-openrouter__openrouter` 5. **Synthesize response** - Never show raw output; interpret and verify ### The 7-Section Delegation Format @@ -62,11 +62,11 @@ Retries use multi-turn (`*-reply` with `threadId`) so the expert remembers previ | Component | Purpose | Notes | |-----------|---------|-------| -| `rules/*.md` | When/how to delegate | Installed to `~/.claude/rules/delegator/` | +| `rules/*.md` | When/how to delegate | Installed to `~/.claude/rules/deliberation/` | | `prompts/*.md` | Expert personalities | Injected via `developer-instructions` | | `commands/*.md` | Slash commands | `/setup`, `/uninstall` | | `config/providers.json` | Provider metadata | Not used at runtime | -| `~/.claude/claude-delegator/config.json` | OpenRouter model config | Live SSOT; stat-gated hot-reload | +| `~/.claude/deliberation/config.json` | OpenRouter model config | Live SSOT; stat-gated hot-reload | > Expert prompts adapted from [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) @@ -82,15 +82,15 @@ Retries use multi-turn (`*-reply` with `threadId`) so the expert remembers previ | **Researcher** | `prompts/researcher.md` | External libraries, docs, best practices | "how do I use X", "find examples of Y" | | **Debugger** | `prompts/debugger.md` | Root-cause analysis, minimal fixes | "why does this crash", "debug this failing test" | -Every expert can operate in **advisory** (`sandbox: read-only`) or **implementation** (`sandbox: workspace-write`) mode based on the task. OpenRouter models are always advisory - per-model expert eligibility is controlled by the `experts` field in `~/.claude/claude-delegator/config.json`. +Every expert can operate in **advisory** (`sandbox: read-only`) or **implementation** (`sandbox: workspace-write`) mode based on the task. OpenRouter models are always advisory - per-model expert eligibility is controlled by the `experts` field in `~/.claude/deliberation/config.json`. ## Grok file access -Grok reads attached files via `files[]` and resolves them under `roots[]` (top-level array of absolute directories) or `cwd`. `path` and `dir` entries take an optional `mode: "auto" | "inline" | "upload"` — inline embeds the file as `input_text` so Grok reads it line-by-line (best for source code); upload routes through the xAI Files API and is SHA-256 dedup-cached locally. `file_id` / `file_url` entries pass through unchanged and do not accept `mode`. Directory expansion via `{dir}` entries. See **[TECHNICAL.md: Grok files and cleanup](TECHNICAL.md#grok-files-and-cleanup)** for parameters, the inline-vs-upload tradeoff, cross-repo usage, cache layout, and the `gc` cleanup subcommand. +Grok reads attached files via `files[]` and resolves them under `roots[]` (top-level array of absolute directories) or `cwd`. `path` and `dir` entries take an optional `mode: "auto" | "inline" | "upload"` - inline embeds the file as `input_text` so Grok reads it line-by-line (best for source code); upload routes through the xAI Files API and is SHA-256 dedup-cached locally. `file_id` / `file_url` entries pass through unchanged and do not accept `mode`. Directory expansion via `{dir}` entries. See **[TECHNICAL.md: Grok files and cleanup](TECHNICAL.md#grok-files-and-cleanup)** for parameters, the inline-vs-upload tradeoff, cross-repo usage, cache layout, and the `gc` cleanup subcommand. ## Key Design Decisions -1. **Native & Bridge MCP** - Codex has a native `mcp-server` command. Gemini requires a bundled bridge (`server/gemini/index.js`) that wraps the Antigravity CLI (`agy`) in print mode. Grok has no MCP or CLI server mode, so a bundled bridge (`server/grok/index.js`) wraps the xAI **Responses API** (`/v1/responses`) directly - advisory-only (no file editing), but it can READ attached files (`files:[{path|file_id|file_url|dir}]`, optional `roots[]`, per-entry `mode` for upload-vs-inline delivery); uploaded files are SHA-256 dedup-cached locally, auto-expire (7-day default, `GROK_FILE_TTL_SECONDS`), and are managed with `/grok-files` (`server/grok/files-admin.js`: `list`/`prune`/`gc`). Details in [TECHNICAL.md § Grok files and cleanup](TECHNICAL.md#grok-files-and-cleanup). OpenRouter uses a bundled bridge (`server/openrouter/index.js`) that calls any OpenAI-compatible `POST {apiBase}/chat/completions` endpoint - advisory-only, text-inline file attachment only (`{path}`/`{dir}`; no upload path), config-driven via `~/.claude/claude-delegator/config.json`. Details in [TECHNICAL.md § OpenRouter bridge](TECHNICAL.md#openrouter-bridge). +1. **Native & Bridge MCP** - Codex has a native `mcp-server` command. Gemini requires a bundled bridge (`server/gemini/index.js`) that wraps the Antigravity CLI (`agy`) in print mode. Grok has no MCP or CLI server mode, so a bundled bridge (`server/grok/index.js`) wraps the xAI **Responses API** (`/v1/responses`) directly - advisory-only (no file editing), but it can READ attached files (`files:[{path|file_id|file_url|dir}]`, optional `roots[]`, per-entry `mode` for upload-vs-inline delivery); uploaded files are SHA-256 dedup-cached locally, auto-expire (7-day default, `GROK_FILE_TTL_SECONDS`), and are managed with `/grok-files` (`server/grok/files-admin.js`: `list`/`prune`/`gc`). Details in [TECHNICAL.md § Grok files and cleanup](TECHNICAL.md#grok-files-and-cleanup). OpenRouter uses a bundled bridge (`server/openrouter/index.js`) that calls any OpenAI-compatible `POST {apiBase}/chat/completions` endpoint - advisory-only, text-inline file attachment only (`{path}`/`{dir}`; no upload path), config-driven via `~/.claude/deliberation/config.json`. Details in [TECHNICAL.md § OpenRouter bridge](TECHNICAL.md#openrouter-bridge). 2. **Single-shot + multi-turn** - Single-shot for advisory (full context per call), multi-turn via `threadId` for chained implementation and retries 3. **Dual mode** - Any expert can advise or implement based on task 4. **Synthesize, don't passthrough** - Claude interprets expert output, applies judgment diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1494652..b915875 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to claude-delegator +# Contributing to deliberation Contributions welcome. This document covers how to contribute effectively. @@ -8,15 +8,15 @@ Contributions welcome. This document covers how to contribute effectively. ```bash # Clone the repo -git clone https://github.com/antonbabenko/claude-delegator -cd claude-delegator +git clone https://github.com/antonbabenko/deliberation +cd deliberation # Run `claude` and install plugin in Claude Code claude -/claude-delegator:setup +/deliberation:setup # Or test your changes locally without reinstalling -claude --plugin-dir /path/to/claude-delegator +claude --plugin-dir /path/to/deliberation ``` --- @@ -36,7 +36,7 @@ claude --plugin-dir /path/to/claude-delegator ## Project Structure ``` -claude-delegator/ +deliberation/ ├── .claude-plugin/ # Plugin manifest │ └── plugin.json ├── commands/ # Slash commands (/setup, /uninstall) @@ -53,7 +53,7 @@ claude-delegator/ ### Before Submitting -1. **Test your changes** - Run `/claude-delegator:setup` and verify +1. **Test your changes** - Run `/deliberation:setup` and verify 2. **Update docs** - If you change behavior, update relevant docs 3. **Keep commits atomic** - One logical change per commit @@ -94,7 +94,7 @@ You never bump versions by hand. 3. It opens a `chore(release): vX.Y.Z` PR that updates `version.json`, `CHANGELOG.md`, and the synced manifests, then auto-merges it once the `validate` check passes. 4. On merge, a second workflow tags `vX.Y.Z` and publishes the GitHub Release. -5. The `antonbabenko/agent-plugins` marketplace then re-pins `claude-delegator` to the new +5. The `antonbabenko/agent-plugins` marketplace then re-pins `deliberation` to the new release (immediately if its dispatch token is set, otherwise within a day via cron). `version.json` is the single source of truth. `.claude-plugin/plugin.json`, @@ -163,8 +163,8 @@ check fails if they drift. After changes, verify with actual MCP calls: 1. Install the plugin in Claude Code -2. Run `/claude-delegator:setup` -3. Verify MCP tools are available (`mcp__codex__codex`) +2. Run `/deliberation:setup` +3. Verify MCP tools are available (`mcp__deliberation-codex__codex`) 4. Test MCP tool calls via oracle delegation 5. Verify responses are properly synthesized 6. Test error cases (timeout, missing CLI) diff --git a/README.md b/README.md index bba3b05..d924f15 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Claude Delegator +# Deliberation Get a second opinion in Claude Code from GPT, Gemini, and Grok - plus 300+ more models through OpenRouter, including Qwen, Kimi, and DeepSeek. Seven domain experts (Architect, Code Reviewer, Security Analyst, and four more) review your plans, find bugs, and debate edge cases until they agree. @@ -29,7 +29,7 @@ When three models argue, the real bug reveals itself. Round 1 = independent top -## What is Claude Delegator? +## What is Deliberation? Claude can ask GPT, Gemini, Grok, or any OpenAI-compatible model (via OpenRouter) for help through MCP. The plugin handles the wiring for each provider so you just write the prompt. @@ -37,7 +37,7 @@ Each expert has a distinct specialty and can advise or implement. You can use any subset of the providers. The plugin detects which are configured and routes accordingly. OpenRouter is advisory-only and config-driven: models are declared in -`~/.claude/claude-delegator/config.json` and hot-reload without restarting Claude Code. +`~/.claude/deliberation/config.json` and hot-reload without restarting Claude Code. | What you get | Why it matters | |--------------|----------------| @@ -58,12 +58,12 @@ Inside a Claude Code instance, run: **2. Install the plugin** ``` -/plugin install claude-delegator@antonbabenko +/plugin install deliberation@antonbabenko ``` **3. Run setup** ``` -/claude-delegator:setup +/deliberation:setup ``` Claude now routes complex tasks to your GPT, Gemini, Grok, and OpenRouter experts (Grok and OpenRouter advise; GPT and Gemini can also implement). @@ -92,7 +92,7 @@ You need at least one provider: - **Codex CLI** (GPT): `npm install -g @openai/codex`, then `codex login`. - **Antigravity CLI**: [Getting Started with Antigravity CLI](https://antigravity.google/docs/cli-getting-started) and [Migrating from Gemini CLI](https://antigravity.google/docs/gcli-migration), then run `agy` and login. - **Grok (xAI)**: no CLI to install; the bridge ships with the plugin (needs Node 18+). Set `XAI_API_KEY` (get a key at https://console.x.ai). -- **OpenRouter**: no CLI; the bridge ships with the plugin (needs Node 18+). Set `OPENROUTER_API_KEY` (get a key at https://openrouter.ai/keys), then declare models in `~/.claude/claude-delegator/config.json`. Works with any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, HuggingFace Inference) - auth is skipped automatically when the key env var is empty. +- **OpenRouter**: no CLI; the bridge ships with the plugin (needs Node 18+). Set `OPENROUTER_API_KEY` (get a key at https://openrouter.ai/keys), then declare models in `~/.claude/deliberation/config.json`. Works with any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, HuggingFace Inference) - auth is skipped automatically when the key env var is empty. ## Commands @@ -100,15 +100,15 @@ Bundled with the plugin (available once installed): | Command | Purpose | |---------|---------| -| `/claude-delegator:setup` | Configure Codex/Gemini/Grok/OpenRouter MCP servers + orchestration rules | -| `/claude-delegator:consensus` | 🔥🔥🔥 Arbiter-mediated GPT + Gemini + Grok + Claude convergence loop | -| `/claude-delegator:ask-all` | 🔥 GPT + Gemini + Grok (+ configured OpenRouter models) in parallel, synthesized | -| `/claude-delegator:ask-gpt` | One-shot GPT (Codex) second opinion | -| `/claude-delegator:ask-gemini` | One-shot Gemini second opinion | -| `/claude-delegator:ask-grok` | One-shot Grok (xAI) second opinion (advisory-only) | -| `/claude-delegator:ask-openrouter` | One-shot OpenRouter model second opinion (advisory-only) | -| `/claude-delegator:uninstall` | Remove MCP config, rules, and aliases | -| `/claude-delegator:grok-files` | List, prune, or gc Grok-uploaded files (storage + local cache cleanup) | +| `/deliberation:setup` | Configure Codex/Gemini/Grok/OpenRouter MCP servers + orchestration rules | +| `/deliberation:consensus` | 🔥🔥🔥 Arbiter-mediated GPT + Gemini + Grok + Claude convergence loop | +| `/deliberation:ask-all` | 🔥 GPT + Gemini + Grok (+ configured OpenRouter models) in parallel, synthesized | +| `/deliberation:ask-gpt` | One-shot GPT (Codex) second opinion | +| `/deliberation:ask-gemini` | One-shot Gemini second opinion | +| `/deliberation:ask-grok` | One-shot Grok (xAI) second opinion (advisory-only) | +| `/deliberation:ask-openrouter` | One-shot OpenRouter model second opinion (advisory-only) | +| `/deliberation:uninstall` | Remove MCP config, rules, and aliases | +| `/deliberation:grok-files` | List, prune, or gc Grok-uploaded files (storage + local cache cleanup) | `/setup` can also install short aliases (`/ask-gpt`, `/ask-gemini`, `/ask-grok`, `/ask-all`, `/consensus`, `/grok-files`) into `~/.claude/commands/`. This is opt-in. Existing same-named commands are kept by default; setup asks before overwriting any of them. `/uninstall` removes an alias only if it is byte-identical to the bundled copy. @@ -202,8 +202,8 @@ Every expert supports two modes, chosen automatically from your request: ### OpenRouter config -OpenRouter models are declared in `~/.claude/claude-delegator/config.json` -(override path with `CLAUDE_DELEGATOR_CONFIG`). The file is the live single source of +OpenRouter models are declared in `~/.claude/deliberation/config.json` +(override the path with `DELIBERATION_CONFIG`). The file is the live single source of truth: changes to the `openrouter` block hot-reload without restarting Claude Code. Toggling a built-in provider (codex / gemini / grok) still requires `/setup`. @@ -262,6 +262,26 @@ see [TECHNICAL.md - OpenRouter bridge](TECHNICAL.md#openrouter-bridge). For provider defaults, environment variables, and manual MCP setup, see [TECHNICAL.md](TECHNICAL.md#environment-variables). +## Upgrade from 1.x (claude-delegator -> deliberation) + +2.0 renames the plugin and drops 1.x compatibility. One-time steps: + +1. Move your config: `mv ~/.claude/claude-delegator ~/.claude/deliberation` (or set + `DELIBERATION_CONFIG` to a custom path; `CLAUDE_DELEGATOR_CONFIG` is no longer read). +2. Re-run `/deliberation:setup` to register the renamed MCP servers. The old bare + `codex`/`gemini`/`grok`/`openrouter` registrations are not auto-removed. If you had them, + remove each one (the CLI takes one name per call): + ``` + claude mcp remove --scope user codex + claude mcp remove --scope user gemini + claude mcp remove --scope user grok + claude mcp remove --scope user openrouter + ``` +3. Slash commands moved from `/claude-delegator:*` to `/deliberation:*` (the short aliases + `/ask-gpt` etc. are unchanged). +4. Optional cleanup: `rm -rf ~/.claude/rules/delegator ~/.claude/cache/claude-delegator`. +5. Restart Claude Code. + ## Author Maintained by Anton Babenko - [LinkedIn](https://linkedin.com/in/antonbabenko), [X/Twitter](https://x.com/antonbabenko). @@ -272,7 +292,7 @@ Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, ## Credits -Claude Delegator started as a fork of [jarrodwatts/claude-delegator](https://github.com/jarrodwatts/claude-delegator) - credit to Jarrod Watts for the original solution and inspiration. Original work and MIT copyright are retained. This fork adds Grok support, Gemini bridge reliability (timeout and trust recovery), provider configuration overrides, and the bundled delegation commands. It is not an official continuation of the upstream project. +Deliberation started as a fork of [jarrodwatts/claude-delegator](https://github.com/jarrodwatts/claude-delegator) - credit to Jarrod Watts for the original solution and inspiration. Original work and MIT copyright are retained. This fork adds Grok support, Gemini bridge reliability (timeout and trust recovery), provider configuration overrides, and the bundled delegation commands. It is not an official continuation of the upstream project. Expert prompts are adapted from [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) (snapshot `03eb9fff`, 2026-05-25) and [PAL MCP server](https://github.com/BeehiveInnovations/pal-mcp-server) (Apache-2.0, snapshot `7afc7c1`, 2026-05-25). diff --git a/TECHNICAL.md b/TECHNICAL.md index 3e1f8f4..ef341b8 100644 --- a/TECHNICAL.md +++ b/TECHNICAL.md @@ -1,6 +1,6 @@ # Technical Reference -Advanced and internal details for Claude Delegator. For install and everyday use, +Advanced and internal details for Deliberation. For install and everyday use, see the [README](README.md). This document covers the provider bridges, the full environment-variable reference, manual MCP setup, multi-turn and retry behavior, and the Gemini recovery paths. @@ -44,9 +44,9 @@ Claude: detects a security question, selects the Security Analyst | v +-------------------------------------+ - | mcp__codex__codex / | - | mcp__gemini__gemini / | - | mcp__grok__grok | + | mcp__deliberation-codex__codex / | + | mcp__deliberation-gemini__gemini / | + | mcp__deliberation-grok__grok | | -> Security Analyst prompt | | -> expert analyzes your code | +-------------------------------------+ @@ -116,7 +116,7 @@ it can read context to advise but cannot mutate the real workspace, even under A bundled zero-dependency Node bridge over the xAI Responses API (`/v1/responses`). It is advisory-only (it cannot edit files) but it can read attached files: pass `files: [{ path | file_id | file_url | dir }]` and the -bridge delivers them per the `mode` setting — uploaded to the xAI Files API +bridge delivers them per the `mode` setting - uploaded to the xAI Files API (default), inlined as `input_text` (for line-by-line reading of source files), or expanded via the bundled glob walker for directories. Resolution is against the top-level `roots: string[]` (first-root-wins) or `cwd` when `roots` is @@ -147,8 +147,8 @@ Codex has no bridge environment variables: it ships its own native MCP server an reads `~/.codex/config.toml` directly. The **model** comes from the `model` key in that file by default (the Codex analog of `GEMINI_DEFAULT_MODEL` / `GROK_DEFAULT_MODEL`). Override it on the server with `-c model=` on the -`claude mcp add ... codex` registration, or per call with the `model` parameter of -`mcp__codex__codex(...)`. See [Configuration in the README](README.md#configuration). +`claude mcp add ... deliberation-codex` registration, or per call with the `model` parameter of +`mcp__deliberation-codex__codex(...)`. See [Configuration in the README](README.md#configuration). ## Manual MCP setup @@ -224,7 +224,7 @@ budget is exhausted, the call fails with `errorKind: "timeout"` (still Grok reads attached files via the `files[]` parameter. Each entry has EXACTLY ONE of: -- `path` - a local file. Delivery is controlled by `mode` (default `"upload"` — bridge uploads to the xAI Files API; `"inline"` embeds as `input_text`; `"auto"` picks per heuristic — see "Inline vs upload delivery" below). +- `path` - a local file. Delivery is controlled by `mode` (default `"upload"` - bridge uploads to the xAI Files API; `"inline"` embeds as `input_text`; `"auto"` picks per heuristic - see "Inline vs upload delivery" below). - `file_id` - an already-uploaded xAI file id (passed through, no upload). - `file_url` - a public URL (passed through). - `dir` - a local directory expanded recursively. Same `mode` rules; the walker @@ -239,7 +239,7 @@ that escape via `realpath` are also refused. An oversize file (>48 MB) returns ### Cross-repo example ```js -mcp__grok__grok({ +mcp__deliberation-grok__grok({ prompt: "Compare the auth strategy in these two services.", cwd: "/Users/me/work/service-a", roots: ["/Users/me/work/service-a", "/Users/me/work/service-b"], @@ -319,7 +319,7 @@ Uploads are deduplicated by SHA-256 content hash. A reuse hit requires the SAME (see cache-key below); identical bytes uploaded under a different filename or a different key produce separate cache rows: -- Cache file: `~/.claude/cache/claude-delegator/grok-files.json` +- Cache file: `~/.claude/cache/deliberation/grok-files.json` - Cache key: `sha256(bytes)@sha256(XAI_API_KEY)[:16]@normalize(apiBase)@effectiveFilename` - Key rotation auto-invalidates entries (different `keyFp`). - Different `apiBase` (including port/protocol differences) → separate rows. @@ -338,7 +338,7 @@ key produce separate cache rows: known file id are surfaced unchanged. - `XAI_DISABLE_FILE_CACHE=1` (env) skips the cache layer entirely (debugging). -Stored upload filenames are `claude-delegator-{sha256[:16]}-{basename}`. Uploads also +Stored upload filenames are `deliberation-{sha256[:16]}-{basename}`. Uploads also carry `expires_after` set by `GROK_FILE_TTL_SECONDS` (default `604800` = 7 days, clamped 1h..30d). @@ -346,7 +346,7 @@ clamped 1h..30d). The bundled `server/grok/files-admin.js` supports three subcommands: -- `list` - shows total xAI file count and every `claude-delegator-*` upload. +- `list` - shows total xAI file count and every `deliberation-*` upload. - `prune --older-than <30m|24h|7d|seconds> [--yes]` - dry run by default; deletes **remote** bridge-owned files matched by filename prefix + age. Works without the local cache; safe for environments where the cache was lost or never existed. @@ -358,7 +358,7 @@ The bundled `server/grok/files-admin.js` supports three subcommands: files). `--force-local-prune` drops ambiguous foreign rows anyway. `prune` and `gc` are complementary: `prune` is the remote-side cleaner; `gc` keeps -the local cache aligned with remote state. The `claude-delegator-` filename prefix +the local cache aligned with remote state. The `deliberation-` filename prefix is a hard safety invariant on both paths - your own xAI files are never touched. ## OpenRouter bridge @@ -370,8 +370,8 @@ It is **advisory-only** - it cannot edit files or run shell commands. ### Configuration file The bridge and the fan-out commands (`/ask-all`, `/consensus`) read -`~/.claude/claude-delegator/config.json` at call time. Override the path with -`CLAUDE_DELEGATOR_CONFIG`. The file is stat-gated: the bridge re-reads it only when +`~/.claude/deliberation/config.json` at call time. Override the path with +`DELIBERATION_CONFIG`. The file is stat-gated: the bridge re-reads it only when the mtime changes, so edits to the `openrouter` block (models, flags, defaults) take effect immediately without restarting Claude Code or re-running `/setup`. Toggling a **built-in** provider (codex / gemini / grok) still requires `/setup` to re-register @@ -440,7 +440,7 @@ rounds; you want the models reasoning, not improvising. for the requested expert; capped to `maxFanout` models (default 3). - **`/consensus`**: includes models where `consensus === true`; NOT subject to `maxFanout`. A warning is logged when more than 3 models enter a consensus round (cost). -- **`openrouter-default`** is the reserved alias for the bare `mcp__openrouter__openrouter` +- **`openrouter-default`** is the reserved alias for the bare `mcp__deliberation__openrouter` call and `/ask-openrouter` with no alias specified. It is the single-shot fallback only and is never included in fan-out or consensus. - Implementation tasks always route to Codex or Gemini, never to OpenRouter. @@ -454,7 +454,7 @@ valid delegate and collects the bad ones into `invalidModels`. Only **top-level/ problems hard-fail the whole config: malformed JSON, a non-object root, an unsupported `version`, or a non-integer/`< 1` `maxFanout`. -`mcp__openrouter__openrouter-list` returns: +`mcp__deliberation__openrouter-list` returns: ```jsonc { @@ -511,7 +511,7 @@ Exceeding either cap returns a hard error with counts. ### Session model persistence -A model alias is bound at the start of a session via `mcp__openrouter__openrouter` +A model alias is bound at the start of a session via `mcp__deliberation__openrouter` and is preserved for the life of that `threadId`. `-reply` calls on the same thread always use the same model. @@ -525,9 +525,9 @@ token count. There is no hard spend cap - the warning is informational only. | Tool | Purpose | |------|---------| -| `mcp__openrouter__openrouter` | Start a new advisory session | -| `mcp__openrouter__openrouter-reply` | Continue a session (multi-turn via threadId) | -| `mcp__openrouter__openrouter-list` | List configured model aliases and their eligibility flags | +| `mcp__deliberation__openrouter` | Start a new advisory session | +| `mcp__deliberation__openrouter-reply` | Continue a session (multi-turn via threadId) | +| `mcp__deliberation__openrouter-list` | List configured model aliases and their eligibility flags | ### Error kinds diff --git a/assets/consensus-flow-simple.html b/assets/consensus-flow-simple.html index 0740751..47fa973 100644 --- a/assets/consensus-flow-simple.html +++ b/assets/consensus-flow-simple.html @@ -2,7 +2,7 @@ - How /consensus works (simple) — claude-delegator + How /consensus works (simple) - deliberation