---

name: coding-agent description: 'Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (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 (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required.' metadata: { "openclaw": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } }, }

Coding Agent (bash-first)

Use bash (with optional background mode) for all coding agent work. Simple and effective.

⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no

For Codex, Pi, and OpenCode, PTY is still required (interactive terminal apps):

# ✅ Correct for Codex/Pi/OpenCode
bash pty:true command:"codex exec 'Your prompt'"

For Claude Code (claude CLI), use --print --permission-mode bypassPermissions instead. --dangerously-skip-permissions with PTY can exit after the confirmation dialog. --print mode keeps full tool access and avoids interactive confirmation:

# ✅ Correct for Claude Code (no PTY needed)
cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'

# For background execution: use background:true on the exec tool

# ❌ Wrong for Claude Code
bash pty:true command:"claude --dangerously-skip-permissions 'task'"

Bash Tool Parameters

Parameter	Type	Description
command	string	The shell command to run
pty	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	number	Timeout in seconds (kills process on expiry)
elevated	boolean	Run on host instead of sandbox (if allowed)

Process Tool Actions (for background sessions)

Action	Description
list	List all running/recent sessions
poll	Check if session is still running
log	Get session output (with optional offset/limit)
write	Send raw data to stdin
submit	Send data + newline (like typing and pressing Enter)
send-keys	Send key tokens or hex bytes
paste	Paste text (with optional bracketed mode)
kill	Terminate the 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!
bash pty: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!)
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
# Returns sessionId for tracking

# Monitor progress
process action:log sessionId:XXX

# Check if done
process action:poll sessionId:XXX

# Send input (if agent asks a question)
process action:write sessionId:XXX data:"y"

# Submit with Enter (like typing "yes" and pressing Enter)
process action:submit sessionId:XXX data:"yes"

# Kill if needed
process action:kill sessionId:XXX

Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

---

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 worksp