Codex

Codex — Hermes Orchestration Guide

Delegate coding tasks to Codex (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Codex v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.

Prerequisites

• Install: npm install -g @anthropic-ai/Codex
• Auth: run Codex once to log in (browser OAuth for Pro/Max, or set ANTHROPIC_API_KEY)
• Console auth: Codex auth login --console for API key billing
• SSO auth: Codex auth login --sso for Enterprise
• Check status: Codex auth status (JSON) or Codex auth status --text (human-readable)
• Health check: Codex doctor — checks auto-updater and installation health
• Version check: Codex --version (requires v2.x+)
• Update: Codex update or Codex upgrade

Two Orchestration Modes

Hermes interacts with Codex in two fundamentally different ways. Choose based on the task.

Mode 1: Print Mode (-p) — Non-Interactive (PREFERRED for most tasks)

Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.

terminal(command="Codex -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)

When to use print mode:

• One-shot coding tasks (fix a bug, add a feature, refactor)
• CI/CD automation and scripting
• Structured data extraction with --json-schema
• Piped input processing (cat file | Codex -p "analyze this")
• Any task where you don't need multi-turn conversation

Print mode skips ALL interactive dialogs — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.

Mode 2: Interactive PTY via tmux — Multi-Turn Sessions

Interactive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Codex work in real time. Requires tmux orchestration.

# Start a tmux session
terminal(command="tmux new-session -d -s Codex-work -x 140 -y 40")

# Launch Codex inside it
terminal(command="tmux send-keys -t Codex-work 'cd /path/to/project && Codex' Enter")

# Wait for startup, then send your task
# (after ~3-5 seconds for the welcome screen)
terminal(command="sleep 5 && tmux send-keys -t Codex-work 'Refactor the auth module to use JWT tokens' Enter")

# Monitor progress by capturing the pane
terminal(command="sleep 15 && tmux capture-pane -t Codex-work -p -S -50")

# Send follow-up tasks
terminal(command="tmux send-keys -t Codex-work 'Now add unit tests for the new JWT code' Enter")

# Exit when done
terminal(command="tmux send-keys -t Codex-work '/exit' Enter")

When to use interactive mode:

• Multi-turn iterative work (refactor → review → fix → test cycle)
• Tasks requiring human-in-the-loop decisions
• Exploratory coding sessions
• When you need to use Codex's slash commands (/compact, /review, /model)

PTY Dialog Handling (CRITICAL for Interactive Mode)

Codex presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:

Dialog 1: Workspace Trust (first visit to a directory)

❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
  2. No, exit

Handling: tmux send-keys -t <session> Enter — default selection is correct.

Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)

❯ 1. No, exit                    ← DEFAULT (WRONG choice!)
  2. Yes, I accept

Handling: Must navigate DOWN first, then Enter:

tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter

Robust Dialog Handling Pattern

# Launch with permissions bypass
terminal(command="tmux send-keys -t Codex-work 'Codex --dangerously-skip-permissions \"your task\"' Enter")

# Handle trust dialog (Enter for default "Yes")
terminal(command="sleep 4 && tmux send-keys -t Codex-work Enter")

# Handle permissions dialog (Down then Enter for "Yes, I accept")
terminal(command="sleep 3 && tmux send-keys -t Codex-work Down && sleep 0.3 && tmux send-keys -t Codex-work Enter")

# Now wait for Codex to work
terminal(command="sleep 15 && tmux capture-pane -t Codex-work -p -S -60")

Extra submit lesson: when you paste a long prompt into the interactive TUI via tmux load-buffer + tmux paste-buffer, Codex may show the full prompt in the input area without actually sending it yet. If capture-pane shows the pasted text plus a waiting prompt, send one more Enter explicitly. Do not assume paste-buffer submitted the message.

Note: After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use --dangerously-skip-permissions.

CLI Subcommands

Print Mode Deep Dive

Structured JSON Output

terminal(command="Codex -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)

Returns a JSON object with:

{
  "type": "result",
  "subtype": "success",
  "result": "The analysis text...",
  "session_id": "75e2167f-...",
  "num_turns": 3,
  "total_cost_usd": 0.0787,
  "duration_ms": 10276,
  "stop_reason": "end_turn",
  "terminal_reason": "completed",
  "usage": { "input_tokens": 5, "output_tokens": 603, ... },
  "modelUsage": { "Codex-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
}

Key fields: session_id for resumption, num_turns for agentic loop count, total_cost_usd for spend tracking, subtype for success/error detection (success, error_max_turns, error_budget).

Streaming JSON Output

For real-time token streaming, use stream-json with --verbose:

terminal(command="Codex -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)

Returns newline-delimited JSON events. Filter with jq for live text:

Codex -p "Explain X" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Stream events include system/api_retry with attempt, max_retries, and error fields (e.g., rate_limit, billing_error).

Bidirectional Streaming

For real-time input AND output streaming:

Codex -p "task" --input-format stream-json --output-format stream-json --replay-user-messages

--replay-user-messages re-emits user messages on stdout for acknowledgment.

Piped Input

# Pipe a file for analysis
terminal(command="cat src/auth.py | Codex -p 'Review this code for bugs' --max-turns 1", timeout=60)

# Pipe multiple files
terminal(command="cat src/*.py | Codex -p 'Find all TODO comments' --max-turns 1", timeout=60)

# Pipe command output
terminal(command="git diff HEAD~3 | Codex -p 'Summarize these changes' --max-turns 1", timeout=60)

JSON Schema for Structured Extraction

terminal(command="Codex -p 'List all functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' --max-turns 5", workdir="/project", timeout=90)

Parse structured_output from the JSON result. Codex validates output against the schema before returning.

Session Continuation

# Start a task
terminal(command="Codex -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)

# Resume with session ID
terminal(command="Codex -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120)

# Or resume the most recent session in the same directory
terminal(command="Codex -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)

# Fork a session (new ID, keeps history)
terminal(command="Codex -p 'Try a different approach' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)

Bare Mode for CI/Scripting

terminal(command="Codex --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)

--bare skips hooks, plugins, MCP discovery, and AGENTS.md loading. Fastest startup. Requires ANTHROPIC_API_KEY (skips OAuth).

To selectively load context in bare mode:

Fallback Model for Overload

terminal(command="Codex -p 'task' --fallback-model haiku --max-turns 5", timeout=90)

Automatically falls back to the specified model when the default is overloaded (print mode only).

Complete CLI Flags Reference

Session & Environment

Model & Performance

Permission & Safety

Output & Input Format

System Prompt & Context

Debugging

Agent Teams

Tool Name Syntax for --allowedTools / --disallowedTools

Read                    # All file reading
Edit                    # File editing (existing files)
Write                   # File creation (new files)
Bash                    # All shell commands
Bash(git *)             # Only git commands
Bash(git commit *)      # Only git commit commands
Bash(npm run lint:*)    # Pattern matching with wildcards
WebSearch               # Web search capability
WebFetch                # Web page fetching
mcp__<server>__<tool>   # Specific MCP tool

Settings & Configuration

Settings Hierarchy (highest to lowest priority)

1. CLI flags — override everything
2. Local project: .Codex/settings.local.json (personal, gitignored)
3. Project: .Codex/settings.json (shared, git-tracked)
4. User: ~/.Codex/settings.json (global)

Permissions in Settings

{
  "permissions": {
    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
    "ask": ["Write(*.ts)", "Bash(git push*)"],
    "deny": ["Read(.env)", "Bash(rm -rf *)"]
  }
}

Memory Files (AGENTS.md) Hierarchy

1. Global: ~/.Codex/AGENTS.md — applies to all projects
2. Project: ./AGENTS.md — project-specific context (git-tracked)
3. Local: .Codex/Codex.local.md — personal project overrides (gitignored)

Use the # prefix in interactive mode to quickly add to memory: # Always use 2-space indentation.

Interactive Session: Slash Commands

Session & Context

Development & Review

Configuration & Tools

Custom Slash Commands

Create .Codex/commands/<name>.md (project-shared) or ~/.Codex/commands/<name>.md (personal):

# .Codex/commands/deploy.md
Run the deploy pipeline:
1. Run all tests
2. Build the Docker image
3. Push to registry
4. Update the $ARGUMENTS environment (default: staging)

Usage: /deploy production — $ARGUMENTS is replaced with the user's input.

Skills (Natural Language Invocation)

Unlike slash commands (manually invoked), skills in .Codex/skills/ are markdown guides that Codex invokes automatically via natural language when the task matches:

# .Codex/skills/database-migration.md
When asked to create or modify database migrations:
1. Use Alembic for migration generation
2. Always create a rollback function
3. Test migrations against a local database copy

Interactive Session: Keyboard Shortcuts

General Controls

Mode Toggles

Multiline Input

Input Prefixes

Pro Tip: "ultrathink"

Use the keyword "ultrathink" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current /effort setting.

PR Review Pattern

Quick Review (Print Mode)

terminal(command="cd /path/to/repo && git diff main...feature-branch | Codex -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1", timeout=60)

Deep Review (Interactive + Worktree)

terminal(command="tmux new-session -d -s review -x 140 -y 40")
terminal(command="tmux send-keys -t review 'cd /path/to/repo && Codex -w pr-review' Enter")
terminal(command="sleep 5 && tmux send-keys -t review Enter")  # Trust dialog
terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")

PR Review from Number

terminal(command="Codex -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

Codex Worktree with tmux

terminal(command="Codex -w feature-x --tmux", workdir="/path/to/repo")

Creates an isolated git worktree at .Codex/worktrees/feature-x AND a tmux session for it. Uses iTerm2 native panes when available; add --tmux=classic for traditional tmux.

Parallel Codex Instances

Run multiple independent Codex tasks simultaneously:

# Task 1: Fix backend
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && Codex -p \"Fix the auth bug in src/auth.py\" --allowedTools \"Read,Edit\" --max-turns 10' Enter")

# Task 2: Write tests
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && Codex -p \"Write integration tests for the API endpoints\" --allowedTools \"Read,Write,Bash\" --max-turns 15' Enter")

# Task 3: Update docs
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && Codex -p \"Update README.md with the new API endpoints\" --allowedTools \"Read,Edit\" --max-turns 5' Enter")

# Monitor all
terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")

AGENTS.md — Project Context File

Codex auto-loads AGENTS.md from the project root. Use it to persist project context:

# Project: My API

## Architecture
- FastAPI backend with SQLAlchemy ORM
- PostgreSQL database, Redis cache
- pytest for testing with 90% coverage target

## Key Commands
- `make test` — run full test suite
- `make lint` — ruff + mypy
- `make dev` — start dev server on :8000

## Code Standards
- Type hints on all public functions
- Docstrings in Google style
- 2-space indentation for YAML, 4-space for Python
- No wildcard imports

Be specific. Instead of "Write good code", use "Use 2-space indentation for JS" or "Name test files with .test.ts suffix." Specific instructions save correction cycles.

Rules Directory (Modular AGENTS.md)

For projects with many rules, use the rules directory instead of one massive AGENTS.md:

• Project rules: .Codex/rules/*.md — team-shared, git-tracked
• User rules: ~/.Codex/rules/*.md — personal, global

Each .md file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single AGENTS.md.

Auto-Memory

Codex automatically stores learned project context in ~/.Codex/projects/<project>/memory/.

• Limit: 25KB or 200 lines per project
• This is separate from AGENTS.md — it's Codex's own notes about the project, accumulated across sessions

Custom Subagents

Define specialized agents in .Codex/agents/ (project), ~/.Codex/agents/ (personal), or via --agents CLI flag (session):

Agent Location Priority

1. .Codex/agents/ — project-level, team-shared
2. --agents CLI flag — session-specific, dynamic
3. ~/.Codex/agents/ — user-level, personal

Creating an Agent

# .Codex/agents/security-reviewer.md
---
name: security-reviewer
description: Security-focused code review
model: opus
tools: [Read, Bash]
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication/authorization flaws
- Secrets in code
- Unsafe deserialization

Invoke via: @security-reviewer review the auth module

Dynamic Agents via CLI

terminal(command="Codex --agents '{\"reviewer\": {\"description\": \"Reviews code\", \"prompt\": \"You are a code reviewer focused on performance\"}}' -p 'Use @reviewer to check auth.py'", timeout=120)

Codex can orchestrate multiple agents: "Use @db-expert to optimize queries, then @security to audit the changes."

Hooks — Automation on Events

Configure in .Codex/settings.json (project) or ~/.Codex/settings.json (global):

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write(*.py)",
      "hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi"}]
    }],
    "Stop": [{
      "hooks": [{"type": "command", "command": "echo 'Codex finished a response' >> /tmp/Codex-activity.log"}]
    }]
  }
}

All 8 Hook Types

Hook Environment Variables

Security Hook Examples

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi"}]
  }]
}

MCP Integration

Add external tool servers for databases, APIs, and services:

# GitHub integration
terminal(command="Codex mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)

# PostgreSQL queries
terminal(command="Codex mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)

# Puppeteer for web testing
terminal(command="Codex mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)

MCP Scopes

MCP in Print/CI Mode

terminal(command="Codex --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)

--strict-mcp-config ignores all MCP servers except those from --mcp-config.

Reference MCP resources in chat: @github:issue://123

MCP Limits & Tuning

• Tool descriptions: 2KB cap per server for tool descriptions and server instructions
• Result size: Default capped; use maxResultSizeChars annotation to allow up to 500K characters for large outputs
• Output tokens: export MAX_MCP_OUTPUT_TOKENS=50000 — cap output from MCP servers to prevent context flooding
• Transports: stdio (local process), http (remote), sse (server-sent events)

Monitoring Interactive Sessions

Reading the TUI Status

# Periodic capture to check if Codex is still working or waiting for input
terminal(command="tmux capture-pane -t dev -p -S -10")

Look for these indicators:

• ❯ at bottom = waiting for your input (Codex is done or asking a question)
• ● lines = Codex is actively using tools (reading, writing, running commands)
• ⏵⏵ bypass permissions on = status bar showing permissions mode
• ◐ medium · /effort = current effort level in status bar
• ctrl+o to expand = tool output was truncated (can be expanded interactively)

Context Window Health

Use /context in interactive mode to see a colored grid of context usage. Key thresholds:

• < 70% — Normal operation, full precision
• 70-85% — Precision starts dropping, consider /compact
• > 85% — Hallucination risk spikes significantly, use /compact or /clear

Environment Variables

Cost & Performance Tips

1. Use --max-turns in print mode to prevent runaway loops. Start with 5-10 for most tasks.
2. Use --max-budget-usd for cost caps. Note: minimum ~$0.05 for system prompt cache creation.
3. Use --effort low for simple tasks (faster, cheaper). high or max for complex reasoning.
4. Use --bare for CI/scripting to skip plugin/hook discovery overhead.
5. Use --allowedTools to restrict to only what's needed (e.g., Read only for reviews).
6. Use /compact in interactive sessions when context gets large.
7. Pipe input instead of having Codex read files when you just need analysis of known content.
8. Use --model haiku for simple tasks (cheaper) and --model opus for complex multi-step work.
9. Use --fallback-model haiku in print mode to gracefully handle model overload.
10. Start new sessions for distinct tasks — sessions last 5 hours; fresh context is more efficient.
11. Use --no-session-persistence in CI to avoid accumulating saved sessions on disk.

Pitfalls & Gotchas

1. Interactive mode REQUIRES tmux — Codex is a full TUI app. Using pty=true alone in Hermes terminal works but tmux gives you capture-pane for monitoring and send-keys for input, which is essential for orchestration.
2. --dangerously-skip-permissions dialog defaults to "No, exit" — you must send Down then Enter to accept. Print mode (-p) skips this entirely.
3. --max-budget-usd minimum is ~$0.05 — system prompt cache creation alone costs this much. Setting lower will error immediately.
4. --max-turns is print-mode only — ignored in interactive sessions.
5. --max-turns is print-mode only — ignored in interactive sessions.
6. --permission-mode plan does NOT implement — it is planning-only. If you want Codex to actually edit files in -p mode, use --permission-mode auto (normal implementation) or --dangerously-skip-permissions when you explicitly want fully non-interactive execution.
7. Even in -p mode, permission configuration still matters — if Codex stops with an edit-permission request, rerun with --permission-mode auto or --dangerously-skip-permissions, or narrow the prompt to a single-file change. For long prompts stored in repo files, a robust pattern is: write the prompt to a file, create a tiny launcher script that cds into the repo, runs Codex -p "$(cat "$PROMPT_FILE")" --permission-mode auto --allowedTools 'Read,Edit,Write,Bash' --max-turns N 2>&1 | tee "$LOG", start that launcher with Hermes terminal(background=true), then monitor with process(action='poll'|'wait'|'log'). This keeps the prompt file auditable, avoids shell-quoting mistakes in long inline prompts, and gives you a durable log file under tmp/Codex-logs/ even when the subprocess emits no immediate stdout.
8. Even in -p mode, permission configuration still matters — if Codex stops with an edit-permission request, rerun with --permission-mode auto or --dangerously-skip-permissions, or narrow the prompt to a single-file change. For long prompts stored in repo files, a robust pattern is: write the prompt to docs/plans/...md, launch Codex -p ... "$PROMPT" in a background subprocess, then monitor with Hermes process polling and inspect git diff after completion.
9. For dirty worktrees, use a two-phase Codex pattern: implement first, then run a separate commit-only prompt — when the repo already has unrelated modified/untracked files, a write-capable Codex run can drift into nearby docs or fail to stage exactly the intended paths. Safer pattern: (a) first run a file-based prompt that only creates/edits the target artifacts and explicitly forbids broad areas, then (b) run a second file-based "commit-only" prompt that verifies exact diffs, stages only the intended file paths with surgical git add <path>..., commits, and pushes. This worked well for session-log portability transfer in workspace-hub after an initial run drifted into docs/plans/README.md and hit a turn cap.
10. Codex -p may succeed with little or no useful stdout summary; verify via git and file state, not output text alone — a background Codex -p ... | tee log run can exit 0 with minimal stdout while still having produced the desired file changes and git commit. After completion, always inspect git status, git log -1, git show --stat HEAD, and the target files themselves instead of assuming the absence of a rich textual summary means the run failed.
11. In interactive tmux runs, actively police scope drift with external git status checks — Codex can claim it cleaned up forbidden edits while unrelated files remain modified or newly created. For gated issue execution, periodically compare the live worktree outside the tmux session (git status --short, git diff --name-only) against the allowed path contract. If drift appears, interrupt with Ctrl-C, send an explicit cleanup command naming the forbidden files, then independently verify the cleanup before allowing the run to continue. Do not trust the model's verbal "cleanup complete" without an external git check.
12. When a scoped interactive run keeps drifting, keep the useful edit and kill the session rather than letting it wander — if Codex repeatedly creates forbidden files (e.g. unrelated scripts/tests/skills) despite corrective prompts, stop the tmux session, manually remove the stray artifacts, keep only the intended diff if it is clean, and finish the commit/closeout yourself. This is often lower risk than trying to recover the same session indefinitely.
13. Codex may use python instead of python3 — on systems without a python symlink, Codex's bash commands will fail on first try but it self-corrects.
14. Interactive Codex can fail immediately with API 500 errors even when tmux launch, auth, and prompt wiring are correct — if the TUI shows API Error: 500 ... Internal server error before any real work starts, treat it as an upstream Codex service failure, not a tmux/orchestration bug. Practical response order: (a) retry once in a fresh tmux session, optionally with a shorter prompt or different model, (b) if the 500 persists, stop burning cycles and fall back to a non-Codex path (main-agent execution, approval-safe prep artifacts, or deferred retry later). Do not assume repeated Enter/re-pasting the same prompt will fix it.
15. Malformed project .Codex/settings.json can prevent Codex from entering the TUI at all; bypass with --setting-sources user when needed — if launch shows Settings Error ... Invalid or malformed JSON and offers 1. Exit and fix manually / 2. Continue without these settings, your automated prompt paste can fall through to the underlying shell after Codex exits, causing the pasted task text to execute as bash commands. Robust recovery pattern: relaunch with Codex --setting-sources user ... (or otherwise exclude project/local settings), then pass the task as the initial Codex prompt argument instead of pasting multiline text after startup. This avoids both the malformed-settings blocker and accidental shell execution of the prompt.
16. For plan-review issues, interactive Codex should be used for approval-safe execution prep only, not implementation — when an issue is not yet status:plan-approved, a useful fallback is to launch Codex with a constrained prompt that only prepares execution packets, prompt files, inventory manifests, or GitHub prep comments under safe paths like tmp/ and docs/reports/. This preserves momentum without violating the approval gate.
17. Session resumption requires same directory — --continue finds the most recent session for the current working directory.
18. Trust dialog only appears once per directory — first-time only, then cached.
19. Background tmux sessions persist — always clean up with tmux kill-session -t <name> when done.
20. Slash commands (like /commit) only work in interactive mode — in -p mode, describe the task in natural language instead.
21. --bare skips OAuth — requires ANTHROPIC_API_KEY env var or an apiKeyHelper in settings.
22. Context degradation is real — AI output quality measurably degrades above 70% context window usage. Monitor with /context and proactively /compact.
23. Interactive Codex sessions can fail immediately with API 500 before any tool use — if a tmux-launched Codex --dangerously-skip-permissions session shows repeated API Error: 500 ... Internal server error at the first prompt, the launch plumbing may still be fine while the upstream Codex service is unhealthy. Practical recovery pattern:

• verify the failure in-pane with tmux capture-pane
• retry once with a fresh tmux session and, if useful, a different model flag (for example --model sonnet)
• if failures persist, stop burning time on retries and fall back to a non-Codex path for the same deliverable (for example: prepare the execution packet manually, use another agent/provider, or convert the task into approval-safe prep work)
• keep the tmux session names and captured errors as evidence so the user can see the requested interactive-Codex method was attempted
• when the issue is not yet approved, use the outage as a cue to produce execution-support artifacts rather than unauthorized implementation

Rules for Hermes Agents

1. Prefer print mode (-p) for single tasks — cleaner, no dialog handling, structured output
2. Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI
3. Always set workdir — keep Code

…(truncated)