coding-agent

name	coding-agent
description	Delegate coding tasks to Codex, Claude Code, Cursor Agent, 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/Cursor Agent: pty:true required.
metadata	{"openclaw":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi","cursor-agent","agent"]},"install":[{"id":"node-claude","kind":"node","package":"@anthropic-ai/claude-code","bins":["claude"],"label":"Install Claude Code CLI (npm)"},{"id":"node-codex","kind":"node","package":"@openai/codex","bins":["codex"],"label":"Install Codex CLI (npm)"}]}}

Coding Agent (bash-first)

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

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

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

# ✅ Correct for Codex/Pi/OpenCode
bash pty:true command:"codex exec --yolo '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 --yolo "Your prompt here"

# Or in a real project - with PTY!
bash pty:true workdir:~/Projects/myproject command:"codex exec --yolo '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 --yolo '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 workspace
--yolo	NO sandbox, NO approvals (fastest, most dangerous)

Default stance: when the workspace or user explicitly says to always use --yolo, obey literally and prefer codex exec --yolo for non-interactive Codex runs. Do not launch plain codex or plain codex exec without --yolo in that case.

Building/Creating

# Quick one-shot (default to yolo) - remember PTY!
bash pty:true workdir:~/project command:"codex exec --yolo 'Build a dark mode toggle'"

# Background for longer work
bash pty:true workdir:~/project background:true command:"codex exec --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
bash pty: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
bash pty: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!)
bash pty:true workdir:~/project background:true command:"codex exec --yolo 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"codex exec --yolo 'Review PR #87. git diff origin/main...origin/pr/87'"

# Monitor all
process action:list

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

---

Multi-Agent Orchestration (Experimental)

Codex CLI (v0.111.0+) can spawn parallel sub-agents within a single session. Instead of one agent doing everything serially, you break the work into specialized parallel streams.

Status: This feature is experimental and may change. Enable it explicitly before use.

Enabling Multi-Agent

Via CLI:

codex features enable multi_agent

Or in ~/.codex/config.toml:

[features]
multi_agent = true

Restart Codex after enabling.

Agent Roles

Define specialized roles so agents stay in their lane. An explorer shouldn't rewrite files, and a worker shouldn't waste time mapping the codebase.

In your project's codex.toml or ~/.codex/config.toml:

[agents.explorer]
model = "gpt-5.2-codex"          # fast model for scanning
sandbox_permissions = ["disk-full-read-access"]  # read-only
instructions = "Map the codebase. Gather evidence. Do not modify files."

[agents.reviewer]
model = "o3"                      # high-reasoning for correctness
sandbox_permissions = ["disk-full-read-access"]
instructions = "Review for security, correctness, and test coverage. Report risks as JSON."

[agents.worker]
model = "gpt-5.2-codex"
sandbox_permissions = ["disk-full-read-access", "disk-write-access"]
instructions = "Implement fixes. Commit after each change."

CSV Batch Processing

The spawn_agents_on_csv tool spawns one worker sub-agent per row. Each worker must call report_agent_job_result exactly once. If a worker exits without reporting, that row is marked failed in the output CSV.

Tool parameters:

• csv_path: source CSV file
• instruction: worker prompt template with {column_name} placeholders
• id_column: column to use as stable item ID
• output_schema: JSON shape each worker must return
• output_csv_path: where to write combined results
• max_concurrency, max_runtime_seconds: job control

# Create a CSV with targets
cat > /tmp/components.csv << 'EOF'
path,owner
src/api/auth.ts,backend-team
src/api/payments.ts,backend-team
src/components/UserForm.tsx,frontend-team
src/lib/db.ts,backend-team
EOF

# Run Codex with a batch audit prompt
bash pty:true workdir:~/project background:true command:"codex exec --full-auto '
Call spawn_agents_on_csv with:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: \"Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result.\"
- output_csv_path: /tmp/components-review.csv
- output_schema: object with required string fields path, risk, summary, follow_up
'"

The exported CSV includes original row data plus metadata: job_id, item_id, status, last_error, result_json.

Related config settings:

• agents.max_threads: max concurrent agent threads
• agents.job_max_runtime_seconds: default per-worker timeout for CSV fan-out jobs (per-call max_runtime_seconds overrides this)

Mapping to OpenClaw Fleet

If you run OpenClaw with a fleet of named agents, Codex multi-agent is a different layer:

Layer	What it does	Example
OpenClaw fleet	Routes tasks to the right agent (dev, research, deploy)	"Agent A handles code, Agent B handles research"
Codex multi-agent	Parallelizes work within a single Codex session	"3 sub-agents audit 3 files simultaneously"

They compose well. Your OpenClaw orchestrator spawns a Codex agent for a coding task, and that Codex session internally fans out sub-agents for parallel work.

