William Valentin
103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# Codex CLI as a Flynn subagent (runbook)
|
||
|
||
This runbook documents how Flynn uses the **Codex CLI** as an external “subagent” for certain tasks.
|
||
|
||
It is intentionally pragmatic and should be updated as we learn.
|
||
|
||
## Goals
|
||
|
||
- Use Codex CLI reliably in **non-interactive** contexts (Flynn backends, scripts).
|
||
- Prefer predictable, easy-to-ingest output.
|
||
- Treat subagent output as *advice* that Flynn digests and verifies when possible.
|
||
|
||
## Key constraints
|
||
|
||
### Interactive mode requires a TTY
|
||
Running `codex` (no subcommand) is the interactive TUI and fails in non-interactive usage (e.g., from a backend runner) with errors like:
|
||
|
||
- `Error: stdin is not a terminal`
|
||
|
||
**Therefore, Flynn must use `codex exec`**.
|
||
|
||
Reference: https://developers.openai.com/codex/noninteractive/
|
||
|
||
## Default invocation
|
||
|
||
### Plain-text (default)
|
||
Flynn’s default is **plain-text stdout** (no JSON streaming) because it is the most compatible with external-backend execution and easiest to digest.
|
||
|
||
Pattern:
|
||
|
||
```bash
|
||
codex exec --ephemeral -m gpt-5.3-codex "<PROMPT>"
|
||
```
|
||
|
||
Behavioral expectations:
|
||
- **stdout**: final assistant message (what Flynn consumes)
|
||
- **stderr**: logs/progress (ignored unless debugging)
|
||
|
||
### Why `--ephemeral`
|
||
Use `--ephemeral` for backend/subagent usage to avoid persisting sessions to disk.
|
||
|
||
## When to use `--json`
|
||
|
||
Codex supports `--json` to emit an event stream (JSONL). Flynn will only opt into this when it is clearly beneficial, e.g.:
|
||
|
||
- debugging / auditing where event-level structure matters
|
||
- programmatic extraction where the plain-text output is ambiguous
|
||
|
||
Pattern:
|
||
|
||
```bash
|
||
codex exec --ephemeral --json -m gpt-5.3-codex "<PROMPT>"
|
||
```
|
||
|
||
Notes:
|
||
- `--json` changes stdout format to **JSONL events**, which is not as drop-in as plain text.
|
||
- If/when Flynn grows a dedicated parser for Codex JSONL, we can consider making `--json` the default.
|
||
|
||
## Model selection
|
||
|
||
Default model:
|
||
- `gpt-5.3-codex`
|
||
|
||
Policy:
|
||
- Keep a single default unless a task clearly benefits from a different one.
|
||
- If a run fails with model availability errors, verify via a small `codex exec -m <MODEL> "test"` smoke test and update this runbook + config.
|
||
|
||
## Prompting guidance (subagent hygiene)
|
||
|
||
- Put the **task** first.
|
||
- Specify the expected **output format** when necessary.
|
||
- Provide only relevant context; avoid leaking secrets.
|
||
- If Codex is being used to draft code changes, ask it for:
|
||
- exact file paths
|
||
- minimal diffs/patches
|
||
- assumptions and risks
|
||
|
||
## How Flynn digests Codex output
|
||
|
||
When Flynn uses Codex:
|
||
|
||
1. **Digest**: summarize the useful pieces and discard irrelevant content.
|
||
2. **Verify** where possible (local grep/tests/lint) before claiming correctness.
|
||
3. **Integrate** into the final response as:
|
||
- a patch/commit
|
||
- a concise plan
|
||
- extracted structured data
|
||
|
||
Raw Codex output is shown only when:
|
||
- Will asks for it
|
||
- there’s ambiguity or a failure that requires inspection
|
||
|
||
## Troubleshooting
|
||
|
||
- `stdin is not a terminal`
|
||
- You invoked interactive `codex` instead of `codex exec`.
|
||
|
||
- Output is noisy / includes progress
|
||
- Ensure you’re reading stdout only; progress typically goes to stderr.
|
||
|
||
- Need deterministic structured output
|
||
- Use `--json` and add a parser (or request an explicit format in the prompt).
|