docs/runbooks/codex.md

Codex Runbook

This repo has project-local Codex setup:

• AGENTS.md contains durable repo instructions.
• .codex/config.toml raises the project instruction byte limit, uses CLAUDE.md as a fallback instruction file, keeps sandboxing conservative, and enables hooks.
• .codex/hooks/stop_check.py prints wrap-up reminders when code/config changes may need tests, docs, or UI verification.

Verify Instruction Loading

From the repository root:

codex --ask-for-approval never "Summarize the active project instructions."

Expected: Codex should mention AGENTS.md, hackathon prize fit, event-ledger architecture, uv commands, docs rules, and the Codex co-author trailer.

Trust Project Config

Codex loads .codex/config.toml and project-local hooks only after the project is trusted. If the hook does not appear, trust the repository in Codex and restart the session.

Review hooks with:

/hooks

Recommended Codex Workflow

1. Ask Codex to inspect relevant files before editing.

2. Make narrow changes that preserve the deterministic no-key path.

3. Update docs/ADRs/journal entries when public behavior or architecture changes.

4. Run:

   uv run pytest tests/ -q
   uv run ruff check .
   

5. Commit only when asked, with:

   Co-authored-by: Codex <codex@openai.com>
   

What Belongs In User Config Instead

Keep these out of the repo-scoped config:

• Model/provider/auth settings.
• Telemetry endpoints.
• Personal notification commands.
• Broad command auto-approval rules.
• Machine-specific writable roots.