Skip to main content
plugin CX Codex

codex-claude-council — Claude Code plugin: what it does

codex-claude-council asks Claude and ChatGPT the same question, then lets them debate across multiple rounds until both reach agreement.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-claude-council@awesome-codex-plugins
Open on GitHub

What codex-claude-council does

The plugin runs a council between Claude Code and ChatGPT via the Codex CLI. Both agents draft independent answers first, review each other's points, and continue round-by-round discussions until they settle on a shared conclusion.

Council members inspect your local workspace strictly in read-only mode. They read source files, run searches, and execute harmless commands such as git log and git diff, without permission to modify files.

The tool requires Node.js 20 or newer. It uses your existing logged-in CLI accounts by default, though you can supply standard API keys instead.

What it helps with

  • resolve technical debates between alternative database index designs
  • verify complicated architectural choices using two distinct AI providers
  • audit git differences with a second opinion without altering local files

Example prompts for the agent

  • Should we choose BIGINT identity or UUIDv7 for primary keys here?
  • Review this error-handling design and debate the edge cases
  • Cross-check our migration plan against current documentation

How to install codex-claude-council

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-claude-council@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about codex-claude-council

How to install codex-claude-council in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then run /plugin install codex-claude-council@awesome-codex-plugins.

What does codex-claude-council do?

It orchestrates a multi-turn discussion between ChatGPT and Claude until both models converge on a single consensus answer.

Are API keys mandatory to run the council?

No, API keys are optional. The council can run directly through your existing signed-in Codex and Claude Code CLI subscriptions.

Source text

codex-claude-council · MIT
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
  <img alt="Codex-Claude Council: ChatGPT and Claude discuss with each other until they agree" src="assets/banner-light.svg" width="100%">
</picture>

<p align="center">
  <a href="https://github.com/hamza-aziz-ai/codex-claude-council/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/hamza-aziz-ai/codex-claude-council/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://www.npmjs.com/package/codex-claude-council"><img alt="npm" src="https://img.shields.io/npm/v/codex-claude-council?color=CB3837"></a>
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  <img alt="Node 20+" src="https://img.shields.io/badge/node-20%2B-brightgreen">
  <img alt="API keys optional" src="https://img.shields.io/badge/API%20keys-optional-D97757">
</p>
<p align="center">
  <a href="https://smithery.ai/servers/hamza-aziz-ai/codex-claude-council"><img alt="Smithery: 98/100" src="https://img.shields.io/badge/Smithery-98%2F100-FF5601"></a>
  <a href="https://github.com/hashgraph-online/hol-guard"><img alt="HOL Plugin Scanner: 95/100" src="https://img.shields.io/badge/HOL%20Plugin%20Scanner-95%2F100-2E7D32"></a>
  <a href="https://tdqs.dev/reports/dbtjn020iu"><img alt="TDQS" src="https://tdqs.dev/reports/dbtjn020iu/badge.svg"></a>
  <a href="https://m8ven.ai/mcp/hamza-aziz-ai/codex-claude-council"><img alt="M8ven Score" src="https://m8ven.ai/badge/mcp/hamza-aziz-ai/codex-claude-council"></a>
  <a href="https://aiagentslisting.com/mcp/codex-claude-council"><img alt="Codex Claude Council MCP score on AI Agents Listing" src="https://aiagentslisting.com/codex-claude-council/badge.svg?variant=score"></a>
  <a href="https://github.com/Appnova-EU-OU/awesome-remote-mcp-servers"><img alt="Listed on awesome-remote-mcp-servers" src="https://img.shields.io/badge/Listed_on-awesome--remote--mcp--servers-blue?logo=github"></a>
</p>
<p align="center">
  <a href="https://glama.ai/mcp/servers/hamza-aziz-ai/codex-claude-council"><img width="380" height="200" alt="Codex–Claude Council on Glama" src="https://glama.ai/mcp/servers/hamza-aziz-ai/codex-claude-council/badges/card.svg"></a>
  <a href="https://mcprush.com/to/codex-claude-council-mcp?ref=badge"><img width="380" height="200" alt="Codex–Claude Council on MCPRush" src="https://mcprush.com/badge/codex-claude-council-mcp/card.svg"></a>
