coding-agent

name	coding-agent
description	Delegate coding tasks to Codex, Claude Code, or Pi agents via background host sessions. Use when: (1) building or creating new features or apps, (2) reviewing PRs or parallel coding with managed worktree isolation when subagents are available, (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat, or any work in ~/clawd workspace (never spawn agents here). Requires OpenClaw host tools with exec_command plus write_stdin.
metadata	{"openclaw":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}

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! When OpenClaw subagents are available, prefer managed worktree isolation:

{
  "task": "Review PR #130 against main. Inspect the diff, run focused checks, and report only actionable findings.",
  "isolation": "worktree",
  "timeout_seconds": 1800
}

Managed worktree isolation requires a runtime profile with workspace.workdir. If that is not available, use the manual clone flow below.

Use a manual clone only when launching an external CLI yourself.

# 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

Batch PR Reviews (parallel army!)

Use one managed subagent per PR:

{
  "task": "Review PR #86 against main. Inspect the diff, run focused checks, and report only actionable findings.",
  "isolation": "worktree",
  "timeout_seconds": 1800
}

Monitor with subagents_list / subagents_get / subagents_wait.

---

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 managed worktrees

For fixing multiple issues in parallel, prefer OpenClaw-managed worktree isolation so the runtime owns creation, cleanup, and result paths:

{
  "task": "Fix issue #78 from the approved ticket summary. Keep the scope tight, run focused tests, and report changed files plus verification.",
  "isolation": "worktree",
  "timeout_seconds": 3600
}

Spawn one subagent per independent issue, then use subagents_list / subagents_get / subagents_wait to monitor results. If a subagent leaves changes, OpenClaw preserves the worktree path and branch in the run result. If a subagent leaves no file or commit changes, OpenClaw removes the managed worktree automatically. Only fall back to manual git worktree commands when the task explicitly requires an external CLI outside OpenClaw-managed subagents.

---

⚠️ 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.