codex-goal-overseer

name	codex-goal-overseer
description	Read-only overseer for a Codex CLI session running /goal autonomously. A dedicated Claude Code session can either LAUNCH a fresh, fully-autonomous Codex as a subagent (codex --dangerously-bypass-approvals-and-sandbox, optionally seeded with a /goal) or ATTACH to one already running, then audits it on a self-managed cron tick using read-only Explore subagents (model opus). It derives the project's drift criteria from the target's own transcript and, on a finding, sends a single Escape to soft-stop the run, lands it idle, logs the finding to the terminal and a log file, and PAUSES -- handing off to the human. After the human reviews and directs a new instruction, the overseer types and submits it into the interrupted /goal so it resumes, then optionally auto-resumes the audit. The only writes to the target are the Esc and the human-directed instruction; everything else is read-only. Use to supervise an autonomous Codex /goal run for direction drift, fabricated data, fake/stub implementations, and broken project invariants. Triggers on "monitor codex goal", "launch and watch a codex goal", "oversee codex /goal", "watch the codex session", "babysit the codex goal run", or any request to launch, supervise, interrupt, or hand off an autonomous Codex build loop from a separate session.
argument-hint	[--launch "<objective>" | <codex-session-id> <session:window.pane>] [--cadence 1h] [--principles "<rules>"] [--no-resume]
user-invocable	true

Codex Goal Overseer

A dedicated Claude Code session pairs with a Codex CLI session that is autonomously running /goal (a long-running, self-driving build loop) and audits it for trouble. It never writes the target's code. When it finds a problem it does exactly two things to the target -- soft-stop it (Escape) and, after the human reviews, type the human's new instruction back in -- and otherwise only reads.

The session is an auditor with a kill-switch and a handoff, not an automation agent. Explicit locators, runtime-derived criteria, and a human-in-the-loop on every course correction are what make it reusable without making it dangerous. It can also start the Codex it watches, but the human, not the overseer, decides every new direction.

Two ways to get a target

• Launch mode (new). The overseer creates its own tmux pane, starts a fully-autonomous Codex there, optionally seeds it with an initial /goal, then resolves the pane + session id and begins auditing. The launch uses exactly codex --dangerously-bypass-approvals-and-sandbox. See Launch mode.
• Attach mode (existing). You already have a Codex /goal running; you pass its session id and tmux pane, and the overseer attaches and audits. See Attach mode.

Either way, once a (session-id, pane) pairing is established the audit loop is identical (see The audit tick). The skill applies to any Codex /goal session: it needs only where to read (the transcript) and where to act (the tmux pane), and it bootstraps everything else -- including what counts as "drift" -- from the target itself.

Invocation

/codex-goal-overseer --launch "<objective>" [--cadence 1h] [--principles "<rules>"] [--no-resume]
/codex-goal-overseer <codex-session-id> <session:window.pane> [--cadence 1h] [--principles "<rules>"] [--no-resume]

