docs: update coding-agent skill guidance
This commit is contained in:
Peter Steinberger
@@ -4,20 +4,73 @@ description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via backgr
|
||||
metadata: {"clawdbot":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}
|
||||
---
|
||||
|
||||
# Coding Agent (background-first)
|
||||
# Coding Agent (bash-first)
|
||||
|
||||
Use **bash background mode** for non-interactive coding work. For interactive coding sessions, use the **tmux** skill (always, except very simple one-shot prompts).
|
||||
Use **bash** (with optional background mode) for all coding agent work. Simple and effective.
|
||||
|
||||
## The Pattern: workdir + background
|
||||
## ⚠️ 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
|
||||
# Create temp space for chats/scratch work
|
||||
SCRATCH=$(mktemp -d)
|
||||
# ✅ Correct - with PTY
|
||||
bash pty:true command:"codex exec 'Your prompt'"
|
||||
|
||||
# Start agent in target directory ("little box" - only sees relevant files)
|
||||
bash workdir:$SCRATCH background:true command:"<agent command>"
|
||||
# Or for project work:
|
||||
bash workdir:~/project/folder background:true command:"<agent command>"
|
||||
# ❌ 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
|
||||
@@ -29,6 +82,9 @@ 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
|
||||
```
|
||||
@@ -41,72 +97,67 @@ process action:kill sessionId:XXX
|
||||
|
||||
**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
|
||||
|
||||
### Building/Creating (use --full-auto or --yolo)
|
||||
### 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
|
||||
# --full-auto: sandboxed but auto-approves in workspace
|
||||
bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""
|
||||
# Quick one-shot (auto-approves) - remember PTY!
|
||||
bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"
|
||||
|
||||
# --yolo: NO sandbox, NO approvals (fastest, most dangerous)
|
||||
bash workdir:~/project background:true command:"codex --yolo \"Build a snake game with dark theme\""
|
||||
|
||||
# Note: --yolo is a shortcut for --dangerously-bypass-approvals-and-sandbox
|
||||
# Background for longer work
|
||||
bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"
|
||||
```
|
||||
|
||||
### Reviewing PRs (vanilla, no flags)
|
||||
### Reviewing PRs
|
||||
|
||||
**⚠️ CRITICAL: Never review PRs in Clawdbot's own project folder!**
|
||||
- Either use the project where the PR is submitted (if it's NOT ~/Projects/clawdbot)
|
||||
- Or clone to a temp folder first
|
||||
Clone to temp folder or use git worktree.
|
||||
|
||||
```bash
|
||||
# Option 1: Review in the actual project (if NOT clawdbot)
|
||||
bash workdir:~/Projects/some-other-repo background:true command:"codex review --base main"
|
||||
|
||||
# Option 2: Clone to temp folder for safe review (REQUIRED for clawdbot PRs!)
|
||||
# Clone to temp for safe review
|
||||
REVIEW_DIR=$(mktemp -d)
|
||||
git clone https://github.com/clawdbot/clawdbot.git $REVIEW_DIR
|
||||
git clone https://github.com/user/repo.git $REVIEW_DIR
|
||||
cd $REVIEW_DIR && gh pr checkout 130
|
||||
bash workdir:$REVIEW_DIR background:true command:"codex review --base origin/main"
|
||||
# Clean up after: rm -rf $REVIEW_DIR
|
||||
bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
|
||||
# Clean up after: trash $REVIEW_DIR
|
||||
|
||||
# Option 3: Use git worktree (keeps main intact)
|
||||
# Or use git worktree (keeps main intact)
|
||||
git worktree add /tmp/pr-130-review pr-130-branch
|
||||
bash workdir:/tmp/pr-130-review background:true command:"codex review --base main"
|
||||
bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"
|
||||
```
|
||||
|
||||
**Why?** Checking out branches in the running Clawdbot repo can break the live instance!
|
||||
|
||||
### Batch PR Reviews (parallel army!)
|
||||
```bash
|
||||
# Fetch all PR refs first
|
||||
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
|
||||
|
||||
# Deploy the army - one Codex per PR!
|
||||
bash workdir:~/project background:true command:"codex exec \"Review PR #86. git diff origin/main...origin/pr/86\""
|
||||
bash workdir:~/project background:true command:"codex exec \"Review PR #87. git diff origin/main...origin/pr/87\""
|
||||
bash workdir:~/project background:true command:"codex exec \"Review PR #95. git diff origin/main...origin/pr/95\""
|
||||
# ... repeat for all PRs
|
||||
# Deploy the army - one Codex per PR (all with 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 all
|
||||
process action:list
|
||||
|
||||
# Get results and post to GitHub
|
||||
process action:log sessionId:XXX
|
||||
# Post results to GitHub
|
||||
gh pr comment <PR#> --body "<review content>"
|
||||
```
|
||||
|
||||
### Tips for PR Reviews
|
||||
- **Fetch refs first:** `git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'`
|
||||
- **Use git diff:** Tell Codex to use `git diff origin/main...origin/pr/XX`
|
||||
- **Don't checkout:** Multiple parallel reviews = don't let them change branches
|
||||
- **Post results:** Use `gh pr comment` to post reviews to GitHub
|
||||
|
||||
---
|
||||
|
||||
## Claude Code
|
||||
|
||||
```bash
|
||||
bash workdir:~/project background:true command:"claude \"Your task\""
|
||||
# With PTY for proper terminal output
|
||||
bash pty:true workdir:~/project command:"claude 'Your task'"
|
||||
|
||||
# Background
|
||||
bash pty:true workdir:~/project background:true command:"claude 'Your task'"
|
||||
```
|
||||
|
||||
---
|
||||
@@ -114,7 +165,7 @@ bash workdir:~/project background:true command:"claude \"Your task\""
|
||||
## OpenCode
|
||||
|
||||
```bash
|
||||
bash workdir:~/project background:true command:"opencode run \"Your task\""
|
||||
bash pty:true workdir:~/project command:"opencode run 'Your task'"
|
||||
```
|
||||
|
||||
---
|
||||
@@ -123,152 +174,65 @@ bash workdir:~/project background:true command:"opencode run \"Your task\""
|
||||
|
||||
```bash
|
||||
# Install: npm install -g @mariozechner/pi-coding-agent
|
||||
bash workdir:~/project background:true command:"pi \"Your task\""
|
||||
bash pty:true workdir:~/project command:"pi 'Your task'"
|
||||
|
||||
# Non-interactive mode (PTY still recommended)
|
||||
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'"
|
||||
```
|
||||
|
||||
**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!
|
||||
|
||||
---
|
||||
|
||||
## Pi flags (common)
|
||||
## Parallel Issue Fixing with git worktrees
|
||||
|
||||
- `--print` / `-p`: non-interactive; runs prompt and exits.
|
||||
- `--provider <name>`: pick provider (default: google).
|
||||
- `--model <id>`: pick model (default: gemini-2.5-flash).
|
||||
- `--api-key <key>`: override API key (defaults to env vars).
|
||||
|
||||
Examples:
|
||||
For fixing multiple issues in parallel, use git worktrees:
|
||||
|
||||
```bash
|
||||
# Set provider + model, non-interactive
|
||||
bash workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p \"Summarize src/\""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## tmux (interactive sessions)
|
||||
|
||||
Use the tmux skill for interactive coding sessions (always, except very simple one-shot prompts). Prefer bash background mode for non-interactive runs.
|
||||
|
||||
---
|
||||
|
||||
## Parallel Issue Fixing with git worktrees + tmux
|
||||
|
||||
For fixing multiple issues in parallel, use git worktrees (isolated branches) + tmux sessions:
|
||||
|
||||
```bash
|
||||
# 1. Clone repo to temp location
|
||||
cd /tmp && git clone git@github.com:user/repo.git repo-worktrees
|
||||
cd repo-worktrees
|
||||
|
||||
# 2. Create worktrees for each issue (isolated branches!)
|
||||
# 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
|
||||
|
||||
# 3. Set up tmux sessions
|
||||
SOCKET="${TMPDIR:-/tmp}/codex-fixes.sock"
|
||||
tmux -S "$SOCKET" new-session -d -s fix-78
|
||||
tmux -S "$SOCKET" new-session -d -s fix-99
|
||||
# 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.'"
|
||||
|
||||
# 4. Launch Codex in each (after pnpm install!)
|
||||
tmux -S "$SOCKET" send-keys -t fix-78 "cd /tmp/issue-78 && pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'" Enter
|
||||
tmux -S "$SOCKET" send-keys -t fix-99 "cd /tmp/issue-99 && pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'" Enter
|
||||
# 3. Monitor progress
|
||||
process action:list
|
||||
process action:log sessionId:XXX
|
||||
|
||||
# 5. Monitor progress
|
||||
tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -30
|
||||
tmux -S "$SOCKET" capture-pane -p -t fix-99 -S -30
|
||||
|
||||
# 6. Check if done (prompt returned)
|
||||
tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -3 | grep -q "❯" && echo "Done!"
|
||||
|
||||
# 7. Create PRs after fixes
|
||||
# 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 "..."
|
||||
|
||||
# 8. Cleanup
|
||||
tmux -S "$SOCKET" kill-server
|
||||
# 5. Cleanup
|
||||
git worktree remove /tmp/issue-78
|
||||
git worktree remove /tmp/issue-99
|
||||
```
|
||||
|
||||
**Why worktrees?** Each Codex works in isolated branch, no conflicts. Can run 5+ parallel fixes!
|
||||
|
||||
**Why tmux over bash background?** Codex is interactive — needs TTY for proper output. tmux provides persistent sessions with full history capture.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Rules
|
||||
|
||||
1. **Respect tool choice** — if user asks for Codex, use Codex. NEVER offer to build it yourself!
|
||||
2. **Be patient** — don't kill sessions because they're "slow"
|
||||
3. **Monitor with process:log** — check progress without interfering
|
||||
4. **--full-auto for building** — auto-approves changes
|
||||
5. **vanilla for reviewing** — no special flags needed
|
||||
6. **Parallel is OK** — run many Codex processes at once for batch work
|
||||
7. **NEVER start Codex in ~/clawd/** — it'll read your soul docs and get weird ideas about the org chart! Use the target project dir or /tmp for blank slate chats
|
||||
8. **NEVER checkout branches in ~/Projects/clawdbot/** — that's the LIVE Clawdbot instance! Clone to /tmp or use git worktree for PR reviews
|
||||
1. **Always use pty:true** — coding agents need a terminal!
|
||||
2. **Respect tool choice** — if user asks for Codex, use Codex. NEVER offer to build it yourself!
|
||||
3. **Be patient** — don't kill sessions because they're "slow"
|
||||
4. **Monitor with process:log** — check progress without interfering
|
||||
5. **--full-auto for building** — auto-approves changes
|
||||
6. **vanilla for reviewing** — no special flags needed
|
||||
7. **Parallel is OK** — run many Codex processes at once for batch work
|
||||
8. **NEVER start Codex in ~/clawd/** — it'll read your soul docs and get weird ideas about the org chart!
|
||||
9. **NEVER checkout branches in ~/Projects/clawdbot/** — that's the LIVE Clawdbot instance!
|
||||
|
||||
---
|
||||
|
||||
## PR Template (The Razor Standard)
|
||||
## Learnings (Jan 2026)
|
||||
|
||||
When submitting PRs to external repos, use this format for quality & maintainer-friendliness:
|
||||
|
||||
````markdown
|
||||
## Original Prompt
|
||||
[Exact request/problem statement]
|
||||
|
||||
## What this does
|
||||
[High-level description]
|
||||
|
||||
**Features:**
|
||||
- [Key feature 1]
|
||||
- [Key feature 2]
|
||||
|
||||
**Example usage:**
|
||||
```bash
|
||||
# Example
|
||||
command example
|
||||
```
|
||||
|
||||
## Feature intent (maintainer-friendly)
|
||||
[Why useful, how it fits, workflows it enables]
|
||||
|
||||
## Prompt history (timestamped)
|
||||
- YYYY-MM-DD HH:MM UTC: [Step 1]
|
||||
- YYYY-MM-DD HH:MM UTC: [Step 2]
|
||||
|
||||
## How I tested
|
||||
**Manual verification:**
|
||||
1. [Test step] - Output: `[result]`
|
||||
2. [Test step] - Result: [result]
|
||||
|
||||
**Files tested:**
|
||||
- [Detail]
|
||||
- [Edge cases]
|
||||
|
||||
## Session logs (implementation)
|
||||
- [What was researched]
|
||||
- [What was discovered]
|
||||
- [Time spent]
|
||||
|
||||
## Implementation details
|
||||
**New files:**
|
||||
- `path/file.ts` - [description]
|
||||
|
||||
**Modified files:**
|
||||
- `path/file.ts` - [change]
|
||||
|
||||
**Technical notes:**
|
||||
- [Detail 1]
|
||||
- [Detail 2]
|
||||
|
||||
---
|
||||
*Submitted by Razor 🥷 - Mariano's AI agent*
|
||||
````
|
||||
|
||||
**Key principles:**
|
||||
1. Human-written description (no AI slop)
|
||||
2. Feature intent for maintainers
|
||||
3. Timestamped prompt history
|
||||
4. Session logs if using Codex/agent
|
||||
|
||||
**Example:** https://github.com/steipete/bird/pull/22
|
||||
- **PTY is essential:** Coding agents are interactive terminal apps. Without `pty:true`, output breaks or 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.
|
||||
- **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline.
|
||||
- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: *"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"* 🦞
|
||||
|
||||
Reference in New Issue
Block a user