Coding Agent

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:

# 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

Process Actions (background sessions)

Quick Start: One-Shot Tasks

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

# 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

Building / Creating

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

# 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

# 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

# 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

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.

# 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

# 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

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:

---
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 — Stored in references/. Kiro loads them only when the instructions direct it to.

Skills in Custom Agents

The default agent auto-discovers skills. Custom agents need explicit resource declarations:

{
  "name": "my-agent",
  "resources": [
    "skill://.kiro/skills/*/SKILL.md",
    "skill://~/.kiro/skills/*/SKILL.md"
  ]
}

Skill Best Practices

• Precise descriptions — "Review pull requests for security vulnerabilities and test coverage" activates reliably; "Helps with code review" does not.
• Keep SKILL.md actionable — Put lengthy reference material in references/ files.
• Right scope — Global skills for personal workflows; workspace skills for team/project conventions.
• Version control — Commit .kiro/skills/ so the team shares the same workflows.
• Check availability — Use /context show to see which skills are loaded in the current session.

Planning Mode (Plan Agent)

Plan Agent is a built-in read-only agent for structured planning before execution. It transforms ideas into detailed implementation plans through an interactive workflow.

When to Use

• Complex multi-step features (e.g., "build a user authentication system")
• Unclear or evolving requirements that need refinement
• Large features that benefit from task breakdown before coding

When NOT to Use

• Simple queries or single-step tasks
• User already has clear, specific instructions
• Quick fixes or small changes

How to Enter Planning Mode

# Slash command
> /plan

# With an immediate prompt
> /plan Build a REST API for user authentication

# Keyboard shortcut (toggles plan ↔ execution)
Shift + Tab

When active, the prompt shows a [plan] indicator.

Plan Workflow (4 phases)

1. Requirements gathering — Structured multiple-choice questions to refine your idea. Answer with 1=a, 2=b syntax or free-text.
2. Research & analysis — Explores your codebase using code intelligence, grep, and glob tools.
3. Implementation plan — Produces a task breakdown with clear objectives, implementation guidance, and demo descriptions for each task.
4. Approval & handoff — You review the plan. On approval (y), the plan transfers automatically to the execution agent.

Plan Agent is read-only: it can read files, search code, and research, but cannot write files or execute commands until handoff.

OpenClaw Integration for Planning Mode

For interactive planning sessions, run Kiro in background mode and relay the /plan command:

# Start interactive Kiro session
bash pty:true workdir:~/project background:true command:"kiro-cli chat --trust-all-tools"

# Enter planning mode
process action:submit sessionId:XXX data:"/plan Build a REST API for user authentication"

# Relay the user's answers to requirement questions
process action:submit sessionId:XXX data:"1=a, 2=d I'm using Rust with Axum"

# Approve the plan
process action:submit sessionId:XXX data:"y"

# Monitor output
process action:log sessionId:XXX

Example Planning Session

> /plan Add user authentication to my web app

[plan] > I understand you want to add user authentication.
[1]: What authentication method?
  a. Email/Password   b. OAuth   c. Magic Links   d. Multi-factor
> 1=a

[plan] > Great! Email/password it is.
[2]: What's your tech stack?
  a. React + Node.js   b. Next.js   c. Django/Flask   d. Other
> 2=d, I'm using Rust with Axum

[plan] > Researching Axum authentication patterns...

**Implementation Plan — User Authentication System**
[Detailed task breakdown...]

Does this plan look good? Ready to exit [plan] agent? [y/n]: y
[default] > Implement this plan: [Plan transferred]

Hooks

Hooks execute custom commands at specific points during agent lifecycle and tool execution. Defined in the agent configuration file.

Hook Types

Exit Codes

• 0 — Success. STDOUT captured (added to context for AgentSpawn/UserPromptSubmit).
• 2 — (PreToolUse only) Block tool execution; STDERR returned to the LLM.
• Other — Failure. STDERR shown as warning to user.

Tool Matching

Use the matcher field to target specific tools:

Configuration

• timeout_ms — Default 30,000ms (30s).
• cache_ttl_seconds — 0 = no caching (default); > 0 = cache successful results. AgentSpawn hooks are never cached.

See Agent Configuration Reference for full syntax.

Subagents

Kiro can delegate tasks to subagents — independent agents with their own context that run autonomously and return results.

> Use the backend agent to refactor the payment module

Key capabilities:

