# Codex CLI — Detailed Integration Guide

[Codex](https://github.com/openai/codex) is OpenAI's autonomous coding agent CLI. This reference covers auth, edge cases, and gateway-specific pitfalls.

## Auth

Codex can use `OPENAI_API_KEY` or OAuth. For Hermes itself, `model.provider: openai-codex` uses Hermes-managed Codex OAuth from `~/.hermes/auth.json` after `hermes auth add openai-codex`. For standalone CLI, a valid OAuth session may live under `~/.codex/auth.json` — do not treat a missing `OPENAI_API_KEY` alone as proof that Codex auth is missing.

## One-Shot Tasks

```bash
terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)
```

For scratch work (Codex needs a git repo):
```bash
cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'
```

## Background Mode (Long Tasks)

```bash
terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id — monitor with process(action="poll"|"log")
```

## Hermes Gateway Caveat

When invoking Codex CLI from a gateway/service context (Telegram-driven sessions), Codex `workspace-write` sandboxing may fail due to bubblewrap/user-namespace restrictions. Prefer:

```bash
codex exec --sandbox danger-full-access "<task>"
```

Use process boundaries as the safety layer: explicit `workdir`, clean git status before launch, narrow task prompts, `git diff` review, targeted tests.

## Parallel Issue Fixing with Worktrees

```bash
# Create worktrees
git worktree add -b fix/issue-78 /tmp/issue-78 main

# Launch Codex in each
terminal(command="codex --yolo exec 'Fix issue #78'", workdir="/tmp/issue-78", background=true, pty=true)
```

## Key Flags

| Flag | Effect |
|------|--------|
| `exec "prompt"` | One-shot execution, exits when done |
| `--full-auto` | Sandboxed but auto-approves file changes |
| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |
| `--sandbox danger-full-access` | No sandbox; useful when bubblewrap fails |