initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,54 @@
+# 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 |