# Codex Issue Runner

> Runs OpenAI Codex CLI agents in iTerm slots to work on GitHub issues. Use when asked to 'run codex on an issue', 'assign an issue to codex', 'spin up a codex agent', or 'have codex work on issue #N'.

- Skill: `aj47/codex-issue-runner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aj47/codex-issue-runner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aj47/codex-issue-runner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aj47 (https://skillmd.com/u/aj47)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aj47/codex-issue-runner

---


# Codex Issue Runner

## Overview
Automates spinning up OpenAI Codex CLI agents in SpeakMCP workspace slots to work on GitHub issues and PRs. Each slot is an independent workspace that can run one Codex agent at a time.

## Slot Architecture
- Slots are at `/Users/ajjoobandi/Development/SpeakMCP-Workspaces/slot-N` (N=1 to 5)
- Each slot is a git clone of the SpeakMCP repo
- Max 5 concurrent Codex agents

## Workflow

### Step 1: Identify Available Slots
Use `iterm:list_sessions` to see which slots are occupied. Look for session names containing `slot-N`.

### Step 2: Prepare the Slot
If the slot doesn't have an iTerm window, create one with `iterm:create_window`.
Navigate to the slot directory and reset to main:
```
cd ~/Development/SpeakMCP-Workspaces/slot-N
gitcm
```
The `gitcm` alias runs `git fetch && git checkout main && git pull`.

### Step 3: Launch Codex
Type `codex` and press ENTER in the terminal. Wait for the Codex UI to appear (look for the prompt box with model info).

### Step 4: Submit the Task
Write a clear task description referencing the issue number. Always instruct Codex to read the full issue first:
```
Work on issue #N - [brief description]. First read the issue by running `gh issue view N` to get full context, then implement the fix.
```
Press ENTER to submit.

### Step 5: Verify Submission
Wait 2-3 seconds, then read terminal output to confirm Codex is working (look for "Working" status).

## Task Formatting Tips
- Always tell Codex to read the issue/PR first with `gh issue view N` or `gh pr view N`
- Give a one-line summary so Codex has initial context
- For PRs, use `gh pr view N` and `gh pr diff N` to understand existing changes

## Monitoring
- Use `iterm:read_terminal_output` with the session ID to check progress
- Codex shows "Working (Ns)" while processing
- Press ESC to interrupt if needed

## After Codex Finishes
Codex will make changes locally. You may want to:
1. Review changes: `git diff`
2. Create a branch: `git checkout -b fix/issue-N-description`
3. Commit and push: `git add . && git commit -m "fix: description" && git push`
4. Create PR: `gh pr create --title "Fix #N: description" --body "Closes #N"`
Or run `www "description"` which automates the PR workflow.

## Common Issues
- If Codex fails to connect to GitHub, check internet connection
- If slot is dirty, run `git stash` or `git reset --hard` before `gitcm`
- If Codex hangs, press ESC and retry