Omelette Fleet

Gemini, Grok and Codex as read-only units in Claude Code

What you get

Three peers inside Claude Code, each on a subscription you already pay for, none of them able to write. doctor is where you find out whether that is actually true on your machine:

$ omelette-fleet doctor      # example output — all three units; config tables trimmed
FLEET DOCTOR · omelette-fleet 0.3.3 · node v20.19.5 · darwin
version       0.3.3 · latest 0.3.3
fleet home    ~/.omelette
fleet config  ~/.omelette/fleet.config.json
claude CLI    ~/.local/bin/claude
claude config ~/.claude.json
rules         project: v0.3.3 · global: absent
agents        project: v0.3.3 (2) · global: absent
skills        project: v0.3.3 (1) · global: absent
hooks         project: v0.3.3 (wired: PreToolUse, PreCompact, SessionStart) · global: absent
mcp timeout   wall-clock: MCP_TOOL_TIMEOUT unset (default ~28 h) ≥ 1800000 needed · ok
              deep research: gemini_deep_research worst case: 3 stages × 2 attempts × (300 + 60 s) = 2160 s · within the wall-clock limit
              idle: CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT unset → 30 min default; grok.timeoutS=1800 s reaches it — units send progress every 30 s when the client passes a progress token; otherwise set CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0 or a per-server "timeout"

── gemini (Gemini) ────────────────────────────────────────────
  bin         agy → ~/.local/bin/agy   [AGY_BIN=(unset)]
  version     1.1.25
  login       OK — agy models listed 14 line(s)
  config      closed — OMELETTE_ALLOW_WRITE does not list "gemini" · effective mode: read-only
              KEY        VALUE                    SOURCE
              enabled    true                     file
              mode       read-only                file
              model      Gemini 3.8 Flash (High)  file
              timeoutS   300                      file
  mcp         omelette-gemini registered (user) → node ~/omelette-fleet/servers/gemini.mjs [file exists]
  status feed ~/.omelette is writable
  results     ~/.omelette/results/gemini · keep 50 · max 50 MB

── grok (Grok) ────────────────────────────────────────────────
  bin         grok → ~/.grok/bin/grok   [GROK_BIN=(unset)]
  version     grok 1.0.13 (5e9a58528b76) [stable]
  login       OK — grok models listed 5 line(s)
  config      closed — OMELETTE_ALLOW_WRITE does not list "grok" · and this unit refuses workspace-write anyway · effective mode: read-only
  mcp         omelette-grok registered (user) → node ~/omelette-fleet/servers/grok.mjs [file exists]

── codex (Codex) ──────────────────────────────────────────────
  bin         codex → ~/.local/bin/codex   [CODEX_BIN=(unset)]
  version     codex-cli 0.153.0
  login       OK — Logged in using ChatGPT
  config      closed — OMELETTE_ALLOW_WRITE does not list "codex" · effective mode: read-only
  mcp         omelette-codex registered (user) → node ~/omelette-fleet/servers/codex.mjs [file exists]

No faults in units that are both enabled and registered.

How it fits together

graph LR
  CC["Claude Code (MCP client)"]

  subgraph FLEET["one stdio MCP server per unit"]
    SG["omelette-gemini"]
    SK["omelette-grok"]
    SX["omelette-codex"]
  end

  AGY["agy CLI"]
  GRK["grok CLI"]
  CDX["codex CLI"]
  SUB["your Gemini / xAI / ChatGPT subscriptions"]

  CFG["fleet.config.json + OMELETTE_ALLOW_WRITE ceiling"]
  FEED["status-*.json + fleet-log.ndjson"]
  READER["menu-bar app / tail -f"]

  CC -->|stdio| FLEET
  SG -->|spawn| AGY --> SUB
  SK -->|spawn| GRK --> SUB
  SX -->|spawn| CDX --> SUB
  CFG -. "re-read per call" .-> FLEET
  FLEET -. "writes" .-> FEED
  FEED --> READER

