references/monitoring.md
# Codex CLI Monitoring Reference
This reference contains version-sensitive operational details. Verify them
against the selected launcher before use.
## Discover Current Capabilities
```bash
<launcher> --version
<launcher> --help
<launcher> exec --help
<launcher> review --help
<launcher> debug models
```
Current help exposes `--model`, `--json`, and sandbox selection. The model
catalog reports available models and their supported reasoning levels. Inspect
current configuration help or reference material for the exact reasoning-effort
override rather than copying a stale key or value from this skill.
`<launcher>` is a placeholder. It may be `codex`, an absolute path, or a
user-provided wrapper. A wrapper may inject model, authentication, profile,
approval, sandbox, or bypass settings. Preserve those semantics and do not
assume native defaults apply.
## Semantic Stream
The compact monitoring baselines are:
```bash
<launcher> exec --json --sandbox read-only --ephemeral "Review or explain"
<launcher> exec --json --sandbox workspace-write "Implement the change"
```
`--json` changes stdout to JSONL events. Useful event classes:
| Codex event | Compact host state |
|---|---|
| `thread.started` or `turn.started` | `running` |
| `item.started` | `working — <item> started` |
| `item.completed` | `working — <item> completed` |
| `turn.completed` with a successful exit | `completed` |
| `turn.failed` or nonzero exit | `failed` |
Items may represent command execution, file changes, or agent messages. Ignore
raw reasoning and avoid forwarding full command output when a short action
summary is enough.
## Polling Contract
The host's running-task ID is not the Codex thread/session ID and is not the OS
PID.
1. Start the process through the host facility that can yield while retaining
the child process.
2. Save the returned running-task ID.
3. Reuse that ID with the host's wait, poll, or resume operation.
4. Parse only new complete JSONL records.
5. If no semantic record arrives but the process is alive, retain `running`.
6. Finish only after a terminal turn event and process exit have been observed.
If the host has no resumable process facility, redirect stdout and stderr into a
directory created under `${TMPDIR:-/tmp}`, retain the PID, and poll both process
liveness and newly appended complete lines. Temporary captures may be left for
system cleanup.
## Terminal and Error Handling
- `turn.completed` and `turn.failed` are terminal turn events.
- Combine the terminal event with process exit. A final-message file or a
plausible agent message is not sufficient completion evidence.
- A nonterminal warning or error-shaped item can occur in a successful turn.
Do not classify the whole run from one item alone.
- Stderr may contain recoverable warnings. Preserve it for diagnosis, but use
terminal state and exit code to classify the run.
- If output ends with an incomplete JSON line, report an incomplete stream
rather than manufacturing completion.
`codex app-server` exposes deeper lifecycle and steering capabilities in some
versions. It is a separate integration surface; inspect its current help only
when protocol-level control is specifically required.
SKILL.md
---
name: codex-coding-agent
description: >-
Run local Codex CLI (`codex`) as an external coding executor. Use only when
explicitly selected by name.
---
# Codex Coding Agent
Use Codex CLI only after the user or active workflow explicitly selects it as
the external executor.
## Minimal Workflow
1. Set `<launcher>` to the requested Codex binary, absolute path, alias, or
wrapper. Preserve a provided wrapper; it may inject model, authentication, or
permission settings, including bypass permissions.
2. Run `<launcher> --help` and `<launcher> exec --help` before composing
version-sensitive flags. Use other subcommand help only when needed.
3. Choose the model and thinking effort deliberately, following the guidance
below and the choices currently exposed by the launcher.
4. Use monitor mode by default for any task that may take time. Use final mode
only when the task is clearly trivial and short.
5. Run from the intended repository or workspace, pass a bounded task contract,
and wait for the external process to finish.
6. Inspect the resulting diff, tests, and final answer before claiming success.
## Model and Effort
Honor explicit model or effort choices. Otherwise inspect current help and model
catalog before launching:
- For routine, bounded work, prefer a balanced model and moderate effort.
- For deep review, ambiguous debugging, cross-module design, or other high-risk
work, prefer a frontier model and high or maximum supported effort.
- Use the highest tier only when its quality benefit justifies the extra latency
or cost, and after checking whether that tier has additional behavior.
Do not hardcode model names or effort levels from this skill; the launcher's
current help and model catalog are authoritative.
## Monitor Mode (Default)
Use Codex's semantic JSON event stream and select the sandbox for the task:
```bash
# Review, explanation, or other read-only work
<launcher> exec --json --sandbox read-only --ephemeral "Your task"
# Approved implementation in the workspace
<launcher> exec --json --sandbox workspace-write "Your task"
```
Start the command with the host's long-running process facility. Keep the task ID
returned by the host, then use the host's wait, poll, or resume facility to read
only newly available output while the process runs.
Reduce the stream to small liveness signals such as:
```text
running — process alive
working — command completed
running — no new semantic event; process alive
completed
```
Ignore raw thinking/reasoning and token deltas. Treat the terminal turn event
together with process exit as completion evidence; do not kill a live process
merely because it has produced no recent semantic event.
## Final Mode
For a clearly trivial, short task, use the same task-appropriate sandbox without
`--json` and wait for the final response.
## Task Boundaries
- Use a read-only sandbox and read-only prompt for review or explanation. Use
workspace-write only for tasks expected to edit files.
- Follow current subcommand help before using review selectors, resume, profiles,
or configuration overrides.
- Do not silently bypass approvals or sandboxing, create worktrees, commit, push,
deploy, or widen task scope.
- Put optional captures in the system temporary directory. Cleanup is optional.
For event mapping, terminal-state handling, model discovery, and current
capability discovery, read [references/monitoring.md](references/monitoring.md).