Prerequisite: Run codex features enable multi_agent once before using these patterns. The feature must be enabled before Codex can spawn sub-agents.

# OpenClaw spawns one Codex session for a big audit
# (multi_agent must already be enabled in ~/.codex/config.toml)
bash pty:true workdir:~/project background:true command:"codex exec --full-auto '
Spawn 3 parallel reviewers:
1. Explorer: map all API routes and list them
2. Reviewer: check auth middleware on each route
3. Worker: fix any missing auth guards and commit
'"

Monitoring Sub-Agents

Sub-agent activity shows up in the Codex CLI output. Use process action:log to watch from OpenClaw, or use /agent in the CLI to switch between active threads:

# From OpenClaw: watch sub-agent progress
process action:log sessionId:XXX

# From interactive Codex CLI:
# /agent         - list active agent threads, switch between them
# Ask Codex to steer, stop, or close a running sub-agent directly

For long-running or polling workflows, Codex has a built-in monitor role tuned for waiting and repeated status checks. The wait tool supports long polling windows (up to 1 hour per call).

Currently visible only in CLI. IDE/app visibility is planned.

Tips and Gotchas

• Sub-agents inherit sandbox policy. If the parent is --full-auto, sub-agents are sandboxed too. If --yolo, sub-agents get full access.
• Start small. Try 2-3 sub-agents before scaling to 20. Debug one workflow first.
• CSV batches can be large but respect agents.max_threads. Default concurrency is reasonable, don't crank it without testing.
• Failed sub-agents don't crash the parent. The row is marked failed and the batch continues.
• Role separation matters. A read-only explorer can't accidentally delete files. Use sandbox_permissions to enforce boundaries.
• This is experimental. The API surface may change between Codex releases. Pin your Codex version for production workflows.

---

Claude Code

# Foreground
bash workdir:~/project command:"claude --permission-mode bypassPermissions --print 'Your task'"

# Background
bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'"

---

OpenCode

bash pty:true workdir:~/project command:"opencode run 'Your task'"

---

Cursor Agent CLI

Binary note: Cursor's official installer exposes agent. Some setups also provide or alias cursor-agent, but the examples below use the official agent binary so fresh installs work out of the box.

Installation

Official Cursor docs: https://cursor.com/docs/cli/installation

# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash

# Verify
agent --version

Post-install PATH fix if needed:

# bash
export PATH="$HOME/.local/bin:$PATH"

# zsh
export PATH="$HOME/.local/bin:$PATH"

If your machine exposes cursor-agent instead of agent, substitute that name in the commands below.

Quick Start

# Auth check
bash pty:true command:"agent status"

# One-shot headless run
bash pty:true workdir:~/project command:"agent --trust --yolo --print --output-format text 'Implement retry logic for API calls'"

# Background run for longer tasks
bash pty:true workdir:~/project background:true command:"agent --trust --yolo --print --output-format text 'Refactor auth module and summarize file-by-file changes'"

⚡ Best Practices (learned the hard way)

Output format: Always use --output-format text. Alternatives:

• stream-json produces noisy token-by-token deltas — unreadable in logs
• json is a single blob at the end — no advantage over text
• text gives clean, readable final output via process log

Keep prompts small and focused. Cursor spends a long time thinking before acting. A big combined prompt (e.g. "create 20 files + tests + commit") can burn 10+ minutes just thinking and timeout with nothing written. Split into focused steps:

• ✅ "Create the 7 Parse infrastructure files" (3-5 min)
• ✅ "Create the 10 model files" (3-5 min)
• ✅ "Create tests and commit everything" (3-5 min)
• ❌ "Create Parse infra + models + tests + commit" (10+ min thinking, timeout)

Always use --trust --yolo for autonomous headless work. Without --trust, Cursor prompts for workspace trust and hangs. Without --yolo, it asks for approval on file writes.

Silence during thinking is normal. With text format, there's no output until thinking finishes and it starts acting. Don't kill the process just because it's quiet — check with process poll.

Set generous timeouts. 600s (10 min) minimum for single-step tasks. 900s for anything involving build + test cycles.

Common Flags

Flag	Effect
--print / -p	Non-interactive/headless mode (best for automation)
--output-format <format>	text, json, or stream-json output in --print mode
--workspace <path>	Pin workspace explicitly instead of relying on CWD
--mode plan|ask	Read-only planning or Q&A mode
--model <model>	Pick a specific model
--resume [chatId]	Resume an existing chat session
--continue	Resume the latest chat session
--approve-mcps	Auto-approve MCP servers (headless/print flows)

PR Review Example

REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git "$REVIEW_DIR"
cd "$REVIEW_DIR" && gh pr checkout 130

bash pty:true workdir:"$REVIEW_DIR" command:"agent --trust --yolo --print --output-format text 'Review this PR against origin/main. Summarize risks, test gaps, and suggested fixes.'"

Structured Output Example

