Coding Agent

About this prompt

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)

Prompt body

# 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:

```bash
# ✅ 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:

```bash
# 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:

```bash
# 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

```bash
# 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:

```json
{
  "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.

```bash
# 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:

```json
{
  "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

```bash
# 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

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

---

## Pi Coding Agent

```bash
# 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:

```json
{
  "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:**

```bash
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`.

Variables

Best for

• •First-use as-is; the defaults work.
• •Fork if your audience or voice is significantly different from the author's.
• •Chain into a workflow when one prompt isn't enough — multi-step flows are the usual next move.