Codex Orchestrator

Monitor, control, and orchestrate background Codex sessions. Use this skill to track progress, handle interruptions, and ensure task completion for long-running coding tasks.

Security Scan

The instructions are coherent with an orchestrator for background Codex sessions, but the skill assumes high-privilege process-control tooling (a 'codex' CLI, PTY and process-action APIs) without declaring those dependencies or the required runtime permissions.

Purpose & Capability

The name/description match the SKILL.md: it is explicitly about launching, monitoring, and controlling background Codex sessions. However, the SKILL.md requires a 'codex' CLI and an agent-level 'process action' tool (PTY/background session support, process action:list/log/submit/kill) but the registry metadata declares no required binaries or tools. That mismatch (undeclared but necessary tools and host process control) is a notable omission.

Instruction Scope

The runtime instructions direct the agent to start background PTY sessions, read process logs, submit keystrokes, kill and resume sessions, and run 'codex exec' with arbitrary commands. While this aligns with orchestration, it also grants the agent the ability to execute arbitrary commands and control local processes — a powerful capability that can access files, network, or other system state. The SKILL.md does not limit or constrain what commands are run, nor does it require explicit user confirmation flows.

Install Mechanism

No install spec and no code files (instruction-only). That minimizes supply-chain risk because nothing is downloaded or written by the skill itself.

Credentials

The skill declares no environment variables or credentials, which is proportionate. However, it implicitly requires runtime capabilities (the 'codex' CLI and process-control tools) that are not declared; this is an omission rather than an overreach in requested credentials.

Persistence & Privilege

always:false (default) so it is not force-included. The skill assumes autonomous ability to start and manage background processes; combined with the process-control instructions, that increases the potential blast radius if the agent is allowed to invoke the skill autonomously. This is normal platform behavior but worth noting.

What to consider before installing

This skill looks like a legitimate orchestrator for background Codex sessions, but it assumes the agent has a 'codex' CLI and process-management tools (PTY support and process action APIs) even though those are not declared. Before installing or enabling: 1) confirm whether your agent/runtime actually exposes a 'codex' CLI and the process action/PTY primitives and understand what privileges those provide (file access, network, ability to run arbitrary shell commands); 2) only grant this skill to agents running in a sandboxed environment or a user-approved context; 3) require explicit user confirmation before the agent launches or resumes background sessions that run arbitrary commands; 4) test on non-sensitive projects first; and 5) if you need stricter controls, ask the skill author to declare required binaries and to add explicit constraints (allowed commands, whitelisted workdirs, or user-interaction gates).

This skill provides a workflow for supervising the Codex coding agent running in background processes.

Workflow

1. Start (Launch)

Always launch Codex in a background PTY session to maintain interactivity without blocking the main agent.

bash pty:true workdir:<target_dir> background:true command:"codex exec --full-auto '<PROMPT>'"

• Store the returned sessionId.
• If sessionId is lost, find it via process action:list.

2. Monitor (Watch)

Check progress regularly (e.g., via cron or manual check).

# Get last 2KB of logs to see current status
process action:log sessionId:<id> limit:2000

Signs of life:

• Spinner animations or progress bars updating.
• "Working...", "Thinking...", "Running...".
• File edits (Edit ...).

Signs of blockage:

• Interactive prompts (e.g., "Select directory", "Approve change [y/n]").
• No log output for >5 minutes (process might be hung or waiting for hidden input).

3. Intervene (Control)

If Codex is stuck at a prompt:

# Send 'y' and Enter
process action:submit sessionId:<id> data:"y"

# Send just Enter (default choice)
process action:submit sessionId:<id> data:""

If Codex is looping or hallucinating:

# Kill the session
process action:kill sessionId:<id>

4. Report (Notify)

When a significant milestone is reached or the task is done:

1. Summarize the work done (files changed, tests passed).
2. Notify the user.

Standard Operating Procedures (SOPs)

"The Stuck Agent" Protocol

1. Diagnose: Run process action:log sessionId:<id> limit:500.
2. Analyze: Is it asking a question? Is it downloading?
3. Action:
   • If asking: Provide answer via submit.
   • If downloading (slow): Wait.
   • If silent >10m: Send a "poke" (e.g. submit data:"\n" to refresh prompt) or kill/resume.

"The Resume" Protocol

If a session died or was killed:

1. Run codex resume --last or codex resume <session_id> in a new background process.
2. Verify it picked up the context.

Logs & Artifacts

• Codex logs are ephemeral in the PTY buffer.
• For persistent logs, instruct Codex to write to a file: codex exec "task..." > codex.log 2>&1 (Note: buffering may delay output).
• Better: Use process action:log to snapshot the buffer periodically.