</p>
<p align="center">
  <a href="https://aiagentslisting.com/mcp/codex-claude-council"><img width="200" height="50" alt="Codex–Claude Council on AI Agents Listing" src="https://aiagentslisting.com/codex-claude-council/badge.svg?claim=df6787ce44b7957dda33ffd902293f93"></a>
</p>
<p align="center">
  Also in the <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hamza-aziz-ai/codex-claude-council">MCP Registry</a>, on <a href="https://smithery.ai/servers/hamza-aziz-ai/codex-claude-council">Smithery</a>, <a href="https://www.npmjs.com/package/codex-claude-council">npm</a>, <a href="https://github.com/hamza-aziz-ai/codex-claude-council/pkgs/container/codex-claude-council">GHCR</a> and <a href="https://hub.docker.com/r/hamzaazizai/codex-claude-council">Docker Hub</a>.
</p>

<h2 align="center">Two AIs. One answer.</h2>

<h3 align="center">Ask <b>ChatGPT</b> (through Codex) and <b>Claude</b> the same question.<br>They discuss with each other, round after round, until they agree on one answer.</h3>

<p align="center">
  In <b>Claude Code</b> · <b>Claude Desktop</b> · <b>Codex</b> · the <b>ChatGPT desktop app</b> · <b>claude.ai</b> and your phone · your <b>terminal</b>, on Windows, macOS and Linux.<br>
  On the plans you already have, or with API keys.
</p>

<p align="center">
  <a href="#get-started"><b>Get started</b></a> ·
  <a href="#use-it"><b>Use it</b></a> ·
  <a href="#how-it-works"><b>How it works</b></a> ·
  <a href="#setups"><b>Setups</b></a> ·
  <a href="#examples-and-best-practices"><b>Guides</b></a> ·
  <a href="#reference"><b>Reference</b></a> ·
  <a href="#troubleshooting"><b>Troubleshooting</b></a>
</p>

<table>
  <tr>
    <td width="50%" valign="top">🔍 <b>Both work in your project, read-only</b><br>They read files, search and run read-only commands such as <code>git log</code> and <code>git diff</code>, but neither can change anything.</td>
    <td width="50%" valign="top">🌐 <b>With the web</b><br>Both check current versions, APIs and docs instead of relying on memory.</td>
  </tr>
  <tr>
    <td valign="top">🔁 <b>With the sessions you choose</b><br>New sessions, your existing Claude Code and Codex sessions (with everything they already know), or the session you are asking from as one of the two members.</td>
    <td valign="top">🧰 <b>With your own setup</b><br>Your skills, plugins, MCP servers and <code>CLAUDE.md</code> / <code>AGENTS.md</code> apply to both. Skills such as <a href="https://github.com/aiwithremy/claude-skills-llm-council">llm-council</a> or <a href="https://github.com/JuliusBrussee/caveman">caveman</a> on request.</td>
  </tr>
  <tr>
    <td valign="top">🔑 <b>Your plans, or API keys</b><br>Your own Codex CLI (signed in with ChatGPT) and Claude Code (signed in with your Claude plan), by default. Or give a side its API key, even with no CLI installed.</td>
    <td valign="top">📱 <b>From anywhere</b><br>On your computer through the plugin, in Claude Desktop through its extension, or online for claude.ai, ChatGPT and your phone, from your computer or a server (Docker).</td>
  </tr>
</table>

<p align="center">
  <img src="assets/demo.gif" width="100%" alt="A real council in the terminal: asked whether to use UUIDv7 or integer primary keys, ChatGPT and Claude both disagree for two exchanges, Claude agrees in the third, ChatGPT in the fourth, and they answer: choose BIGINT identity, with UUIDv7 only for offline or decentralized ID generation.">
  <br><sub>A real council (low effort, the wait cut out): they disagree for two exchanges, then converge on one answer. Recorded with <a href="assets/demo.tape"><code>assets/demo.tape</code></a>.</sub>
</p>

## Get started

**1. Add it where you ask:**