Plug Google Gemini, xAI Grok and OpenAI Codex into Claude Code as MCP units — read-only research and code-review peers. Each unit is its own stdio MCP server that spawns the vendor's own CLI headless (agy, grok, codex), so every call rides the subscription you already pay for. The child environment is built from a small allowlist rather than inherited, and API keys that would silently switch a CLI to metered billing are scrubbed on top of it. Claude Code stays the manager: units propose, the manager applies. A single config file with a two-key write ceiling keeps a unit from becoming a foot-gun, and a status feed reports what each unit is doing right now.

Zero runtime dependencies. Node core only, no build step.

Requirements

• Node ≥ 20
• Claude Code (the MCP client that will host the units)
• Any subset of the vendor CLIs, installed and logged in: agy (Antigravity, for Gemini), grok (Grok Build), codex (Codex CLI).
• macOS or Linux. Windows works through WSL; native Windows is not supported yet — CI runs the suite on windows-latest as a signal only, and 43 tests fail there today (POSIX path assertions, fake binaries without .cmd shims, file modes). Tracked for a later release.

A partial fleet is normal and expected. install skips units whose CLI is not on PATH; the units you do have work exactly the same.

Quickstart

Install the units once, from the clone:

git clone https://github.com/adxd-og/omelette-fleet.git
cd omelette-fleet
./bin/omelette-fleet.mjs install

Then give one project the operating rules — from inside that project, because every file this writes lands in the current directory:

cd /path/to/your/project
/path/to/omelette-fleet/bin/omelette-fleet.mjs rules --agents --hooks

(install --rules does both halves in one run, and its second half targets the current directory too — so run that from the project, not from the clone.)

Then: restart Claude Code, merge the printed snippet into that same project's .claude/settings.json, and run omelette-fleet doctor there — it names the one thing still missing, if there is one.

install registers one MCP server per available unit with claude mcp add -s user, named <prefix>-<unit> (default prefix omelette, so omelette-gemini, omelette-grok, omelette-codex), and creates ~/.omelette/fleet.config.json from examples/fleet.config.json if you don't have one. The tools appear after the restart as mcp__<prefix>-<unit>__<tool> — for example mcp__omelette-codex__codex_code_review.

--rules adds the second half in the current directory: it is exactly rules --agents --hooks, so you get the operating rules, both sub-agent definitions, the /omelette-test skill, the guard script and the settings snippet to paste. install --rules --dry-run prints both halves and changes nothing. Leave it off and the same files are one command away:

./bin/omelette-fleet.mjs rules          # <project>/.claude/rules/omelette-fleet.md
./bin/omelette-fleet.mjs rules --global # ~/.claude/rules instead
./bin/omelette-fleet.mjs rules --agents # + the coder / tester sub-agent definitions and the /omelette-test skill

Rules load on the next session start; agent definitions and skills are picked up by Claude Code's watcher — usually within seconds, sometimes minutes (restart if .claude/agents or .claude/skills did not exist before).

Optionally, install the guard hook — the coder's "never commits" rule, enforced rather than requested, plus a ledger marker on every compaction and the last handoff block printed back into the session that follows one:

./bin/omelette-fleet.mjs rules --hooks  # writes .claude/hooks/omelette-guard.mjs

