---
name: codex-iterm
description: Run Codex CLI tasks inside iTerm so the user can watch progress. Use when Adolfo wants coding work done by Codex with a visible terminal session (e.g., "fire up Codex in iTerm", "let me see Codex work").
---

# Codex iTerm Runner

Use this skill whenever Adolfo wants Codex to handle coding tasks while he watches the live session in iTerm. The helper script pipes a Codex command into the foreground iTerm window so the GUI stays visible on his Mac.

## Quick Start

```bash
cd $WORKSPACE
python3 skills/codex-iterm/scripts/run_codex_iterm.py \
  --workdir /Users/adolforeyna/Project/basic1 \
  --flags "--full-auto" \
  "Run git pull --ff-only, then summarize last 3 commits."
```

What the helper does:
1. Builds a safe shell command: `cd <workdir> && codex <flags> '<prompt>'`
2. Calls `osascript` with `run_codex_iterm.applescript`
3. AppleScript activates iTerm (creates a window if needed) and types the command into the current session so Codex runs visibly.

## Workflow

1. **Prep the prompt**
   - Keep prompts explicit about the repo, steps, and deliverables, e.g.:
     - `"Sync with origin (git pull --ff-only) then describe any skill that can generate games from images."
2. **Run the helper**
   - `python3 skills/codex-iterm/scripts/run_codex_iterm.py --workdir <repo> --flags "--full-auto" "<prompt>"`
   - Flags can be swapped (`--yolo`, `--model gpt-5.3-codex`, etc.) by editing the `--flags` string.
3. **Monitor progress**
   - Adolfo watches the iTerm window; stay available in chat in case Codex asks for input.
4. **Capture results**
   - Once Codex finishes, summarize what happened (commands run, key outputs, follow-ups) in chat.
5. **Close the terminal**
   - When the run is complete and results are copied, close the active iTerm tab/window (⌘W or `osascript -e 'tell application "iTerm" to tell current session of current window to close'`) so Codex isn’t left running.

## Tips & Troubleshooting

- **Permission errors (`.git/FETCH_HEAD`)**: Report them to Adolfo before attempting fixes; he may prefer to adjust permissions locally.
- **Multiple commands**: Encode the entire plan in one prompt or run the helper multiple times.
- **Non-default repos**: Override `--workdir`. The default is `~/Project/basic1`.
- **Script locations**:
  - AppleScript: `skills/codex-iterm/scripts/run_codex_iterm.applescript`
  - Python helper: `skills/codex-iterm/scripts/run_codex_iterm.py`
- **Manual fallback**: If the helper ever fails, replicate it manually:
  ```bash
  /usr/bin/osascript <<'OSA'
  set cmd to "cd /path/to/repo && /Applications/Codex.app/Contents/Resources/codex --full-auto 'your prompt'"
  tell application "iTerm"
      activate
      if (count of windows) = 0 then create window with default profile
      tell current session of current window to write text cmd
  end tell
  OSA
  ```

Stay in sync with Adolfo after each run: confirm the command launched and summarize Codex’s output once it completes.