# Codex CLI Harness — Referenz-Guide

> Für Samuel: Du kennst Claude Code in- und auswendig. Dieser Guide erklärt Codex im direkten Vergleich.

---

## 1. Architektur

Codex ist OpenAIs autonomer Coding-Agent mit TUI und Non-interactive-Mode. Konfiguration läuft über TOML statt JSON.

```
codex (CLI)
├── interaktive TUI         — Standard bei `codex` ohne Argumente
├── codex exec "prompt"     — Non-interactive One-Shot Execution
├── codex review            — Eingebauter Code-Review-Modus
├── codex resume/fork       — Session-Management
└── codex features          — Feature-Flag-Verwaltung
```

**Schichten-Überblick:**

| Schicht | Pfad | Funktion |
|---------|------|----------|
| Haupt-Config | `~/.codex/config.toml` | Modell, Trust-Level, Migrationen |
| Auth | `~/.codex/auth.json` | ChatGPT OAuth Tokens (Google Account) |
| Runbooks | `~/.codex/runbooks/` | Session-Typ-Instruktionen (4 Typen) |
| Approval-Rules | `~/.codex/rules/default.rules` | Command-Approval via `prefix_rule` |
| Skills | `~/.codex/skills/` | 33 Skill-Verzeichnisse |
| Logs | `~/.codex/log/` | Session-Logs |
| History | `~/.codex/history.jsonl` | Session-History |

**Kernunterschied zu Claude Code:** Codex verwendet _Runbooks_ statt Hooks. Wo Claude Code mit PreToolUse/PostToolUse-Hooks in Shell oder Python Verhalten steuert, definiert Codex pro Session-Typ eine Markdown-Instruktionsdatei. Kein programmatisches Hook-System.

**Auth-Modell:** Nicht API-Key-basiert wie Claude Code — Codex nutzt ChatGPT OAuth (Google Account, auto-refresh). Token liegt in `~/.codex/auth.json`. Kein manuelles Key-Rotieren nötig.

---

## 2. Konfiguration

### config.toml

```toml
model = "gpt-5.4"
model_reasoning_effort = "medium"  # low | medium | high | xhigh

[projects."/home/smlflg/Projekte"]
trust_level = "trusted"

[projects."/home/smlflg/Projekte/untrusted-experiment"]
trust_level = "untrusted"

[notice.model_migrations]
"gpt-5.1-codex-max" = "gpt-5.4"   # Auto-Redirect veralteter Modell-Namen
```

**Trust-Level** ist das Äquivalent zu Claude Codes Permissions-System — aber granularer, weil per-Project und nicht global. Aktuell: 17 trusted, 2 untrusted Projekte.

### Runbooks (~/.codex/runbooks/)

Jeder Session-Typ hat eine eigene Instruktionsdatei:

| Runbook | Zweck | Wann verwenden |
|---------|-------|----------------|
| `build.md` | "Implement one stable outcome" | Feature bauen, Bug fixen |
| `planning.md` | "Fuzzy goals → buildable artifacts" | Ideen strukturieren, Architektur |
| `review.md` | "Quality + regression checks" | Code reviewen, vor Commit |
| `inspect.md` | "Read-only exploration" | Codebase verstehen, Analyse |

Runbooks direkt editieren für projekt-spezifische Instruktionen — das ist Codex' Äquivalent zu CLAUDE.md (AGENTS.md ist geplant, aber noch nicht implementiert).

### Approval-Policies

Codex hat zwei orthogonale Kontrollebenen — Sandbox-Mode (was darf die Umgebung?) und Approval-Policy (wann fragt der Agent nach?):

| Sandbox-Mode | Bedeutung |
|--------------|-----------|
| `read-only` | Nur lesen, keine Schreiboperationen |
| `workspace-write` | Schreiben im Projektverzeichnis erlaubt |
| `danger-full-access` | Unbeschränkter Zugriff |

| Approval-Policy | Bedeutung |
|-----------------|-----------|
| `untrusted` | Fragt bei allem nach |
| `on-request` | Fragt nur wenn unsicher |
| `on-failure` | Fragt nur bei Fehler |
| `never` | Fragt nie (volle Autonomie) |

**Vergleich zu Claude Code:**

