Codex Unchained

Codex Unchained keeps the official OpenAI Codex CLI intact and swaps only the inference brain.

Current upstream lock: Codex CLI 0.156.1.

Codex still owns the TUI, conversation/tool loop, shell, file editing, patches, approvals, sandbox, MCP, browser tools, session state, and execution. AGY and Ollama only decide the next assistant response or Codex tool call.

Model selection: use Codex /model

There is no separate model-fetch workflow.

Every time codex-unchained starts, the brain gateway discovers:

• models exposed by agy models;
• models exposed by ollama list.

It converts them into a native Codex model catalog using metadata from the installed official Codex build and starts Codex with that catalog.

Run:

codex-unchained

Then inside Codex:

/model

AGY and Ollama brains appear in the normal Codex model picker. Their internal slugs are namespaced so the gateway knows where inference should go, for example:

agy/gemini-3.8-flash-medium
agy/claude-sonnet-4-6
ollama/qwen3:8b

You can still use normal Codex -m when useful:

codex-unchained -m agy/gemini-3.8-flash-high
codex-unchained -m ollama/qwen3:8b

Or set an optional startup default:

export UNCHAINED_MODEL=agy/gemini-3.8-flash-medium

If no default is forced, Unchained starts with the first discovered brain, so a saved OpenAI Codex default cannot appear as the active model. Select another agy/ or ollama/ model with /model, or set UNCHAINED_MODEL for startup.

Brain architecture

                               ┌─ AGY / Antigravity model
                               │
You → official Codex CLI → brain gateway
          │                    │
          │                    └─ Ollama model
          │
          ├─ shell / files / patches
          ├─ approvals / sandbox
          ├─ MCP
          └─ browser extension via MCP

AGY

AGY runs through a model-only Antigravity agent:

• tools: [finish] (required to deliver the structured decision)
• inheritMcp: false
• command execution disabled

The finish tool only completes the AGY inference turn. Disabling it makes AGY retry completion without delivering a decision to Codex. Shell commands, edits, and browser actions still execute exclusively through Codex.

The Codex request is transported to AGY through its stream-json stdin protocol, which avoids command-line size limits on Windows. To keep multi-step work responsive, the gateway sends AGY only the current user request, relevant Codex tool results, and the currently available tool schemas. Codex retains the larger host instruction bundle and executes every action itself.

Ollama

Ollama is also treated as a model-only brain. The gateway sends the same Codex conversation/tool descriptions to Ollama and requires the same structured decision format. Ollama does not independently execute host tools.

Codex tool discovery loads app/browser schemas on demand. Ollama receives an explicit 32,768-token context (UNCHAINED_OLLAMA_CONTEXT overrides it), also advertised in the Codex catalog, and thinking is disabled for these structured decisions. Grossly oversized requests fail with a context error instead of being knowingly truncated. The preflight size check is an estimate, not a tokenizer. See Ollama's context documentation.

CPU-only inference can still take minutes to read a full Codex prompt. Increasing the deadline allows more time but does not speed up the model. Use an AGY model for interactive work if the local model cannot process the prompt quickly enough.

That keeps the rule consistent across providers:

Codex acts. The selected model thinks.

Browser extension

The Chrome/Edge extension is restored, but not the old ADP browser runtime.

The extension is now a thin execution bridge:

Codex tool loop
     │
     ▼
Codex MCP client
     │
     ▼
codex-unchained-browser-mcp
     │ localhost :8765
     ▼
Chrome / Edge extension
     │
     ▼
existing browser profile + active tab

The browser MCP currently exposes:

• bind active tab;
• semantic page inspection;
• navigate;
• click;
• fill non-sensitive controls;
• scroll;
• screenshot;
• wait for completed downloads.

The model does not talk directly to the extension. It selects a Codex tool; Codex invokes the MCP server; the MCP server transports the action to the extension.

Load the extension

The installer copies the unpacked extension into the Unchained install directory.

On Linux/macOS the default path is:

~/.local/lib/codex-unchained/extension

On Windows the installer prints the exact %LOCALAPPDATA%\CodexUnchained\extension path.

Chrome:

1. Open chrome://extensions
2. Enable Developer mode
3. Click Load unpacked
4. Select the installed extension directory

Edge uses edge://extensions.

After that, codex-unchained automatically registers the browser MCP with official Codex.

After an extension update, reload it in the browser's extensions page. Version 0.2.1 uses the scripting permission to initialize its content script in tabs that were already open. It retries only a missing-receiver error, never an ambiguous failure that might replay a click or fill.

Install

Linux / macOS

Requirements:

• curl
• Rust/Cargo
• agy for AGY models
• ollama for Ollama models

git clone https://github.com/haseebgb92/codex-unchained.git
cd codex-unchained
chmod +x install.sh
./install.sh

Windows

git clone https://github.com/haseebgb92/codex-unchained.git
cd codex-unchained
powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer downloads the official Codex version listed in UPSTREAM_CODEX_VERSION. It does not compile or patch Codex itself. It builds only the small provider gateway and browser MCP adapter.

Diagnostics

codex-unchained doctor

This reports the official Codex version, AGY/Ollama availability, brain gateway, browser MCP binary, extension path, and last imported catalog.

Each inference request has a 120-second deadline for both providers. Override it with UNCHAINED_INFERENCE_TIMEOUT=180s (the older UNCHAINED_AGY_TIMEOUT is also accepted). Gateway failures are not automatically retried by the launcher. The gateway log records the selected model, request start, completion time, and errors without recording prompts. On Linux/macOS it is at ~/.local/lib/codex-unchained/brain-gateway.log.

After updating, reinstall the gateway, launcher, and agent definition, then restart Unchained so it does not reuse an older running gateway.

Why the old runtime is gone

The earlier implementation duplicated browser, agent, executor, model-router, MCP, memory, and runtime behavior around Codex. That caused Unchained behavior to diverge from upstream Codex.

The current design removes those competing layers. The only custom pieces are adapters at the edges:

1. brain gateway — translates official Codex inference requests to AGY or Ollama;
2. browser MCP bridge + extension — gives official Codex access to the user's existing browser.

Everything in between stays upstream Codex.

The pre-cleanup implementation is preserved at:

codex-unchained-legacy-20260924

Upgrading Codex

Update UPSTREAM_CODEX_VERSION, run the compatibility CI, and rerun the installer. Because Codex itself is not forked or patched, upstream upgrades remain intentionally small.