It prints a settings snippet and you merge it in yourself, into .claude/settings.json or .claude/settings.local.json: a hook script does nothing until your settings call it, and omelette-fleet reads those files but never writes them. The snippet is a whole hooks object, so — as the printed line says — "Merge this into your settings file (it is a whole hooks object — add the events it lists to an existing hooks block rather than replacing the file)". The script path in it is quoted for the platform the CLI runs on: POSIX single quotes on macOS and Linux, double quotes on Windows, where the JSON layer then doubles the backslashes of the path ("node \"C:\\Users\\me\\.claude\\hooks\\omelette-guard.mjs\""). Double quotes are a shell quoting, not an argv: under PowerShell or Git Bash a $ in that path would expand, so a path holding one wants editing by hand — one more reason native Windows is not supported yet. doctor reads both files and reports hooks project: v0.3.3 (wired: PreToolUse, PreCompact, SessionStart) — or NOT wired, which is the failure mode where everything looks installed; a PreToolUse entry whose matcher cannot see a Bash call is reported as NOT wired (PreToolUse matcher is not Bash), since it will never see the call it exists to guard. A matcher is read the way Claude Code reads it: an exact list or an unanchored regex. A string of nothing but tool names, |, , and spaces is a list — Bash|Edit and Bash, Write are wired, Bashful and ash are not — and anything else is a regex tested against Bash unanchored, so .*, Ba. and ash$ are wired too; an absent matcher, "" and "*" mean every tool. One that does not compile counts as nothing and is named as what it is — NOT wired (PreToolUse matcher "(" is not a valid regex) — because that is a typo to fix, not a guard aimed at the wrong tool, and a matcher that is not a string at all is reported as NOT wired (PreToolUse matcher is not a string). The SessionStart group is matched on the session's source rather than a tool: the snippet wires "matcher": "compact", startup is reported as NOT wired (SessionStart matcher is not compact), and a guard still wired the 0.3.2 way reads NOT wired (missing SessionStart).

Then check the install:

./bin/omelette-fleet.mjs doctor

doctor reports the binaries and versions it found, login state, the resolved config with sources, the effective mode and write ceiling per unit, MCP registration, and whether the status-feed directory is writable. It reads Claude Code's .claude.json from $CLAUDE_CONFIG_DIR first and ~/ second, and prints which file it used — "not registered" against the wrong file would be a lie. It reads the project's .mcp.json too, and names it when it is there.

A registration counts as ours by where it points, not by what it is called: command node, args path exactly this clone's servers/<unit>.mjs. So if you registered the units under your own prefix, doctor finds them, says prefix orion (found on the registrations) and reports the rest under that name instead of announcing that omelette-* is missing. Two different prefixes are ambiguous — it names both, keeps omelette, and leaves the choice to --prefix. A project-scope entry counts only for the project you are standing in.

It also names the client's own two timeout walls under mcp timeout — the wall-clock MCP_TOOL_TIMEOUT against the longest call the enabled units can make, and the 30-minute stdio idle abort — with the snippet to merge when the first one is short. Both are informational; the details are in docs/CONFIG.md.

While something is missing it also prints ONE next line, in the order a first run needs them:

next          omelette-fleet install                     # nothing registered yet (--prefix <p> when you use one)
next          omelette-fleet rules --agents --hooks       # registered, but one of the four managed kinds is missing
next          a managed file has no omelette-fleet marker (see the rules/agents/skills/hooks lines) — inspect it, then `omelette-fleet rules --agents --hooks --force` replaces it
next          <path> is a symlink — omelette-fleet refuses to manage it; remove the link, then rules --agents --hooks
next          merge the hooks snippet into .claude/settings.json (rules --hooks prints it)
next          raise MCP_TOOL_TIMEOUT to 1800000 ms — merge {"env":{"MCP_TOOL_TIMEOUT":"1800000"}} into your settings file (omelette-fleet never writes it)

and nothing at all once they are done. The marker line and the symlink line are the exceptions to "run this command": a file at one of those paths that is not ours would be refused by the plain command, and a symlink is refused by --force as well — rules never writes through one — so doctor names the situation instead of sending you into a refusal. It is a hint, never a fault: it does not change the exit code. It looks at the project scope only — the scope the commands it suggests write — so a guard installed and wired globally still gets the merge hint here. The timeout line is last on purpose: it is tuning for a machine that already works, so it waits until every first-run step is done.