| Feature | Claude Code | Codex |
|---------|-------------|-------|
| Config-Format | JSON | TOML |
| Auth | API Key (Anthropic) | ChatGPT OAuth (Google) |
| Modell | Claude Opus/Sonnet/Haiku | GPT-5.4 (OpenAI) |
| Hooks | 5 Lifecycle-Points (Shell/Python) | Keine — Runbooks statt Hooks |
| Session-Typen | Frei (Plan Mode optional) | 4 definierte Typen |
| Sandbox | Permissions allow/deny | 3 Sandbox-Modes + 4 Approval-Policies |
| Trust | Global | Per-Project Trust-Level |
| Skills | SKILL.md in ~/.claude/skills/ | 33 Skill-Verzeichnisse |
| Feature Flags | Nicht vorhanden | Togglebar |
| Regel-Datei | CLAUDE.md | AGENTS.md (geplant, noch nicht aktiv) |

---

## 3. Tuning

### Modell und Reasoning-Tiefe

```bash
codex -m gpt-5.4 "prompt"                          # Modell wählen
codex -c model_reasoning_effort="high" exec "..."   # Mehr Reasoning
codex -c model_reasoning_effort="xhigh" exec "..."  # Maximum — langsamer, gründlicher
```

`xhigh` entspricht ungefähr Claude Codes extended thinking — für komplexe Architektur- oder Debug-Tasks sinnvoll, für einfache Edits Overhead.

### Sandbox + Approval kombinieren

```bash
# Standard für den meisten Alltag: Schreiben erlaubt, fragt bei Unsicherheit
codex exec -s workspace-write -a on-request "..."

# Shorthand (identisch mit oben)
codex exec --full-auto "..."

# Nur lesen — für Analyse und Review
codex exec -s read-only "..."

# Volle Autonomie — nur für bekannte, stabile Aufgaben
codex exec -s workspace-write -a never "..."
```

### Trust-Level per Projekt setzen

```toml
# In ~/.codex/config.toml ergänzen:
[projects."/home/smlflg/Projekte/MeinNeuesProjekt"]
trust_level = "trusted"
```

Nach dem Editieren kein Reload nötig — wird beim nächsten `codex`-Aufruf im Verzeichnis gelesen.

### Feature Flags

```bash
codex features list                     # Alle Features und Status anzeigen
codex features enable multi_agent       # Feature global aktivieren
codex features disable js_repl          # Feature deaktivieren
codex --enable multi_agent exec "..."   # Nur für diese Session aktivieren
```

**Stabile Features** (produktionstauglich): `multi_agent`, `personality`, `shell_snapshot`, `shell_tool`, `enable_request_compression`, `fast_mode`

**Experimentell** (mit Vorsicht): `guardian_approval`, `js_repl`, `prevent_idle_sleep`

**In Entwicklung** (nicht für Produktion): `code_mode`, `memories`, `plugins`, `realtime_conversation`, `child_agents_md`

### Session Management

```bash
codex resume              # Interaktiver Session-Picker
codex resume --last       # Direkt letzte Session fortsetzen
codex fork                # Session branchen (Picker)
codex fork --last         # Letzte Session forken — für Experimente ohne Hauptsession zu verlieren
```

`fork` ist praktisch wenn eine Session gut läuft, aber ein riskanter nächster Schritt ansteht — Branch erstellen, ausprobieren, bei Bedarf zur Hauptsession zurück.

### Code Review

```bash
codex review                                      # Alle uncommitted Changes
codex review --base main                          # Diff gegen Branch
codex review --commit abc123                      # Einzelnen Commit reviewen
codex review --uncommitted "Focus on security"    # Mit Custom-Focus
```

Kein Equivalent in Claude Code nativ — dort müsste man den Review manuell als Prompt formulieren.

### Runbooks anpassen

```bash
# Build-Runbook für eigene Konventionen ergänzen:
nano ~/.codex/runbooks/build.md
# → Projekt-Konventionen, Testbefehle, Style-Regeln eintragen

# Eigenes Runbook für speziellen Workflow:
cp ~/.codex/runbooks/build.md ~/.codex/runbooks/debug.md
# → Dann mit `codex --runbook debug exec "..."` aufrufen
```

---

## 4. Vor- und Nachteile

### Vorteile

