/coding-agent

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"] },
        "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 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 workspace | | `--yolo` | NO sandbox, NO approvals (fastest, most dangerous) |

Building/Creating

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

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

Reviewing PRs

**⚠️ CRITICAL: Never review PRs in OpenClaw's own project