It exits 1 only for a unit that is enabled and registered and broken: the vendor binary is missing, the CLI says it is signed out, or the registration points at a server file that no longer exists. A unit you deliberately never wired up is not a fault — and neither is a login state of unknown. A probe doctor cannot interpret (a non-zero --version, a login status with no explicit signal) is reported as unknown (exit N) with the tail of its output, never as a version and never as "signed out".

Once published, the same commands work as npx omelette-fleet ….

Fewer permission prompts

Every unit tool is read-only by design — it spawns a vendor CLI that cannot write your repository — so approving each call one at a time buys you nothing. Allowlist them once in .claude/settings.json (project) or ~/.claude/settings.json (global):

{
  "permissions": {
    "allow": [
      "mcp__omelette-gemini__*",
      "mcp__omelette-grok__*",
      "mcp__omelette-codex__*"
    ]
  }
}

Use your own --prefix if you installed with one. If you register the servers per project through a checked-in .mcp.json instead of claude mcp add -s user, "enableAllProjectMcpServers": true in .claude/settings.json approves the servers themselves; the permissions.allow entries above still decide the per-tool prompting. As everywhere else here, this is a file you edit — omelette-fleet never writes settings.json or settings.local.json.

CLI

If claude is not in PATH, install still writes the fleet config and prints the exact claude mcp add commands to run later; uninstall prints its commands and changes nothing. Neither the CLI nor the servers ever shell out — every child is spawn(bin, [args]), so a path or a value containing a space is data, not shell syntax. The only files the CLI writes are <home>/fleet.config.json, <home>/update-check.json and — only when you run rules — the marked files it manages under .claude/rules/, .claude/agents/, .claude/skills/ and .claude/hooks/, never one that lacks its marker unless you pass --force. The unit servers write two more of their own: the status feed and <home>/results/<unit>/*.md, the result spool. Claude Code's own config is parsed, never written: that goes for .claude.json and for settings.json / settings.local.json, which doctor reads to say whether the guard hook is wired and rules --hooks only ever prints a snippet for.

call is the way to test a unit without a client: ./bin/omelette-fleet.mjs call codex codex_models '{}'. It distinguishes the two failures that matter — a tool that answered with an error (exit 2, the unit talking) from a server that errored at the protocol level or died mid-call (exit 1, the pipe breaking), rather than reporting either as an empty success.

Keeping it up to date

./bin/omelette-fleet.mjs update          # fast-forward this checkout
./bin/omelette-fleet.mjs update --check  # report only; exit 3 = an update is available

Restart Claude Code afterwards. The unit servers are spawned per session and there is no daemon, so a running session keeps the code it started with until you restart it.

You do not have to remember to check: each unit server makes one unauthenticated request to the GitHub releases API at startup and prints a single stderr line — update: omelette-fleet X.Y.Z is available (you run …) — when there is something newer. The check runs at most once every 24 hours (the answer is cached in <home>/update-check.json), is capped at 2.5 s, is fire-and-forget so it can never delay a tool call, and stays quiet when you are current. Switch it off with OMELETTE_UPDATE_CHECK=0 in the server's env block, or "updateCheck": false in the fleet config.

The vendor CLIs update themselves; this package deliberately does not. doctor shows both — each unit's version line, and the fleet's own version … · latest … header.

Units

Model ids, benchmark numbers and routing advice live in units/<unit>/models.js and are served by each unit's <unit>_models tool — call it when you are unsure which model a task belongs on.

Configuration

One JSON file, ~/.omelette/fleet.config.json (or $OMELETTE_HOME/fleet.config.json), read fresh on every call. examples/fleet.config.json:

{
  "version": 1,
  "defaults": {
    "status": true
  },
  "agents": {
    "coder": {
      "model": "opus",
      "effort": "xhigh"
    },
    "tester": {
      "model": "sonnet",
      "effort": "xhigh",
      "maxTurns": 80
    }
  },
  "units": {
    "gemini": {
      "enabled": true,
      "mode": "read-only",
      "model": "Gemini 3.8 Flash (High)",
      "timeoutS": 300
    },
    "grok": {
      "enabled": true,
      "mode": "read-only",
      "timeoutS": 1800,
      "maxTurns": 30
    },
    "codex": {
      "enabled": true,
      "mode": "read-only",
      "model": "gpt-6-astra",
      "effort": "high",
      "webSearch": true,
      "timeoutS": 600
    }
  }
}

One consequence worth knowing: because the Codex unit runs with --ignore-user-config, leaving codex.model unset does not fall back to your ~/.codex/config.toml default — the adapter pins the first catalog entry (gpt-6-astra) instead and logs that it did.

Every key, its default, the resolution order, and the per-unit environment overrides: docs/CONFIG.md.

Security

• Units are read-only by default; the mutating path stays in Claude Code, under your approval.
• Write mode needs two keys: mode: "workspace-write" in the config file and the unit listed in OMELETTE_ALLOW_WRITE in the MCP server's env block. The config can only narrow, never widen.
• Enforcement strength differs by vendor: Codex is an OS-level kernel sandbox (plus --ignore-user-config --ignore-rules, so your ~/.codex/config.toml — MCP servers, plugins, hooks — never reaches a fleet run), Grok is a spawn-arg tool allowlist (and refuses write mode outright), Gemini is the CLI's own permission policy — the weakest of the three.
• The child environment is built from an allowlist, not inherited: a review run cannot read your GH_TOKEN or cloud credentials. Billing-risk API keys are scrubbed on top of that, and --dangerously-* / --always-approve flags are never passed.
• Everything a unit reads from the web or from a repository is untrusted input.

Threat model, the per-unit enforcement matrix, and what is only best-effort: docs/SECURITY.md.

Status feed

Every unit writes what it is doing to $OMELETTE_HOME (default ~/.omelette): a per-unit snapshot status-<unit>.json with the calls running right now and the last finished event, and a shared append-only fleet-log.ndjson with one compact JSON line per start and end. Writes are atomic, mode 0600, fail-soft (an fs error can never break a tool call), and the log self-trims. Any menu-bar app, HUD or tail -f can read it. One reader of this feed is Omelette usage-checker, a macOS menu-bar app; the feed is an open contract, so nothing here depends on it. Schema and field lists: docs/STATUS-FEED.md. An end event's resultId names the file the answer itself was spooled to; omelette-fleet results prints that spool from a shell, and <unit>_result hands the answer back inside a session.

Orchestration

How to actually run a session with a fleet — who decides, who proposes, which unit gets which task, and when to escalate a model or effort level: docs/ORCHESTRATION.md. The adapter contract and internals: docs/ARCHITECTURE.md. Adding a fourth unit: docs/ADAPTERS.md.

Rules in your session. Three layers put that operating model in front of Claude Code. Every unit server hands the short version — units propose, the session applies, absolute paths, verify Grok — to the client from the MCP initialize handshake, so it is in context as "MCP Server Instructions" after a restart, with nothing to run. The long version is one command: omelette-fleet rules writes <project>/.claude/rules/omelette-fleet.md (or --global for ~/.claude/rules), which Claude Code loads like CLAUDE.md, and --agents adds the coder and tester sub-agent definitions — where their effort and the tester's turn limit are set, and where the harness is told they may not spawn sub-agents of their own — plus the /omelette-test skill, which forks the tester with the diff taken from git at invocation so it can never be handed the coder's summary. You invoke it as /omelette-test <spec path> [repo path] — the repo path is for an orchestrator whose session sits in another repository; leave it off and the diff is the current directory's. The third layer is --hooks: one guard script that blocks the coder's git commit at PreToolUse, stamps a re-read marker into your plan ledger at PreCompact, and prints that ledger's last handoff block back into the session that opens after a compaction at SessionStart, wired up by a snippet you paste into your own settings file. Details, including how the version marker decides which files the fleet may overwrite: docs/ORCHESTRATION.md.

FAQ

Why CLIs instead of API keys?
Two reasons. Billing: each vendor CLI authenticates against the subscription you already pay for, and an API key present in the environment would silently flip it to metered API billing — so every key that could do that is deleted from the child process env. Safety: each CLI ships its own sandbox and permission machinery (Codex's OS sandbox, Grok's --tools allowlist and permission rules, agy's permission policy), and this package drives those instead of reimplementing them against a raw API.

The flip side is that a CLI run is a program with an environment, so the child env is built from an allowlist rather than inherited — a unit running read-only shell commands would otherwise be able to read every secret in your shell. Details in docs/SECURITY.md.

Why read-only?
Because a review peer that can also write is a review peer you have to supervise twice. Units read, search, analyse and propose; Claude Code applies the change, where your normal approval flow already sits. It also contains the blast radius of prompt injection: a unit that ingests a hostile web page or repository can only report back, not act.

Can I let a unit write?
Only deliberately, and only where it is actually enforceable. Write mode takes two keys: mode: "workspace-write" for that unit in the config file, and the unit named in OMELETTE_ALLOW_WRITE in the server's env block — which lives outside every project and cannot be edited by a read-only unit. Then the unit itself has to implement the mode:

• Codex does. Writes are kernel-scoped to the cwd you pass, and the adapter grants it only to codex_code_review with an explicit absolute cwd — codex_research is read-only whatever the config says. (codex_image also runs workspace-write, and is the one call that does not consult the ceiling: the kernel scopes it to a throwaway temp directory the adapter just created, because an image tool that cannot save a file is not a tool. Details in docs/SECURITY.md.)
• Grok does not. workspace-write is declared unsupported and refused even with the ceiling open.
• Gemini maps it to agy's --mode accept-edits, which is agy's own permission layer inside the process cwd — real, but not kernel-enforced. ORION_ALLOW_GEMINI_MUTATE=1 is honoured as a legacy alias for opening the ceiling for gemini only.

What if my ChatGPT plan rejects gpt-5.6-sol?
The Codex catalog lists what exists in the current generation, not what one account happens to accept. gpt-5.6-sol is plan-gated to ChatGPT Pro/Enterprise; on a Plus or Team plan the call fails fast, before any work, with The 'gpt-5.6-sol' model is not supported when using Codex with a ChatGPT account.

You are not missing much. The fleet default is gpt-6-astra at effort: high, which is accepted on Plus — probed live 2026-09-05 on codex-cli 0.153.4 at effort low, high, xhigh and max — and scores above sol on the AA Intelligence Index (55 vs 51). gpt-5.6-terra is the cheaper step-down for sweeps and routine review, since astra costs ~5x terra per token and is markedly slower. The heavier gpt-6-astra-pro, gpt-6-pro and gpt-6 are rejected on a ChatGPT plan exactly like sol; only gpt-6-astra is embedded in the CLI binary. codex-cli 0.153.4 also made astra its own bundled default, so a fleet call and a bare codex run now land on the same model — the fleet pins it explicitly regardless, because it runs with --ignore-user-config. omelette-fleet doctor --probe-models tells you exactly which ids your account accepts.

How do I add a unit?
Three files and a test: units/<unit>/models.js (the model allowlist and cheat-sheet), units/<unit>/adapter.mjs (a defineUnit({...}) call), servers/<unit>.mjs (a two-line entrypoint). The runtime gives you config, the ceiling, catalog validation, the mutate gate, the status feed, bounded spawn with the env allowlist and billing scrub, and JSON-RPC. Step by step, with a skeleton and the fake-binary test pattern: docs/ADAPTERS.md.

Why three servers instead of one?
Failure isolation and stable names. A missing CLI, a hung vendor process, or an adapter bug takes down one server, not the fleet — the other units keep answering. Each server also owns a fixed tool list, so installing or removing a unit never reshuffles the tools of the others, and you can enable, disable, time-out and configure each vendor independently. It costs one idle Node process per unit.

License

MIT — see LICENSE.