• Autonomous execution with isolated context
• Live progress tracking
• Parallel execution for multiple tasks
• Custom agent configurations for specialized workflows

Available tools in subagents: read, write, shell, code intelligence, MCP tools. Not available: web_search, web_fetch, use_aws, grep, glob, thinking, todo_list.

Custom Agents

Pre-define tool permissions, context resources, and behaviors:

kiro-cli agent list              # List available agents
kiro-cli agent create my-agent   # Create new agent
kiro-cli agent edit my-agent     # Edit agent config
kiro-cli agent validate ./a.json # Validate config file
kiro-cli agent set-default my-agent

Benefits: Pre-approved tool trust, limited tool access, auto-loaded project docs, shareable team configs.

Steering (Project Context)

Provide persistent project knowledge via markdown files:

Example structure:

.kiro/steering/
├── product.md           # Product overview
├── tech.md              # Tech stack
├── structure.md         # Project structure
└── api-standards.md     # API conventions

Also supports AGENTS.md in the project root or ~/.kiro/steering/.

In custom agents: Add "resources": ["file://.kiro/steering/**/*.md"] to config.

MCP Integration

Connect external tools and data sources via Model Context Protocol:

kiro-cli mcp add --name my-server --command "node server.js" --scope workspace
kiro-cli mcp list [workspace|global]
kiro-cli mcp status --name my-server
kiro-cli mcp remove --name my-server --scope workspace

OpenCode

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

Pi Coding Agent

# Install: npm install -g @mariozechner/pi-coding-agent

# Interactive
bash pty:true workdir:~/project command:"pi 'Your task'"

# Non-interactive (single response)
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'"

Parallel Issue Fixing (git worktrees)

Fix multiple issues simultaneously using isolated worktrees:

# 1. Create worktrees
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. Launch agents (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: <description>. Commit and push.'"

# 3. Monitor
process action:list
process action:log sessionId:XXX

# 4. Create PRs
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. Clean up
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

Rules

1. Always use pty:true — Coding agents need a pseudo-terminal.
2. Respect tool choice — If the user asks for Kiro, use Kiro; for Codex, use Codex. Do NOT hand-code patches yourself when orchestrating agents. If an agent fails or hangs, respawn it or ask the user — don't silently take over.
3. Be patient — Don't kill sessions just because they seem slow.
4. Monitor with process:log — Check progress without interfering.
5. Codex auto-approve flags — Use --full-auto (sandboxed) or --yolo (no sandbox) for building tasks.
6. Kiro tool trust — Use --trust-all-tools for automation; --trust-tools for restricted scope.
7. Kiro one-shots — Use --no-interactive for single-response queries.
8. Parallel is OK — Run multiple agent processes concurrently for batch work.
9. Never start agents in ~/clawd/ — Agents will read system docs and behave unpredictably.
10. Never checkout branches in ~/Projects/openclaw/ — That's the live OpenClaw instance.
11. Suggest Kiro /plan for complex tasks — When requirements are unclear or multi-step, suggest Plan Agent and let the user decide.
12. Leverage Kiro skills — If the project has .kiro/skills/ or the user has ~/.kiro/skills/, relevant skills activate automatically. No extra flags needed.

Progress Updates

When you spawn coding agents in the background, keep the user informed:

• On start — 1 short message: what's running, where, and which agent.
• On change — Update only when something happens:
  • A milestone completes (build finished, tests passed)
  • The agent asks a question or needs input
  • An error occurs or user action is needed
  • The agent finishes (include what changed and where)
• On kill — Immediately say you killed it and why.

Auto-Notify on Completion

For long-running tasks, append a wake trigger so OpenClaw is notified immediately when the agent finishes:

... your task here.

When completely finished, run this command to notify me:
openclaw gateway wake --text "Done: [brief summary]" --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 gateway wake --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

This triggers an immediate wake event instead of waiting for the next heartbeat.

Learnings

• PTY is essential — Without pty:true, output breaks or the agent hangs.
• Git repo required for Codex — Use mktemp -d && git init for scratch work.
• exec for one-shots — codex exec "prompt" runs and exits cleanly.
• submit vs write — submit sends input + Enter; write sends raw data without newline.
• Skills activate automatically — No slash command needed; Kiro matches your request against skill descriptions.
• Plan before complex builds — /plan saves time on multi-step features by clarifying requirements upfront.