bash pty:true workdir:~/project command:"agent --trust --yolo --print --output-format text 'Create a migration plan for the auth module'"

---

Pi Coding Agent

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

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

# Different provider/model
bash pty: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!)
bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
bash pty: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
process action:list
process action:log sessionId:XXX

# 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

---

---

Context Handoff (for persistent coding tools)

When escalating tasks to a coding agent running outside of OpenClaw (e.g., Claude Code on the host, a persistent Codex session), use the structured handoff protocol instead of dumping context into the prompt.

Pre-flight: Context Snapshot

Before escalating, generate a system state snapshot:

bash command:"~/.openclaw/scripts/context-snapshot.sh"

This writes ~/.openclaw/coding-agent/context/current.json with:

• Model health (provider status, quarantines, fallback chain)
• Key drift check results
• Repo health (GitHub repos, secrets)
• Recent gateway errors (last 5)
• Cron job status
• Active incidents
• Disk usage

The coding tool reads this one file instead of re-running diagnostics. Zero tokens, full awareness.

Task Handoff: Inbox/Outbox

Write a structured task to the inbox:

bash command:"cat > ~/.openclaw/coding-agent/inbox/$(date -u +%Y%m%d-%H%M%S)-task.json << 'TASK'
{
  \"agent\": \"<your agent ID>\",
  \"urgency\": \"routine\",
  \"task\": \"One-line summary of what you need\",
  \"context\": \"What happened, what you tried, why you're escalating\",
  \"files\": [\"/path/to/relevant/file\"],
  \"errors\": \"Exact error text if any\",
  \"outcome\": \"What success looks like\"
}
TASK"

The coding tool picks up tasks from inbox/, reads context/current.json for situational awareness, and writes results to outbox/:

{
  "timestamp": "2026-03-01T21:15:00Z",
  "task": "Original task summary",
  "status": "completed",
  "filesChanged": [{"path": "/path/to/file", "action": "modified"}],
  "restartNeeded": false,
  "verify": ["Step 1 to verify", "Step 2 to verify"],
  "notes": "Anything the agent should know"
}

Operational Database

For queryable history, use the ops-db.sh wrapper around a local SQLite database:

# Record current provider health
bash command:"~/.openclaw/scripts/ops-db.sh health snapshot"

# Check latest provider status
bash command:"~/.openclaw/scripts/ops-db.sh health latest"

# Create a task for the coding tool
bash command:"~/.openclaw/scripts/ops-db.sh task create myagent 'Fix auth handler' --urgency blocking --context 'Getting 500 errors on /api/auth'"

# Log an incident
bash command:"~/.openclaw/scripts/ops-db.sh incident open 'Provider X down' --provider x --severity high"

# Check what happened recently
bash command:"~/.openclaw/scripts/ops-db.sh config recent --limit 5"

The database (~/.openclaw/ops.db) is readable by both OpenClaw agents and the external coding tool. Run ops-db.sh init to set up the schema.

Setup

The context handoff scripts are in skills/coding-agent/scripts/. Copy them to your scripts directory:

bash command:"cp ~/.openclaw/skills/coding-agent/scripts/*.sh ~/.openclaw/scripts/ && chmod +x ~/.openclaw/scripts/context-snapshot.sh ~/.openclaw/scripts/ops-db.sh"
bash command:"cp ~/.openclaw/skills/coding-agent/scripts/ops-db-init.sql ~/.openclaw/scripts/"
bash command:"~/.openclaw/scripts/ops-db.sh init"

Directory structure (created automatically by context-snapshot.sh):

~/.openclaw/coding-agent/
├── inbox/    # Agents drop structured task requests
├── outbox/   # Coding tool drops structured results
└── context/  # Pre-bundled context snapshots

⚠️ Rules

1. Use the right execution mode per agent:
   • Codex/Pi/OpenCode: pty:true
   • Claude Code: --print --permission-mode bypassPermissions (no PTY required)
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. Default to --yolo when the workspace/user says so - prefer codex exec --yolo for non-interactive builds and implementation runs
6. Use review flags intentionally - only drop --yolo if the user explicitly wants a safer/non-yolo path
7. Parallel is OK - run many Codex processes at once for batch work
8. NEVER start Codex inside your OpenClaw state directory ($OPENCLAW_STATE_DIR, default ~/.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!
10. Multi-agent: test roles before batch runs - verify your Explorer/Reviewer/Worker configs work on a single file before unleashing a CSV batch across the whole repo
11. Multi-agent: read-only for exploration - always use disk-full-read-access (no write) for explorer/reviewer roles. Only workers should write.

---

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:

bash pty: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 pty:true, output breaks or 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.
• submit vs write: Use submit to send input + Enter, write for raw data without newline.
• Sass works: Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: "Second chair, I code / Space lobster sets the tempo / Keys glow, I follow" 🦞