tobihagemann/codex-exec

Codex Exec

Autonomous task execution via the codex CLI. Runs non-interactively. Progress streams to stderr; final result on stdout.

codex exec "task description" < /dev/null

For large context, pipe it via stdin. The prompt stays as the argument, context is passed as <stdin> automatically:

cat context.txt | codex exec "question about the context"

Sandbox

All codex Bash calls require dangerouslyDisableSandbox: true (network access to OpenAI API). Without it, codex crashes with an Operation not permitted panic from the system-configuration crate before the model runs.

Stdin Gotcha

Codex reads from stdin whenever stdin is non-TTY (per codex exec --help: "If stdin is piped and a prompt is also provided, stdin is appended as a <stdin> block"). In subagent and subprocess contexts the harness leaves stdin connected to a pipe that never EOFs, so a bare codex exec "..." hangs forever, printing only Reading additional input from stdin....

Always redirect stdin on non-piped invocations:

codex exec "task description" < /dev/null

The piped form (cat context.txt | codex exec "...") is safe — cat closes the pipe after the file, sending EOF.

Synchronous Execution

Run codex via the Bash tool (timeout: 3600000, do not set run_in_background). On long runs the harness may force the call into the background anyway; the Bash result then contains a background ID instead of codex output. Poll the background ID with BashOutput until codex completes, then treat the final output as the synchronous result.

If you are a subagent, do not pair codex exec with Monitor. Wait for the Bash call to return before emitting final text. Monitor only delivers events during your current turn; events after you emit final text are dropped. Backgrounding codex and idling on Monitor produces a false-complete: you return "Waiting for codex to finish" before codex has produced anything. The same false-empty trap applies if the harness force-backgrounds the call and you return the background ID as if codex finished — see /peer-review subagent-wrapping for the recovery pattern.

Permission Levels

| Level | Flag | When to Use | |-------|------|-------------| | Read-only (default) | (none) | Analysis, code reading, generating reports | | Workspace write | --sandbox workspace-write | Editing files within the project | | Full access | --sandbox danger-full-access | Installing packages, running tests, system operations | | Full auto | --full-auto | Combined with a sandbox level for unattended execution |

For fix or implementation tasks, default to --sandbox workspace-write --full-auto so Codex can edit files without confirmation prompts. Use read-only for analysis or research tasks.

Options

| Option | Description | |--------|-------------| | --full-auto | Allow file edits without confirmation prompts | | --sandbox <level> | Permission level: danger-full-access, workspace-write | | --json | JSON Lines output (progress + final message) | | -o <path> | Write final message to a file | | --output-schema <path> | Enforce JSON Schema on the output | | --ephemeral | No persisted session files | | --skip-git-repo-check | Bypass git repository requirement |

Prompt Shaping

Codex uses XML tags in its own context scaffolding, so the model parses them natively. Structure prompts with XML tags for clearer responses:

• <task>: The concrete job and relevant context.
• <structured_output_contract>: Required output shape, ordering, and format.
• <compact_output_contract>: Same purpose but for concise prose responses.
• <grounding_rules>: When claims must be evidence-based.
• <dig_deeper_nudge>: Push past surface-level findings to check for second-order failures.
• <verification_loop>: When correctness matters — ask Codex to verify before finalizing.

Keep prompts compact, with tight output contracts. One clear task per exec call.

Parallel Execution

Codex supports parallel sub-agents via spawn_agent / wait_agent. The model will not fan out unless the prompt explicitly requests it. See references/parallel-execution.md for patterns and limitations.

Interpreting Results

• Exec output is a starting point, not a guaranteed solution
• Cross-reference suggestions with project documentation and conventions
• Test incrementally rather than applying all changes at once
• For file-editing tasks, always review the diff before committing