| Where you ask | Add it with | Details |
|---|---|---|
| **Claude Code, Codex** (CLI and IDE extension) | `npx -y codex-claude-council install`, then restart them | [Install](#install) |
| **Claude Desktop** | its extension: open [`codex-claude-council-<version>.mcpb`](https://github.com/hamza-aziz-ai/codex-claude-council/releases/latest), with API keys in its settings if you want | [Claude Desktop extension](#claude-desktop-extension) |
| **ChatGPT desktop app** | **Settings → Plugins → Add → + Add a marketplace**: `https://github.com/hamza-aziz-ai/codex-claude-council.git` | [Or install per app](#or-install-per-app) |
| **claude.ai, ChatGPT on the web, your phone** | `npx -y codex-claude-council serve --tunnel`, or the Docker image on a server, then add the URL as a connector | [Use it online](#use-it-online-claudeai-chatgpt-your-phone) |
| **Cursor, VS Code, Windsurf, any MCP client** | a stdio server: `npx -y codex-claude-council mcp` | [JSON config](#or-install-per-app) |
| **Your terminal** | `npx -y codex-claude-council ask "…"` | [From the terminal](#from-the-terminal) |

**2. Choose how each side runs** (separately for ChatGPT and Claude):

| | Needs | Pays with |
|---|---|---|
| **Its CLI, on your plan** (default) | [Codex CLI](https://developers.openai.com/codex/cli) signed in with ChatGPT / [Claude Code](https://code.claude.com/docs/en/setup) signed in with your Claude plan | your ChatGPT or Claude plan |
| **Its CLI, on an API key** | the CLI, signed in with an API key | per token: [API keys instead of a plan](#api-keys-instead-of-a-plan) |
| **Its API, no CLI** | only an OpenAI or Anthropic API key | per token: [Without the CLIs](#without-the-clis-through-the-apis) |

Mix freely: for example Claude Code on your Claude plan, with ChatGPT through an OpenAI API key. `npx -y codex-claude-council doctor` checks what you have.

**3. Ask**, in a project: *"Ask the council: what does this project do, and what would you improve first?"*

> [!TIP]
> Already in a session of one model? Say *"discuss with my Codex session 019a…"* (in Claude Code) and your session takes part itself, with everything it already knows. See [`council_join`](#take-part-yourself-council_join).

## Use it

Just ask in plain language. The host (the app you are asking in) picks the tool and fills in its inputs:

| You say | What runs |
|---|---|
| "Ask the council: should I use Postgres or MongoDB for this?" | `council_ask`: both answer, then reply to each other until they agree on one final answer |
| "Run a council **debate** on this migration plan." | `council_debate`: the final answer plus both answers, every exchange and the final check |
| "Get **Codex's** second opinion on this function." | `council_ask_codex` (or `council_ask_claude` for Claude alone) |
| "**Discuss with my Codex session 019a…** whether this refactor is safe." (asked in Claude Code) | `council_join`: this session takes part itself; Codex continues session 019a… |
| "Ask the council, continuing **my Claude session 3f2a…** and **my Codex session "auth refactor"**: is my plan sound?" | `council_ask` with `claude_session_id` and `codex_session_id` |
| "Council this with **ChatGPT on gpt-5.6-sol at xhigh** and **Claude on opus at max**: …" | `council_ask` with per-side model and effort |
| "Ask the council and **keep going until they agree**: …" | `council_ask` with `max_rounds: 0` |
| "Ask the council, and let **ChatGPT write the final answer**: …" | `council_ask` with `synthesizer: "codex"` |
| "Ask the council: is **the latest** Next.js release safe to upgrade to for our app?" | `council_ask`: both read the project and search the web |
| "Ask the council **without internet access**: …" | `council_ask` with `web_search: false` |
| "Ask the council, **using the llm-council and caveman skills**: …" | `council_ask` with `skill: "llm-council, caveman"` |

In a project, the host passes its folder as the `workspace`, and the models read what they need themselves: point them at files, functions, the failing test or the error rather than pasting whole files. They cannot see the host's conversation (unless the host takes part itself), so the host states the task and any context that is not in the project.

Apps that show MCP prompts (claude.ai and Claude Desktop, in their **+** menu) also offer three starters: `ask_council`, `second_opinion` and `debate`.

> [!NOTE]
> **Long runs.** A council takes several minutes: two calls for the answers, two per exchange and two for the final answer and its check, all counting against both plans (or keys). Some apps end a tool call after about 60 seconds (Claude Desktop does), so every tool returns within about 50 seconds, with the answer or with "still working", the current step and a `job_id`; the host then calls `council_result` until the answer is ready, while the council keeps running. `council_cancel` stops a job.

## How it works

```mermaid
flowchart LR
    Q[Your question] --> CA[Codex answers]
    Q --> LA[Claude answers]
    CA -- to Claude --> L1[Claude replies]
    LA -- to Codex --> C1[Codex replies]
    L1 -- to Codex --> C2[Codex replies]
    C1 -- to Claude --> L2[Claude replies]
    C2 & L2 --> V{Both agree?}
    V -- no: exchange again --> V
    V -- yes --> F[One writes the final answer, the other checks it]
```

1. **Answer**: both models answer on their own, without seeing each other.
2. **Exchange**: each model gets the other's latest message (first its answer, then its replies) and replies point by point: what it accepts and how its position changes, where it still disagrees and why, then its current answer and a verdict, `AGREE` or `DISAGREE`. The two replies cross over, and the exchange repeats: a crossed zig-zag that narrows round after round.
3. **Converge**: as soon as both say `AGREE` in the same exchange, one model writes the final answer and the other checks that it matches what they agreed (at most 5 exchanges by default; `max_rounds: 0` for no limit).
4. **No agreement**: if the limit is reached first, the final answer sets out what they agree on and each point still in dispute, with both positions.

Neither model leads the discussion: in every exchange both reply to each other at the same time, and only after they agree does one of them write the final text. Each model keeps its session between questions, so it remembers the discussion and what it has already read, and each prompt carries only what that model has not seen yet.

### Why two models?

One model answers with confidence, right or wrong. Two models that disagree, and must explain why to each other, catch what either misses alone, the way a second reviewer does.

A real run (low effort): *"PostgreSQL or SQLite for a single-server internal tool with about 20 users?"*

| | ChatGPT | Claude |
|---|---|---|
| **Opening answer** | SQLite | PostgreSQL |
| **Exchange 1** | holds: "20 users alone does not establish write contention" | accepts most points and switches to SQLite, but keeps one objection |
| **Exchanges 2–3** | sharpens when PostgreSQL *would* be right | withdraws "multiple app instances" as a reason |
| **Exchange 4** | agrees | agrees |
| **Final check** | rejects the first final text (over the 120-word limit, one unsupported claim); accepts the revision | |

The final answer was sharper than either opening answer: SQLite, with the exact conditions under which to move to PostgreSQL. See the whole discussion as a page: [**open it**](https://htmlpreview.github.io/?https://github.com/hamza-aziz-ai/codex-claude-council/blob/main/docs/examples/postgres-or-sqlite.html) ([source](docs/examples/postgres-or-sqlite.html)) (make your own with `--html`, see [From the terminal](#from-the-terminal)).

### Benchmark

24 programs in which several traps interact (the [hard set](bench/hard.mjs): the event loop across nested promises and timers, class fields, `yield from`, `NULL` in joins, …), each asked *"what exactly does this print?"* and graded against what it really prints. Codex `gpt-6.1-sol` and Claude Sonnet 5.5, both at low effort, fresh sessions, no web search (October 13, 2026):

| | Right answers | Median time per question |
|---|---|---|
| Codex alone | 24 / 24 | 18 s |
| Claude alone | 23 / 24 | 11 s |
| **Council** | **24 / 24** | 59 s |

- **The council caught the one mistake:** on `h-py-dunder` Claude alone printed `V3 V102 V3 …`; the council printed the right `V3 V102 V102 …`, with both models agreeing.
- **It never made things worse:** there is no question the council got wrong that either model got right alone.
- **What it means:** here Codex alone was already perfect, so the council's gain is insurance. You get the better answer without knowing in advance which model will slip, at about 3 to 5 times the time. One miss in 24 is a small sample, not proof.

Every answer is in the [result file](bench/results/2026-10-13-03-15-hard-low.json). [Run it yourself](bench) with your own models and effort.

## Setups

### Requirements

| You need | Install | Sign in |
|---|---|---|
| [Node.js](https://nodejs.org) 20 or newer: runs the small MCP server (not needed for the Claude Desktop extension or Docker) | [nodejs.org](https://nodejs.org) | – |
| For Claude's side on your plan: [Claude Code CLI](https://code.claude.com/docs/en/setup), with a Claude Pro, Max, Team or Enterprise plan | macOS / Linux / WSL: `curl -fsSL https://claude.ai/install.sh \| bash`<br>Windows: `irm https://claude.ai/install.ps1 \| iex` | `claude auth login` |
| For ChatGPT's side on your plan: [Codex CLI](https://developers.openai.com/codex/cli), with a ChatGPT plan | any OS: `npm install -g @openai/codex`<br>macOS: `brew install --cask codex` | `codex login` → *Sign in with ChatGPT* |
| [Git](https://git-scm.com) (recommended) | usually already installed | – |

- **Each side needs its CLI, or its API key** ([Without the CLIs](#without-the-clis-through-the-apis)). Before each council, each side is checked, and nothing is sent until both are ready; the message says what is missing and how to fix it.
- **Git** lets both models look at your project's history, changes and blame, and `skill add` uses it to download a repository's skills.

> [!IMPORTANT]
> **Keep both CLIs up to date.** The council uses recent options: Claude Code's plan mode and `stream-json` output, and Codex's `exec resume` and web search. If a run fails with "unknown option" or "unexpected argument", update the CLI it names: `claude update`, or `npm install -g @openai/codex@latest`.

### Install

For Claude Code and Codex (the CLIs and their IDE extensions). Use one of these:

**macOS / Linux / WSL**

```bash
curl -fsSL https://raw.githubusercontent.com/hamza-aziz-ai/codex-claude-council/main/install.sh | bash
```

**Windows (PowerShell)**

```powershell
irm https://raw.githubusercontent.com/hamza-aziz-ai/codex-claude-council/main/install.ps1 | iex
```

**Any OS with Node.js**

```bash
npx -y codex-claude-council install
```

The installer checks Node.js and both CLIs (and whether each is signed in), then adds this repository's marketplace to Claude Code and Codex and installs the plugin in both (for Claude Code, for your user, so it works in every project). If the plugin is already installed, it updates it instead.

- **Options:** `--only claude|codex` (one app only), `--claude-desktop` (also register the server with Claude Desktop's Chat tab), `--dry-run` (show the commands without running them). With the scripts: `… | bash -s -- --claude-desktop`, or `& ([scriptblock]::Create((irm https://raw.githubusercontent.com/hamza-aziz-ai/codex-claude-council/main/install.ps1))) --claude-desktop`.
- **Afterwards:** fully quit and reopen Claude Code and Codex, check the setup with `npx -y codex-claude-council doctor`, and try it in a project.

#### Update

```bash
npx -y codex-claude-council update               # both apps
npx -y codex-claude-council update --only claude # or --only codex
```

It refreshes the marketplace and updates the plugin in Claude Code and Codex; then fully quit and reopen both. [`CHANGELOG.md`](CHANGELOG.md) lists what changed. In Claude Desktop, plugins update through **Sync automatically** (or **Sync** under **Settings → Plugins**); in the ChatGPT desktop app, under **Settings → Plugins**.

> [!WARNING]
> **Windows:** if Codex fails with *"failed to back up plugin cache entry: Access is denied. (os error 5)"*, a running app still has the plugin's folder open (versions up to 0.5.1 did this). Quit every Codex and Claude session, IDE extension and desktop app, then update again.

#### Or install per app

| App | How |
|---|---|
| **Claude Code** | `claude plugin marketplace add hamza-aziz-ai/codex-claude-council`<br>`claude plugin install codex-claude-council@codex-claude-council --scope user` |
| **Codex** (CLI and IDE extension) | `codex plugin marketplace add hamza-aziz-ai/codex-claude-council`<br>`codex plugin add codex-claude-council@codex-claude-council` |
| **Claude Desktop** (Cowork and Code) | **Settings → Customize → Plugins → + Add → Add marketplace → Add from a repository**, enter `hamza-aziz-ai/codex-claude-council`, turn **Sync automatically** on, click **Sync**, then install **codex-claude-council** |
| **Claude Desktop** (Chat, with the extension) | see [Claude Desktop extension](#claude-desktop-extension); or `npx -y codex-claude-council install --claude-desktop --only claude`, then fully quit and reopen Claude Desktop |
| **ChatGPT desktop app** | **Settings → Plugins → Add → + Add a marketplace**, enter `https://github.com/hamza-aziz-ai/codex-claude-council.git` in **Source**, click **Add marketplace**, then install **codex-claude-council** |
| **Any other MCP client** (Cursor, VS Code, Windsurf, …) | a local (stdio) MCP server with command `npx` and arguments `["-y", "codex-claude-council", "mcp"]` (below). Also in the [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hamza-aziz-ai/codex-claude-council) as `io.github.hamza-aziz-ai/codex-claude-council` |

For a client configured with JSON (Cursor's `mcp.json`, Windsurf, Claude Desktop's `claude_desktop_config.json`, …), paste:

```json
{
  "mcpServers": {
    "council": {
      "command": "npx",
      "args": ["-y", "codex-claude-council", "mcp"]
    }
  }
}
```

The council runs on your computer, so keep the app open while you use it.

### Claude Desktop extension

1. Open `codex-claude-council-<version>.mcpb` from the [latest release](https://github.com/hamza-aziz-ai/codex-claude-council/releases/latest) (or **Settings → Extensions → Install Extension…**). It includes everything the server needs.
2. **Optional, for a side without its CLI:** open **Settings → Extensions → Codex–Claude Council → Configure** and enter the partner model's key: an **OpenAI API key** for ChatGPT, an **Anthropic API key** for the Claude side, and a model for each if you like (empty: `gpt-6-astra`, `claude-opus-5-5`). A side with a key runs through its API; a side without one uses its CLI. Claude Desktop keeps the keys masked and passes them only to this server, which never passes them on to the CLIs.
3. Ask: "Ask ChatGPT: …" (one model), "Discuss with ChatGPT whether …" (`council_join`: Claude Desktop itself is the Claude member, so the OpenAI key alone is enough), or "Ask the council: …".

### Use it online: claude.ai, ChatGPT, your phone

Apps on the web and on phones reach MCP servers over HTTPS, from their providers' servers, so they can't start a local one. `serve --tunnel` puts the council's MCP server online from your computer. It needs [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (Windows: `winget install Cloudflare.cloudflared`, macOS: `brew install cloudflared`) and no Cloudflare account:

```bash
npx -y codex-claude-council serve --tunnel
```

It prints the URL, `https://<random words>.trycloudflare.com/mcp/<token>`. Add it as a custom connector, with no sign-in:

| App | Where |
|---|---|
| **claude.ai** (and the Claude apps on your phone and desktop) | **Settings → Connectors → Add custom connector**: a name, the URL, then **No sign-in** |
| **ChatGPT** | Turn on developer mode (**Settings → Apps → Advanced settings**), then create a connector with the URL |
| **Any other MCP client** | a remote MCP server with the URL (Streamable HTTP) |

- **Keep the URL secret.** The token in it is the only key: anyone with the URL can run the council on your computer, under your plans, and the members can read your files. It is generated on the first start and saved next to your config file (`serve-token`); delete that file for a new one, or set `--token` / `COUNCIL_TOKEN`.
- **Your computer is the server.** It must be on, with `serve` running. Questions about a project need its folder on that computer: name it in the question ("in the project at `~/code/app`").
- **The address changes** each time `serve --tunnel` starts (a quick tunnel); update the connector then, or use a [fixed address](#a-fixed-address-with-your-own-domain).
- **Options:** `--port` (default 8000), `--host` (default `127.0.0.1`). Without `--tunnel`, `serve` prints the local address, `http://127.0.0.1:8000/mcp/<token>`, for your own tunnel or reverse proxy.

#### With Docker Compose, in the background

The whole setup in one container that starts again by itself after a reboot: Node.js, both CLIs, cloudflared and `serve --tunnel`. On a server you control (a VPS or a home server, amd64 or arm64) or on your own computer with Docker Desktop. It is still your council: sign both CLIs in with your own accounts, for your own use. In an empty folder:

```bash
curl -fsSLO https://raw.githubusercontent.com/hamza-aziz-ai/codex-claude-council/main/compose.yaml
# Windows (PowerShell): irm https://raw.githubusercontent.com/hamza-aziz-ai/codex-claude-council/main/compose.yaml -OutFile compose.yaml
docker compose up -d
docker compose exec council codex-claude-council login   # once: sign both CLIs in
docker compose logs council                              # the URL to add as a connector
```

- **`login`** signs in each CLI that isn't signed in yet: for Codex, a code to enter on any device (choose **Sign in with ChatGPT**); for Claude Code, a link to open and a code to paste back. The sign-ins are kept, so this is needed once.
- **Settings go in `.env`** next to `compose.yaml`: `COUNCIL_PROJECTS` (the folder mounted read-only at `/projects`; default `./projects`), `COUNCIL_TOKEN`, a fixed address (below), and API keys ([below](#without-the-clis-through-the-apis)). Keep `.env` to yourself.
- **The `council-home` volume** keeps the sign-ins, config, skills and the token across restarts and new images.
- **Update:** `docker compose pull`, then `docker compose up -d`. The image is `ghcr.io/hamza-aziz-ai/codex-claude-council`, also on Docker Hub as [`hamzaazizai/codex-claude-council`](https://hub.docker.com/r/hamzaazizai/codex-claude-council), tagged `latest` and with each version.
- **`seccomp=unconfined`** (set in `compose.yaml`): Codex's read-only sandbox (bubblewrap) needs user namespaces, which Docker's default seccomp profile blocks. If Codex still reports that bubblewrap can't create a namespace, add `apparmor=unconfined` under `security_opt` too.
- **Without Compose:** `docker run -d --name council --restart unless-stopped --security-opt seccomp=unconfined --env-file .env -v council-home:/home/node -v ~/code:/projects:ro ghcr.io/hamza-aziz-ai/codex-claude-council serve --tunnel`, then `docker exec -it council codex-claude-council login` and `docker logs council`.

#### A fixed address with your own domain

With a [Cloudflare named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/) on a domain whose DNS is on Cloudflare, the container runs that tunnel itself and the address stays the same. Once, with cloudflared on your computer (this opens Cloudflare in your browser):

```bash
cloudflared tunnel login
cloudflared tunnel create council
cloudflared tunnel route dns council council.example.com
```

Then add the tunnel's token and its address to `.env` (PowerShell; this writes the token to the file without showing it) and start it:

```powershell
Add-Content .env "TUNNEL_TOKEN=$(cloudflared tunnel token council)"
Add-Content .env "COUNCIL_PUBLIC_URL=https://council.example.com"
docker compose up -d
```

`docker compose logs council` then shows `https://council.example.com/mcp/<token>`, the same after every restart. To keep a URL you already use, add its token too: `COUNCIL_TOKEN=<the part after /mcp/>`.

### Plans, API keys or no CLI

#### API keys instead of a plan

To pay per token on one side through its CLI, for example Claude on your Claude plan and Codex on an OpenAI API key, set that side's `auth` to `api_key` in the [config](#configure) (Docker: `COUNCIL_CODEX_AUTH=api_key` or `COUNCIL_CLAUDE_AUTH=api_key` in `.env`):

```json
{ "codex": { "auth": "api_key" } }
```

| Side | How to give it the key |
|---|---|
| **Codex** | `codex login --with-api-key`, then paste it; or set `OPENAI_API_KEY` and run `npx -y codex-claude-council login`, which stores it with Codex |
| **Claude Code** | set `ANTHROPIC_API_KEY`, which Claude Code reads as it is; or `claude auth login --console` |

A side on `subscription` gets no API key at all, so it can't bill an API account by accident; neither CLI ever gets the other side's key. A side on `api_key` still accepts its plan's sign-in.

#### Without the CLIs: through the APIs

An add-on to the CLIs, which stay the default: a side set to `"via": "api"` runs through its provider's API, so its CLI doesn't need to be installed. Claude goes through Anthropic's Messages API and ChatGPT through OpenAI's Responses API, each with its API key, billed per token.

| Side | Set | Key | Model, when none is set |
|---|---|---|---|
| **Codex (ChatGPT)** | `{ "codex": { "via": "api" } }` or `COUNCIL_CODEX_VIA=api` | `OPENAI_API_KEY` | `gpt-6-astra` |
| **Claude** | `{ "claude": { "via": "api" } }` or `COUNCIL_CLAUDE_VIA=api` | `ANTHROPIC_API_KEY` | `claude-opus-5-5` (`opus`, `sonnet`, `haiku` and `fable` name the current ones) |

In the [Claude Desktop extension](#claude-desktop-extension), entering a key in its settings does both. `model` and `effort` work as for the CLIs. The Claude Code and Codex plugins don't include the providers' SDKs: run `npx -y codex-claude-council api-setup` once to add them (npm, Docker and the Claude Desktop extension have them already).

| | Through its CLI | Through its API |
|---|---|---|
| **Your project** | reads files, searches, runs read-only commands (`git log`, `diff`, …) | three read-only tools of the council's own, limited to the project folder: list files, read a file, search; no commands |
| **The web** | the CLI's web search | the provider's web search (and Claude's web fetch) |
| **Memory** | the CLI session | the conversation, kept by the council's server while it runs (OpenAI's side with `store: false`) |
| **Your own sessions** (`…_session_id`, `council_join`'s other side) | continued in place | not possible: they exist only in the CLIs |
| **Your setup** (CLI skills, plugins, MCP servers, `CLAUDE.md` / `AGENTS.md`) | applies | doesn't: a skill you name is sent as text |

It can't change anything either way: an API member has no tool that writes or runs anything.

## Examples and best practices

### Pick the right tool

```mermaid
flowchart TD
    S{What do you want?} -->|a quick second opinion| O[council_ask_codex / council_ask_claude]
    S -->|a cross-checked answer| W{Who should take part?}
    W -->|two fresh sessions| CA[council_ask]
    W -->|my existing Claude Code and Codex sessions| CS[council_ask with claude_session_id and codex_session_id]
    W -->|the session I am in, with the other model| CJ[council_join]
    S -->|ev...

© Hamza Aziz · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
debt-ops The debt-ops plugin for Claude Code and Codex records deferred agent decisions in a repo registry; its review skill ranks debt by file churn. CX Codex ★ 1,596repo stars core-learning core-learning structures study sessions around Socratic questioning, Feynman teach-back, and spaced recall to deliver working projects. CX Codex ★ 1,596repo stars context-guard context-guard is a Claude Code and Codex plugin that preserves requirements and verification evidence in long Codex tasks. It restores open items after context compaction and checks evidence before marking work complete. CX Codex ★ 1,596repo stars codex-attachment-manager codex-attachment-manager is a Claude Code plugin that manages image history in Codex tasks. It selects attachments for the next message and searches them by description. CX Codex ★ 1,596repo stars codex-usage-and-resets codex-usage-and-resets is a Claude Code plugin that reports Codex weekly usage, pace, and reset expirations. It estimates whether the allowance will last until the next reset. CX Codex ★ 1,596repo stars codex-tui-proof codex-tui-proof is a Claude Code plugin for checking terminal UIs in Codex's browser with keyboard input and screenshots. It runs from a TUI validation request. CX Codex ★ 1,596repo stars codex-tasklist codex-tasklist is a plugin for Codex CLI that creates a live task panel, saves state to SQLite, and switches to tmux when native terminal panels are unavailable. CX Codex ★ 1,596repo stars codex-skin-pack-installer The codex-skin-pack-installer plugin stages and checks public-safe Codex skin packs from GitHub releases. Use it when a custom background, artwork, and a visible restore path matter. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open