coding-agent

Run Codex CLI, Claude Code, Kiro CLI, OpenCode, or Pi Coding Agent via background process for programmatic control.

# Coding Agent

Launch and manage AI coding agents (Codex, Claude Code, Kiro CLI, OpenCode, Pi) from OpenClaw using bash with background process control.

## PTY Mode Required

Coding agents are **interactive terminal applications** that need a pseudo-terminal (PTY). Without it, output breaks or the agent hangs.

**Always set `pty:true`:**

```bash
# Correct — with PTY
bash pty:true command:"codex exec 'Your prompt'"

# Wrong — agent may break or hang
bash command:"codex exec 'Your prompt'"
```

## Tool Reference

### Bash Parameters

| Parameter    | Type    | Description                                                 |
| ------------ | ------- | ----------------------------------------------------------- |
| `command`    | string  | Shell command to run                                        |
| `pty`        | boolean | Allocate a pseudo-terminal (**required for coding agents**) |
| `workdir`    | string  | Working directory (agent sees only this folder)             |
| `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 Actions (background sessions)

| Action      | Description                                          |
| ----------- | ---------------------------------------------------- |
| `list`      | List all running/recent sessions                     |
| `poll`      | Check if a session is still running                  |
| `log`       | Get session output (optional offset/limit)           |
| `write`     | Send raw data to stdin (no newline)                  |
| `submit`    | Send data + newline (like typing and pressing Enter) |
| `send-keys` | Send key tokens or hex bytes                         |
| `paste`     | Paste text (optional bracketed mode)                 |
| `kill`      | Terminate the session                                |

---

## Quick Start: One-Shot Tasks

```bash
# Codex needs a git repo — create a temp one for scratch work
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt"

# Run inside an existing project (with PTY)
bash pty:true workdir:~/project command:"codex exec 'Add error handling to the API calls'"
```

---

## Core Pattern: workdir + background + pty

For longer tasks, combine all three:

```bash
# 1. Start the agent
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
# → returns sessionId

# 2. Monitor progress
process action:log sessionId:XXX

# 3. Check completion
process action:poll sessionId:XXX

# 4. Send input if the agent asks a question
process action:submit sessionId:XXX data:"yes"     # text + Enter
process action:write sessionId:XXX data:"y"         # raw keystroke

# 5. Kill if stuck
process action:kill sessionId:XXX
```

**Why `workdir`?** The agent starts in a focused directory and won't wander into unrelated files.

---

## Codex CLI

**Default model:** `gpt-5.2-codex` (set in `~/.codex/config.toml`)

### Flags

| Flag            | Effect                                             |
| --------------- | -------------------------------------------------- |
| `exec "prompt"` | One-shot execution, exits when done                |
| `--full-auto`   | Sandboxed, auto-approves within workspace          |
| `--yolo`        | No sandbox, no approvals (fastest, most dangerous) |

### Building / Creating

```bash
# One-shot with auto-approve
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

**Never review PRs in OpenClaw's own project folder.** Clone to a temp directory or use a git worktree.

```bash
# Clone to temp
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"

# 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

```bash
# Fetch all PR refs
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Launch one Codex per PR (all background + PTY)
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

# Monitor
process action:list

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

---

## Claude Code

```bash
# One-shot
bash pty:true workdir:~/project command:"claude 'Your task'"

# Background
bash pty:true workdir:~/project background:true command:"claude 'Your task'"
```

---

## Kiro CLI (AWS)

AWS AI coding assistant with session persistence, custom agents, skills, hooks, steering, subagents, planning mode, and MCP integration.

**Install:** https://kiro.dev/docs/cli/installation

### Basic Usage

```bash
kiro-cli                           # Interactive chat (default)
kiro-cli chat "Your question"      # Direct question
kiro-cli --agent my-agent          # Use a specific agent
kiro-cli chat --resume             # Resume last session (per-directory)
kiro-cli chat --resume-picker      # Pick from saved sessions
kiro-cli chat --list-sessions      # List all sessions
```

### Non-Interactive Mode

For scripting and automation — outputs a single response to STDOUT, then exits.

```bash
# Single response
kiro-cli chat --no-interactive "Show current directory"

# Trust all tools (no confirmation prompts)
kiro-cli chat --no-interactive --trust-all-tools "Create hello.py"

# Trust specific tools only
kiro-cli chat --no-interactive --trust-tools "fs_read,fs_write" "Read package.json"
```

**Tool trust:** `--trust-all-tools` for full automation. For untrusted input, use `--trust-tools "fs_read,fs_write,shell"` to limit scope.

### OpenClaw Integration

```bash
# Interactive session (background)
bash pty:true workdir:~/project background:true command:"kiro-cli"

# One-shot query (non-interactive)
bash pty:true workdir:~/project command:"kiro-cli chat --no-interactive --trust-all-tools 'List all TODO comments in src/'"

# With a specific agent
bash pty:true workdir:~/project background:true command:"kiro-cli --agent aws-expert 'Set up Lambda'"

# Resume previous session
bash pty:true workdir:~/project command:"kiro-cli chat --resume"
```

### Skills (Agent Skills)

Skills are **portable instruction packages** that extend what Kiro knows. When a request matches a skill's description, Kiro automatically loads and follows its instructions — no slash command needed.

#### Skill Locations

| Location | Scope | Notes |
| --- | --- | --- |
| `.kiro/skills/<name>/` | Workspace (project) | Shared via version control |
| `~/.kiro/skills/<name>/` | Global (all projects) | Personal workflows |

Workspace skills take priority when names collide.

#### Creating a Skill

A skill is a folder with a `SKILL.md` file:

```
my-skill/
├── SKILL.md          # Required — frontmatter + instructions
└── references/       # Optional — detailed docs loaded on demand
    └── guide.md
```

**SKILL.md format:**

````markdown
---
name: pr-review
description: Review pull requests for code quality, security issues, and test coverage.
---

## Review checklist

1. Check for vulnerabilities, injection risks, exposed secrets
2. Verify edge cases and failure modes are handled
3. Confirm new code has appropriate tests

For detailed patterns, see `references/guide.md`.
````

- **`name`** — Unique identifier for the skill.
- **`description`** — Determines when Kiro activates the skill. Be specific; include keywords that match how you'd phrase requests.
- **Reference files**