Codex CLI

Auto-wired

Setup detects Codex CLI and writes two things: an MCP entry in ~/.codex/config.toml, and steering instructions in ~/.codex/AGENTS.md.

Codex also has a shell, which means it can use the sigil CLI directly — often the better path.

Setup

sigil init
sigil doctor

Manual config

Codex uses TOML, so translate the JSON from sigil register --print:

~/.codex/config.toml

[mcp_servers.sigil]
command = "/Users/you/.sigil/bin/sigil-mcp"
args = []

Run sigil register --print for the correct path on your machine.

Steering

Setup writes this into ~/.codex/AGENTS.md. If you’re configuring by hand, add:

## Memory (Sigil)

You have a persistent memory at `sigil`. Use it.

- Before answering about this project, past decisions, or preferences,
  run `sigil search "..."`.
- When the user shares a preference, decision, or constraint, run
  `sigil remember --bg "short self-contained fact"`.
- To store a document whole: `sigil ingest ./FILE.md`.
- Batch multiple facts into one call:
  `sigil remember --bg "fact one" "fact two"`.

CLI or MCP

Codex can do both. The CLI is often better here:

	CLI	MCP
Token cost	A shell command	Codex loads MCP tool definitions per exec — roughly 9.9k tokens of schema on every call
Setup	Nothing, if sigil is on PATH	An entry in config.toml
Structure	Text output	Typed results

That per-exec MCP loading cost is real, and it’s why Sigil exposes llm.codexExtraArgs as an escape hatch when it’s using Codex as its LLM provider.

For most Codex CLI usage, the shell path is simpler and cheaper:

sigil search "how do we handle retries"
sigil remember --bg "Codex handles the migration scripts; Claude Code owns the API layer"

--bg inside an agent turn

A save runs a chain of LLM calls. --bg returns immediately and completes in the background — the right default when an agent is mid-turn. Failures still surface through sigil doctor.

Codex as Sigil’s LLM provider

The relationship runs both ways: Sigil can use your Codex subscription as its own LLM provider.

llm.provider = codex
llm.codexPath = /path/to/codex      # if it isn't on the daemon's PATH
llm.codexExtraArgs = ["-c", "model_reasoning_effort=\"low\""]

codexModel is deliberately null by default — Codex already has a model in ~/.codex/config.toml, and duplicating it here would create two sources of truth that silently disagree. Null means “let Codex decide”.

See Providers.

Troubleshooting

sigil connect --clients codex
sigil doctor --deep

Codex doesn’t call Sigil. Check that ~/.codex/AGENTS.md actually contains the steering block — Codex reads it at session start.

The MCP entry errors. The shim path went stale after a Node switch. sigil connect fixes it.