- **Bestes Endprodukt in Evals:** Liefert konsistent hübsche, fertige Outputs — Dashboard-Eval: "dicke geliefert"
- **Gründliche Rückfragen:** Stellt ~10x Rückfragen vor dem Bauen — verhindert Fehlannahmen, weniger Re-Work
- **Höchste Scope-Treue:** Bleibt nah am Referenz-Material, baut was im Auftrag steht — kein feature creep
- **4 Session-Typen:** Build/Planning/Review/Inspect erzwingen Fokus — kein "Alles in einem"-Prompt
- **Echtes Sandbox-System:** Read-only bis full-access — granularer als Claude Codes Allow/Deny-Listen
- **Per-Project Trust:** Feiner als Claude Codes globales Permission-System
- **Feature Flags:** Experimentelle Features togglebar — bei Claude Code alles-oder-nichts
- **`codex review`:** Eingebauter Code-Review mit Branch/Commit-Scope
- **Session fork/resume:** Strukturiertes Session-Management — Claude Code hat keinen nativen Fork
- **Reasoning-Stufen:** low/medium/high/xhigh — feinere Kontrolle als Modell-Auswahl

### Nachteile

- **Langsamer Start:** Braucht Zeit zum Einlesen des Projekts — nicht nach 30 Sekunden abbrechen
- **Dashboard-Stabilität:** 2x abgestürzt bei großen Outputs in Evals
- **Wenig Selbstkritik:** Selbstbewusst bis erhaben — gibt selten Fehler oder Unsicherheit zu
- **Mittelpreisig:** GPT-5.4 teurer als MiniMax-basierte Harnesses (Hermes/OpenCode)
- **Kein Hook-System:** Kein PreToolUse/PostToolUse — Verhalten nicht per Script steuerbar
- **Kein AGENTS.md:** CLAUDE.md-Äquivalent geplant, aber noch nicht implementiert
- **Kein echtes Subagent-System:** `multi_agent`-Flag existiert, aber nicht vergleichbar mit Claude Codes Agent-Tool
- **OpenAI-locked:** Nur GPT-Modelle — kein Multi-Provider wie Hermes oder OpenCode
- **Keine Sidecar-Integration:** Kein UserPromptSubmit-Hook → kein Context-Injection möglich
- **MCP noch leer:** Infrastruktur vorhanden, aber keine Server konfiguriert

---

## 5. Referenz

### Wichtige Dateipfade

| Pfad | Inhalt |
|------|--------|
| `~/.codex/config.toml` | Haupt-Config (Modell, Trust-Level, Migrationen) |
| `~/.codex/auth.json` | ChatGPT OAuth Tokens |
| `~/.codex/runbooks/build.md` | Build-Session-Instruktionen |
| `~/.codex/runbooks/planning.md` | Planning-Session-Instruktionen |
| `~/.codex/runbooks/review.md` | Review-Session-Instruktionen |
| `~/.codex/runbooks/inspect.md` | Inspect-Session-Instruktionen |
| `~/.codex/rules/default.rules` | Command-Approval-Rules |
| `~/.codex/skills/` | 33 Skill-Verzeichnisse |
| `~/.codex/history.jsonl` | Session-History (52KB+) |
| `~/.codex/log/` | Session-Logs |
| `~/.codex/models_cache.json` | Cached Modell-Liste (63KB) |
| `~/.local/bin/codex-wrapper` | Usage-Tracking Wrapper → `~/.claude/usage/codex-cli.jsonl` |

### Wichtige Befehle

```bash
# Sessions
codex                                    # Interaktive Session starten
codex exec "prompt"                      # Non-interactive
codex exec --full-auto "prompt"          # Auto (workspace-write + on-request)
codex exec -s read-only "prompt"         # Nur lesen
codex resume --last                      # Letzte Session fortsetzen
codex fork --last                        # Letzte Session branchen

# Review
codex review                             # Uncommitted Changes
codex review --base main                 # Diff gegen Branch
codex review --commit abc123             # Spezifischen Commit

# Modell und Reasoning
codex -m gpt-5.4 "prompt"               # Modell wählen
codex -c model_reasoning_effort="xhigh" exec "..."   # Maximum Reasoning

# Features
codex features list                      # Alle Feature Flags anzeigen
codex features enable multi_agent        # Feature aktivieren
codex features disable js_repl           # Feature deaktivieren
codex --enable multi_agent exec "..."    # Per-Session

# MCP
codex mcp list                           # Konfigurierte Server
codex mcp add my-tool -- my-command      # Server hinzufügen
codex mcp remove my-tool                 # Server entfernen

# Auth
codex login status                       # Auth-Status prüfen
```