> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Run Smithers from OpenAI's Codex CLI. Register the MCP server in config.toml and point Codex at it with AGENTS.md.

[OpenAI Codex](https://developers.openai.com/codex) extends through **MCP
servers** declared in `~/.codex/config.toml` and **`AGENTS.md`** instructions.
Wire up the MCP server with Smithers:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator mcp add --agent codex
```

That registers the MCP server in Codex's config. Restart Codex and it can drive
workflows.

## Model tiers

Smithers pins each Codex worker to the tier that matches its role:

| Work                                                                                      | Model                                                                          |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Planning, orchestration, review, and the hardest reasoning                                | [`gpt-5.6-sol`](https://developers.openai.com/api/docs/models/gpt-5.6-sol)     |
| Mid-tier judgment, validation, or tool-heavy work that needs extra checking               | [`gpt-5.6-terra`](https://developers.openai.com/api/docs/models/gpt-5.6-terra) |
| **Research, implementation, ordinary tool use, UI, and routine-to-substantial execution** | [`gpt-5.6-luna`](https://developers.openai.com/api/docs/models/gpt-5.6-luna)   |

Use the exact tier IDs rather than the floating `gpt-5.6` alias. Start with
Luna for most research, implementation, ordinary tool use, and substantial
execution; size alone does not require Sol. Escalate to Terra for stronger
validation or structured tool-heavy judgment, and to Sol for ambiguity,
high-stakes decisions, novel architecture, orchestration, final review, or
repeated failure. When usable Codex authentication is present, generated
Smithers workflows put these Codex workers first. Other adapters remain later
runtime fallbacks and run only when the Codex attempt is unavailable or fails.
See [SOTA role defaults](/reference/sota-models#role-defaults).

## Smithers docs in Codex

Smithers does not currently auto-install a Codex skill, and
`bunx smithers-orchestrator skills add` has no supported `--agent codex` target
filter. For Codex, keep the repo-level `AGENTS.md` guidance below and use the
packaged docs commands when Codex needs the full API:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator docs-full
bunx smithers-orchestrator ask "How do I run and watch a workflow?"
```

## Register the MCP server

`mcp add` writes the entry for you. The native config is a TOML table in
`~/.codex/config.toml`:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[mcp_servers.smithers]
command = "bunx"
args = ["smithers-orchestrator", "--mcp"]
```

Or use the Codex CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
codex mcp add smithers -- bunx smithers-orchestrator --mcp
```

Codex launches the server at session start and the semantic tools
(`list_workflows`, `run_workflow`, `watch_run`, `resolve_approval`, …) appear in
the `/mcp` list. Full reference: [MCP Server](/integrations/mcp-server).

## Standing instructions

Codex reads `AGENTS.md` from the repo root down to the working directory. Add a
section so Codex knows to reach for Smithers:

```md theme={"theme":{"light":"github-light","dark":"github-dark"}}
## Orchestration
Use Smithers for durable, multi-step, or human-in-the-loop agent work.
Run `bunx smithers-orchestrator starters` to see ready-made workflows,
then `bunx smithers-orchestrator workflow run <name> --prompt "…"`.
```

This same `AGENTS.md` is read by Cursor, Copilot, Hermes, and Pi; one file
covers several agents.

## Smithers runs Codex too

In the other direction, Smithers spawns Codex as a worker via `CodexAgent`
(`codex exec` with a streamed JSON protocol and native thread hijack):

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { CodexAgent } from "smithers-orchestrator";

const implementer = new CodexAgent({
  model: "gpt-5.6-luna",
  config: { model_reasoning_effort: "medium" },
  sandbox: "workspace-write",
});
```

See [CLI Agents → Codex](/integrations/cli-agents#codex-cli-agent).