Coding Agent (bash-first)
Use bash (with optional background mode) for all coding agent work. Simple and effective.
⚠️ 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 pty:true when running coding agents:
bash
# ✅ Correct - with PTY bash pty:true command:"codex exec 'Your prompt'" # ❌ Wrong - no PTY, agent may break bash command:"codex exec 'Your prompt'"
Bash Tool Parameters
| Parameter | Type | Description |
|---|---|---|
command | string | The shell command to run |
pty | 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 | number | Timeout in seconds (kills process on expiry) |
elevated | boolean | Run on host instead of sandbox (if allowed) |
Process Tool Actions (for background sessions)
| Action | Description |
|---|---|
list | List all running/recent sessions |
poll | Check if session is still running |
log | Get session output (with optional offset/limit) |
write | Send raw data to stdin |
submit | Send data + newline (like typing and pressing Enter) |
send-keys | Send key tokens or hex bytes |
paste | Paste text (with optional bracketed mode) |
kill | Terminate the 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! bash pty: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!) bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'" # Returns sessionId for tracking # Monitor progress process action:log sessionId:XXX # Check if done process action:poll sessionId:XXX # Send input (if agent asks a question) process action:write sessionId:XXX data:"y" # Submit with Enter (like typing "yes" and pressing Enter) process action:submit sessionId:XXX data:"yes" # Kill if needed process action:kill sessionId:XXX
Why workdir matters: Agent wakes up in a focused directory, 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! 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
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 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 (parallel)
bash
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*' 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'" process action:list gh pr comment <PR#> --body "<review content>"
Claude Code
bash
bash pty:true workdir:~/project command:"claude 'Your task'" bash pty:true workdir:~/project background:true command:"claude 'Your task'"
Parallel Issue Fixing with git worktrees
bash
# 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!) 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 progress process action:list process action:log sessionId:XXX # 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 pty:true - coding agents need a terminal!
- •Respect tool choice - if user asks for Codex, use Codex.
- •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
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).
- •Only update again when: a milestone completes, agent asks a question, you hit an error, or agent finishes.
- •If you kill a session, immediately say you killed it and why.
Auto-Notify on Completion
bash
bash pty: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\" --mode now'"