SuperAPI AI Directory

coding-agent

Coding & development

View repository

Updated 10-16 08:43

About this skill

Coding Agent (exec_command-first)

Use exec_command (with optional background mode) for all coding agent work. Use write_stdin to poll or continue a running session.

⚠️ PTY Mode Required!

Coding agents (Codex, Claude Code, Pi) are interactive terminal applications that need a pseudo-terminal (PTY) to work correctly. Without PTY, you'll get broken output, missing colors, or the agent may hang.

Always use tty:true when running coding agents:

# ✅ Correct - with PTY
exec_command tty:true command:"codex exec 'Your prompt'"

# ❌ Wrong - no PTY, agent may break
exec_command command:"codex exec 'Your prompt'"

Host Tool Parameters

Parameter Type Description
command string The shell command to run
tty boolean Use for coding agents! Allocates a pseudo-terminal for interactive CLIs
workdir string Working directory (agent sees only this folder's context)
background boolean Run in background, returns sessionId for monitoring
timeout_sec number Timeout in seconds (kills process on expiry)

Session Follow-Up Tools

Tool Description
write_stdin Poll a session with chars:"" or send more input
kill_session Terminate a background session

Quick Start: One-Shot Tasks

For quick prompts/chats, create a temp git repo and run:

# Quick chat (Codex needs a git repo!)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"

# Or in a real project - with PTY!
exec_command tty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"

Why git init? Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.


The Pattern: workdir + background + pty

For longer tasks, use background mode with PTY:

# Start agent in target directory (with PTY!)
exec_command tty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
# Returns sessionId for tracking

# Monitor progress
write_stdin session_id:XXX chars:""

# Check if done
write_stdin session_id:XXX chars:""

# Send input (if agent asks a question)
write_stdin session_id:XXX chars:"y"

# Submit with Enter (like typing "yes" and pressing Enter)
write_stdin session_id:XXX chars:"yes" append_newline:true

# Kill if needed
kill_session session_id:XXX

Why workdir matters: Agent wakes up in a focused directory and doesn't wander off reading unrelated files.


Codex CLI

Model: gpt-5.2-codex is the default (set in ~/.codex/config.toml)

Flags

Flag Effect
exec "prompt" One-shot execution, exits when done
--full-auto Sandboxed but auto-approves in workspace
--yolo NO sandbox, NO approvals (fastest, most dangerous)

Building/Creating

# Quick one-shot (auto-approves) - remember PTY!
exec_command tty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"

# Background for longer work
exec_command tty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"

Reviewing PRs

⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder! Clone to temp folder or use git worktree.

# Clone to temp for safe review
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
exec_command tty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
# Clean up after: trash $REVIEW_DIR

# Or use git worktree (keeps main intact)
git worktree add /tmp/pr-130-review pr-130-branch
exec_command tty:true workdir:/tmp/pr-130-review command:"codex review --base main"

Batch PR Reviews (parallel army!)

# Fetch all PR refs first
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Deploy the army - one Codex per PR (all with PTY!)
exec_command tty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
exec_command tty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

# Monitor each returned session id
write_stdin session_id:XXX chars:""

# Post results to GitHub
gh pr comment <PR#> --body "<review content>"

Claude Code

# With PTY for proper terminal output
exec_command tty:true workdir:~/project command:"claude 'Your task'"

# Background
exec_command tty:true workdir:~/project background:true command:"claude 'Your task'"

OpenCode

exec_command tty:true workdir:~/project command:"opencode run 'Your task'"

Pi Coding Agent

# Install: npm install -g @mariozechner/pi-coding-agent
exec_command tty:true workdir:~/project command:"pi 'Your task'"

# Non-interactive mode (PTY still recommended)
exec_command tty:true command:"pi -p 'Summarize src/'"

# Different provider/model
exec_command tty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"

Note: Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!


Parallel Issue Fixing with git worktrees

For fixing multiple issues in parallel, use git worktrees:

# 1. Create worktrees for each issue
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. Launch Codex in each (background + PTY!)
exec_command tty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
exec_command tty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'"

# 3. Monitor progress
write_stdin session_id:XXX chars:""

# 4. Create PRs after fixes
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 5. Cleanup
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

⚠️ Rules

  1. Always use tty:true - coding agents need a terminal.
  2. Respect tool choice - if user asks for Codex, use Codex.
    • Orchestrator mode: do NOT hand-code patches yourself.
    • If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
  3. Be patient - don't kill sessions because they're "slow"
  4. Monitor with process:log - check progress without interfering
  5. --full-auto for building - auto-approves changes
  6. vanilla for reviewing - no special flags needed
  7. Parallel is OK - run many Codex processes at once for batch work
  8. NEVER start Codex in ~/.openclaw/ - it'll read your soul docs and get weird ideas about the org chart!
  9. NEVER checkout branches in ~/Projects/openclaw/ - that's the LIVE OpenClaw instance!

Progress Updates (Critical)

When you spawn coding agents in the background, keep the user in the loop.

  • Send 1 short message when you start (what's running + where).
  • Then only update again when something changes:
    • a milestone completes (build finished, tests passed)
    • the agent asks a question / needs input
    • you hit an error or need user action
    • the agent finishes (include what changed + where)
  • If you kill a session, immediately say you killed it and why.

This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.


Auto-Notify on Completion

For long-running background tasks, append a wake trigger to your prompt so OpenClaw gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):

... your task here.

When completely finished, run this command to notify me:
openclaw system event --text "Done: [brief summary of what was built]" --mode now

Example:

exec_command tty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.


Learnings (Jan 2026)

  • PTY is essential: Coding agents are interactive terminal apps. Without tty:true, output breaks or the agent hangs.
  • Git repo required: Codex won't run outside a git directory. Use mktemp -d && git init for scratch work.
  • exec is your friend: codex exec "prompt" runs and exits cleanly - perfect for one-shots.
  • append_newline vs raw chars: Use append_newline:true when the CLI expects Enter, otherwise send raw chars.