coding-agent

# 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