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 |
@@ -0,0 +1,73 @@
+# OpenCode CLI — Detailed Integration Guide
+
+[OpenCode](https://opencode.ai) is a provider-agnostic, open-source AI coding agent. This reference covers binary resolution, session management, and key pitfalls.
+
+## Binary Resolution
+
+Shell environments may resolve different OpenCode binaries. Check:
+
+```bash
+terminal(command="which -a opencode")
+terminal(command="opencode --version")
+```
+
+If needed, pin an explicit binary path: `$HOME/.opencode/bin/opencode run '...'`
+
+## Interactive Sessions (Background)
+
+```bash
+# Start TUI in background
+terminal(command="opencode", workdir="~/project", background=true, pty=true)
+
+# Send a prompt
+process(action="submit", session_id="<id>", data="Implement OAuth refresh flow")
+
+# Monitor
+process(action="log", session_id="<id>")
+
+# Exit — use Ctrl+C, NOT /exit
+process(action="write", session_id="<id>", data="\x03")
+```
+
+**Important:** Do NOT use `/exit` — it opens an agent selector instead. Use Ctrl+C (`\x03`) or `process(action="kill")`.
+
+## TUI Keybindings
+
+| Key | Action |
+|-----|--------|
+| Enter | Submit message |
+| Tab | Switch between agents |
+| Ctrl+P | Command palette |
+| Ctrl+X L | Switch session |
+| Ctrl+X M | Switch model |
+| Ctrl+X N | New session |
+| Ctrl+C | Exit |
+
+## PR Review
+
+```bash
+terminal(command="opencode pr 42", workdir="~/project", pty=true)
+```
+
+Or review in a temporary clone for isolation.
+
+## Session & Cost Management
+
+```bash
+opencode session list
+opencode stats
+opencode stats --days 7 --models anthropic/claude-sonnet-4
+```
+
+## Common Flags
+
+| Flag | Use |
+|------|-----|
+| `run 'prompt'` | One-shot execution and exit |
+| `-c` / `--continue` | Continue last session |
+| `-s <id>` | Continue a specific session |
+| `--agent <name>` | Choose agent (build or plan) |
+| `--model provider/model` | Force specific model |
+| `--thinking` | Show model thinking blocks |
+| `--format json` | Machine-readable output |
+| `-f <path>` | Attach file(s) to the message |