coding-agent

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 (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 or 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). Requires OpenClaw host tools with exec_command plus write_stdin.

Quality

81%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

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:

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

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

# 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

# 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! Clone to temp folder or use git worktree.

# 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

# Or use git worktree (keeps main intact)
git worktree add /tmp/pr-130-review pr-130-branch
exec_command tty:true workdir:/tmp/pr-130-review command:"codex review --base main"

Batch PR Reviews (parallel army!)

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

# Deploy the army - one Codex per PR (all with PTY!)
exec_command tty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
exec_command tty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

# Monitor each returned session id
write_stdin session_id:XXX chars:""

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

Claude Code

# 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

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

Pi Coding Agent

# 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 git worktrees

For fixing multiple issues in parallel, use git worktrees:

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

# 2. Launch Codex in each (background + PTY!)
exec_command tty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
exec_command tty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'"

# 3. Monitor progress
write_stdin session_id:XXX chars:""

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

⚠️ Rules

Always use tty:true - coding agents need a terminal.
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.
Be patient - don't kill sessions because they're "slow"
Monitor with process:log - check progress without interfering
--full-auto for building - auto-approves changes
vanilla for reviewing - no special flags needed
Parallel is OK - run many Codex processes at once for batch work
NEVER start Codex in ~/.openclaw/ - it'll read your soul docs and get weird ideas about the org chart!
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:

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.

Repository: trpc-group/trpc-agent-go
Commit: 8763418

Last updated: about 1 hour ago
Created: about 1 hour ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.