clawbot/skills/codex-iterm/SKILL.md

name, description

name	description
codex-iterm	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

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:

  /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.