• --launch "<objective>" -- Launch mode. Create a new pane, start codex --dangerously-bypass-approvals-and-sandbox, seed it with /goal <objective>, resolve the pane + session id, then audit. Omit the objective text (--launch) to start Codex without seeding a goal (you will seed it yourself).
• <codex-session-id> -- Attach mode. The Codex session UUID. Resolves the transcript at ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl, the read surface (progress + the human's prior steering).
• <session:window.pane> -- Attach mode. The tmux pane where the Codex TUI runs, e.g. Z-manage:main.2. Codex usually occupies a single pane inside a window, so the locator is pane-precise. This is the act surface (Esc + the human's instruction).
• --cadence -- audit tick interval (default 1h).
• --principles "..." -- extra drift rules to merge on top of what is derived from the transcript (for rules the human holds that are not in the transcript).
• --no-resume -- after a human-directed instruction is delivered, do not auto-resume the audit cron; leave it paused for the human to resume. Default is to resume the audit automatically.

If you are not sure which pane/session is the live Codex, run scripts/locate-codex.sh first: it sweeps every tmux pane, flags the ones that look like a live Codex TUI, and lists recent Codex /goal transcripts, so you can confirm the exact (session-id, pane) before attaching.

The overseer must run in its own pane on the same tmux server as the target.

Alerting (headless host)

This host is headless (no desktop, no audio), reached over SSH, so alerting is terminal output plus a log file -- there are no phone or push notifications.

Every finding, interrupt, handoff, terminal condition, and delivered instruction is both printed in the overseer's terminal and appended to:

./temp/codex-goal-overseer/monitor.log

Each log line is a structured, self-contained record (timestamp, tick id, what, and the evidence pointer -- a transcript turn/timestamp or a git path), so the log alone reconstructs why the overseer acted. The inject-steer.sh and interrupt-target.sh evidence dumps land under the same ./temp/codex-goal-overseer/ root, so a finding and the keystrokes it triggered are auditable together.

Read-only safety contract

This is load-bearing, not advisory. The overseer's value depends on it being unable to corrupt what it watches.

The only writes the skill makes to the target are two keystroke actions, each through a hardened script after verify-target confirms a live Codex pane:

1. the Escape interrupt on a finding (scripts/interrupt-target.sh), and
2. the human-directed instruction, typed and submitted only after the human has reviewed and directed it (scripts/inject-steer.sh).

Everything else the overseer does is read-only.

Allowed (read-only): git status/diff/log/show, rg/grep, jq, tail, head, sed (read), ls, find, stat, wc, python for parsing only, tmux capture-pane / list-panes / display-message.

Banned: any write into the target repo's tracked files; apply_patch or any editor; git add/commit/reset/checkout/clean; builds or tests that mutate or produce artifacts; package installs; deletions; modifying the target transcript; and any raw tmux send-keys to the target other than the two sanctioned actions above. There is no autonomous steering: the overseer never composes and sends a course correction on its own -- a human authors every new instruction.

Subagents are Explore-type only -- they physically lack Edit/Write/build tools. Their prompts must also state, in words, that they may only read.

The only other writes the skill performs: (a) its own cron via CronCreate/CronDelete, and (b) the log + evidence dumps under ./temp/codex-goal-overseer/. Neither touches the target repo or transcript.

Launch mode

Launch mode lets the overseer run Codex itself as a fully-autonomous subagent and then watch it.

FULL HOST PERMISSIONS, NO SANDBOX. Launch runs exactly codex --dangerously-bypass-approvals-and-sandbox: maximum permissions, no approval prompts, no sandbox. The launched Codex can read, write, and run anything you can. This is the user's explicit, authorized automation choice and is appropriate only for goals the user trusts to run unattended. The overseer that audits the result is the safety rail; the launch itself has none. Do not use launch mode for an untrusted or exploratory objective -- use Codex's normal sandboxed flow for those.

Flow:

1. Confirm intent. Launch mode starts a no-sandbox, no-approval agent. State that plainly and proceed on the user's explicit request (the --launch invocation is that request).
2. Launch. Run scripts/launch-codex.sh --goal "<objective>" (drop --goal to start without seeding). It creates a fresh tmux window, starts codex --dangerously-bypass-approvals-and-sandbox, waits until the pane is a live Codex TUI (same verify-target gate the rest of the skill uses), submits /goal <objective> via inject-steer.sh send when an objective is given, then resolves the newest rollout session id that appeared after launch.
3. Capture the pairing. Parse the script's PANE= and SESSION_ID= lines. That (session-id, pane) is exactly what attach mode would have taken.
4. Audit. Continue into Loop and cadence with that pairing -- run the light preflight, one tick immediately, then schedule the cron.

scripts/launch-codex.sh exit codes: 0 launched (id resolved), 10 tmux unavailable / pane not created, 11 codex CLI not found, 12 pane never became a live Codex TUI, 13 initial /goal seed failed to submit (pane is live -- seed it by hand, then attach), 14 live but no new rollout id resolved yet (re-scan ~/.codex/sessions or run locate-codex.sh), 64 usage error. On 13/14 the pane is alive, so prefer attaching to it over relaunching (relaunching would spawn a second autonomous Codex).

Attach mode

You already have a Codex /goal running. Pass its <codex-session-id> and <session:window.pane>. The overseer:

1. Resolves the transcript from the session id and confirms the pane with inject-steer.sh verify-target (a live Codex TUI, not a shell, not the overseer's own Claude pane, not in copy mode).
2. If either is missing/ambiguous (transcript not found or rotated, pane gone or not Codex), it stops and asks you to re-specify -- it never guesses a different transcript or pane. scripts/locate-codex.sh lists the candidates.
3. Proceeds into Loop and cadence with that pairing.

The audit tick

Each cron firing re-enters this skill fresh. Subagents do the heavy transcript reading and return only conclusions, so the overseer's own context stays lean across a multi-hour run. The tick, in order:

1. Re-locate the target -- resolve the transcript from the session id; confirm the tmux pane via inject-steer.sh verify-target. If the transcript is missing/ambiguous/rotated, or the session ended, or /goal is complete or blocked, or the pane is gone/renamed/not a live Codex TUI -> log the diagnosis to terminal + monitor.log and, for terminal conditions, offer CronDelete.
2. Refresh drift criteria -- re-derive from the transcript (see below), newer steering overriding older, merged with --principles.
3. Dispatch three read-only Explore subagents in parallel (see Audit dimensions), each on the Opus model (dispatch with model: opus). Strongly restate read-only in each prompt.
4. Synthesize against the four judgment criteria.
5. Decide: clean -> append a one-line "clean" record to monitor.log and leave a one-line conclusion in the session; no interrupt. Finding -> On a finding.

A clean tick is quiet: a single log line, no interrupt, no handoff.

Drift-criteria derivation

The strength of this skill is that "what counts as drift" is not hardcoded -- it is read from the target session's own human steering history each tick.

• Parse the transcript line-by-line (it can be tens of MB; never read it whole). Each line is JSON with type and payload; payload.type is one of user_message, agent_message, reasoning, function_call, patch_apply_end, thread_goal_updated. Timestamps are ISO UTC.
• Extract the human's user_message entries and distill the project's first-principles rules from them.
• Newer steering overrides older. Each derived rule should cite its originating turn/timestamp. When two human instructions genuinely conflict, prefer the most recent explicit one; if still ambiguous, ask the human -- do not interrupt Codex on a guess.
• Merge any --principles the human passed at invocation.

These derived rules are intentionally not persisted -- re-deriving each tick keeps them in sync as the human's priorities evolve and avoids a second source of truth.

Audit dimensions

Three read-only Explore subagents per tick, each blind to the others, each dispatched on the Opus model (the audit judgement needs the strongest model; do not downgrade these to a smaller tier):

• Transcript progress -- what Codex did since the last checkpoint, what it claims, whether it ran its own independent audits or self-certified, and the /goal state (active / blocked / complete, token + time burn).
• Git commits + worktree diff since the last checkpoint HEAD -- red flags: hardcoded magic numbers used as simulation/expected RESULTS baked into producer code or tests; pass/status with no real artifact behind it; disabled or skipped functional tests; stub returns dressed as real computation; whether the unpushed-batch-then-review discipline is being followed; and commit-message hygiene.
• Artifact reasonableness -- the invariants here are derived from the transcript/repo, not hardcoded. Typical shapes: distinct kernels/apps must produce distinct numbers; results must trace to a real report (not fabricated, not all-zero, missing-evidence not written as zero); a constrained model must not be more optimistic than its idealized baseline; first-principles monotonicity (e.g. longer input must cost more).

Judgment criteria

1. Drift -- violates the human's established principles. But deep-diving or optimizing a fundamental design decision is NOT drift -- it is exactly the kind of foundational work the human wants; only a genuine departure from stated principles counts.
2. Fabricated data -- hardcoded numbers as results, pass-without-evidence, or an artifact that exists but whose data is not reasonable.
3. Fake / stub implementation -- plausible-looking returns claimed as real hardware-aware / functional behavior.
4. Project-specific invariant breaks -- the derived invariants above, most notably distinct things reporting identical numbers, where the target's own audit may have let it through.

On a finding: interrupt, log, hand off

When the synthesis is a real finding (not foundational work), the overseer does not decide the fix. It stops Codex and hands off to the human.

1. Verify the target, then soft-stop it -- scripts/interrupt-target.sh <pane>: verify-target -> send a single Escape -> confirm the pane left its Working / streaming state and is back at an idle composer. Escape is a soft interrupt: the Codex process stays alive and the goal context is intact; only the in-flight turn stops, so the human can review and re-instruct without losing the thread. If verify-target says the pane is not a live Codex (or is gone), refuse to send Escape -- log the diagnosis and stop. A wrong pane is never interrupted.
2. Report the finding to the terminal and append it to monitor.log, structured: what tripped which judgment criterion, with the evidence pointer (the transcript turn/timestamp or the git path), and the interrupt-target.sh exit code.
3. Pause the audit loop -- stop auto-ticking (CronDelete the audit job, or suspend it) so the overseer is not re-auditing a deliberately-stopped run. The overseer now waits for the human; it does not compose or send any instruction on its own.

interrupt-target.sh exit codes: 0 interrupted and idle, 10 target gone, 11 not a live Codex TUI (refused), 20 pane unstable, 40 still Working after Escape (soft stop did not take), 64 usage error. On 40, do not assume the turn stopped: surface the evidence dump, report that the soft stop did not take, and leave it to the human (a second Escape may be warranted, or Codex may be mid-tool-call). On 10/11, treat as a re-locate failure -- never send a follow-up instruction to a pane you could not interrupt.

After the handoff: deliver the human's instruction

The human reviews the interrupted run in the terminal and directs a new instruction. The overseer is the mechanical delivery arm for that human-authored instruction -- it carries intent the human supplied; it does not invent the course correction.

1. Verify the target again (inject-steer.sh verify-target). If the pane is no longer a live Codex, refuse and tell the human; never type into a wrong pane.
2. Compose for the goal contract. Take the human's instruction and make it a well-formed message for the active /goal thread (see Composing the instruction). Preserve the human's intent; add the contract structure. If the instruction contradicts the active goal or an established principle, surface that and confirm rather than silently delivering something incoherent.
3. Deliver it -- inject-steer.sh type <pane> <file> lands the text in Codex's composer unsent; the human may eyeball it in the pane; then inject-steer.sh submit <pane> <file> presses Enter and verifies the send. (Use inject-steer.sh send for type+submit in one step if the human said "just send it".) Text is always passed via a file, never argv. Report the exit code; on a nonzero exit, surface the evidence dump and do not assume the instruction was delivered -- hand it back to the human.
4. Resume the audit -- by default, CronCreate the audit tick again so the overseer watches the now-continuing /goal. With --no-resume, leave it paused for the human to resume manually.

The interrupted /goal continues from the human's instruction; the overseer goes back to read-only auditing.

Composing the instruction

The human-directed instruction is a message injected into an active Codex /goal thread, so it must speak the goal contract's language, not just say "keep going" or dump a vague ask. Before composing, you may consult the bundled reference references/codex-goal-cookbook.md (the guide to Codex Goals) to keep the instruction consistent with how a goal is defined and audited. It is an optional phrasing aid, not a gate.

A good instruction:

• Names the outcome / end state it wants, in terms the live goal can audit.
• Points at the verification surface -- the test, benchmark, report, artifact, or evidence that proves it -- never "trust me, it is done".
• Restates the constraints that must not regress (the project's established principles: SSOT, no fabricated data, no fake/stub, and so on).
• Respects the goal's boundaries (the files, tools, and scope already in play).
• Says how Codex should choose the next action, and when to treat itself as blocked rather than declare false success.
• Stays narrow enough to audit but open enough for Codex to investigate.

Keep it tight and single-purpose: the instruction augments the live goal, it does not restate or redefine the whole goal. The human's intent always governs; the contract structure is just how it is phrased.

The scripts

They all live under ~/.claude/skills/codex-goal-overseer/scripts/. The two that write to the target make the keystroke dance deterministic instead of LLM-improvised: a TUI's render timing is racy, and reacting to pane text by hand risks fumbling quoting on CJK/quotes/newlines or double-submitting. Each turns "looks like it worked, probably" into a checkable state machine with exit codes, and the orchestrating session branches on the exit code -- it never eyeballs pane text to decide success.

launch-codex.sh (launch mode)

Creates a fresh tmux window, runs exactly codex --dangerously-bypass-approvals-and-sandbox, waits until the pane is a live Codex TUI (same verify-target detection), optionally submits an initial /goal <objective>, resolves the newest post-launch rollout session id, and prints PANE= / SESSION_ID=. Exit codes as in Launch mode. The no-sandbox / no-approvals flag string is a single constant in the script so the launch contract cannot drift.

interrupt-target.sh (the Escape)

verify-target -> send a single Escape -> verify the pane is no longer in its Working / streaming state. Non-mutating beyond the one Escape. Exit codes as in On a finding. Refuses (exit 11) anything that is not a live Codex pane.

inject-steer.sh (the human-directed instruction)

The hardened type/submit machinery for delivering the human's instruction. Text is always passed via a file, never argv.

Subcommand	Contract
verify-target <pane>	Non-mutating health check: pane resolves, not dead, input not off, not in copy mode, identified as a live Codex process, capture nonempty and stable. (Codex runs on the PRIMARY screen, so the target is matched by process tree, not alternate-screen -- which is what stops the instruction from landing in a plain shell or the overseer's own Claude pane.)
type <pane> <file>	load-buffer then paste-buffer -p -r (bracketed paste; -r stops LF becoming Enter), then verify the text landed near the input -- either as a normalized tail-signature (short pastes render inline) or as a collapsed [Pasted Content N chars] placeholder whose count matches the file (long pastes; Codex collapses them in the composer). No Enter.
submit <pane> [file]	Press Enter, verify the instruction left the live input line (literal signature or the collapsed placeholder), retry Enter once only if there was no pane delta and the text is still in the input region; stop on any ambiguity. At most two Enters.
send <pane> <file>	Atomic type + submit. Used both by launch-codex.sh to seed the initial /goal and to deliver a "just send it" instruction.

Exit codes: 0 success, 10 target missing/dead, 11 not a live Codex TUI, 20 pane busy/unstable, 30 paste failed, 31 text-landed verify failed, 40 submit verify failed, 41 ambiguous post-Enter (retry suppressed), 64 usage error. A nonzero exit means do not assume the instruction was sent: surface the evidence dump and hand it back to the human.

Every run of either writing script dumps evidence (target metadata, before/after-paste/after-enter captures, byte count + hash) under ./temp/codex-goal-overseer/, alongside the finding log -- so each keystroke is auditable next to the finding that caused it.

locate-codex.sh (discovery, read-only)

Sweeps every tmux pane, flags the ones that look like a live Codex TUI, and lists recent Codex /goal transcripts so you can confirm the exact (session-id, pane) before attaching. Strictly read-only: no tmux state mutated, no files written.

Loop and cadence

The overseer self-manages its own cron. On first invocation (after a launch or an attach): run a light preflight (confirm the pairing resolves and verify-target passes), one audit tick immediately, then CronCreate a recurring job (default hourly, on an off-the-hour minute to dodge top-of-hour congestion). Report the cron id so the human can stop it. The job re-enters this skill each firing.

The cron is paused on a finding (see On a finding) and resumed after the human's instruction is delivered (unless --no-resume). CronDelete the job on termination, when /goal completes, or when the target is gone.

The cron lives in the overseer session's memory: closing the overseer session or its tmux pane stops the loop. The overseer pane must stay alive. (In launch mode, the overseer pane and the Codex pane are different panes on the same server; closing the overseer pane stops the auditing, not the launched Codex.)

Failure modes

• Transcript not found / multiple matches / rotated -> halt the tick, log, ask the human to re-specify; never guess a different transcript.
• Session ended, or /goal complete or blocked -> terminal-condition log, offer CronDelete.
• Pane missing / renamed / reused, or verify-target fails (not Codex, in copy mode, input off, dead) -> never Escape, never type; log and ask.
• Multiple /goal candidates -> locate-codex.sh lists them; the human confirms.
• Derived-criteria conflict -> newer human instruction wins; genuine ambiguity -> ask the human, do not interrupt.
• interrupt-target.sh exit 40 (still Working) -> do not assume stopped; surface evidence; leave to the human.
• inject-steer.sh nonzero exit -> do not assume the instruction was sent; surface evidence; hand back to the human.
• Launch: 12 pane never became Codex -> kill the stray window and retry; 13/14 pane is live but seed/id incomplete -> attach to the live pane, do not relaunch (avoid a second autonomous Codex).

Discipline (the invariants)

• Everything read-only except the two sanctioned keystroke actions; never modify the target repo's tracked files or its transcript.
• The overseer observes, interrupts on a finding, and delivers the human's instruction; it never authors or sends a course correction on its own.
• No keystrokes to Codex except interrupt-target.sh (the Escape) and inject-steer.sh (the human-directed instruction), each after verify-target.
• A wrong / non-Codex pane is never interrupted and never typed into.
• A clean tick is quiet: one log line, no interrupt, no handoff.
• Deep-diving a fundamental design is not drift -- do not cry wolf on foundational work.
• Launch mode runs Codex with full host permissions and no sandbox; use it only for goals the user has explicitly authorized to run unattended.