my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	---
#2	name: coding-agent
#3	description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
#4	metadata: {"clawdbot":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}
#5	---
#6
#7	# Coding Agent (bash-first)
#8
#9	Use bash (with optional background mode) for all coding agent work. Simple and effective.
#10
#11	## ⚠️ PTY Mode Required!
#12
#13	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.
#14
#15	Always use `pty:true` when running coding agents:
#16
#17	```bash
#18	# ✅ Correct - with PTY
#19	bash pty:true command:"codex exec 'Your prompt'"
#20
#21	# ❌ Wrong - no PTY, agent may break
#22	bash command:"codex exec 'Your prompt'"
#23	```
#24
#25	### Bash Tool Parameters
#26
#27	\| Parameter \| Type \| Description \|
#28	\|-----------\|------\|-------------\|
#29	\| `command` \| string \| The shell command to run \|
#30	\| `pty` \| boolean \| Use for coding agents! Allocates a pseudo-terminal for interactive CLIs \|
#31	\| `workdir` \| string \| Working directory (agent sees only this folder's context) \|
#32	\| `background` \| boolean \| Run in background, returns sessionId for monitoring \|
#33	\| `timeout` \| number \| Timeout in seconds (kills process on expiry) \|
#34	\| `elevated` \| boolean \| Run on host instead of sandbox (if allowed) \|
#35
#36	### Process Tool Actions (for background sessions)
#37
#38	\| Action \| Description \|
#39	\|--------\|-------------\|
#40	\| `list` \| List all running/recent sessions \|
#41	\| `poll` \| Check if session is still running \|
#42	\| `log` \| Get session output (with optional offset/limit) \|
#43	\| `write` \| Send raw data to stdin \|
#44	\| `submit` \| Send data + newline (like typing and pressing Enter) \|
#45	\| `send-keys` \| Send key tokens or hex bytes \|
#46	\| `paste` \| Paste text (with optional bracketed mode) \|
#47	\| `kill` \| Terminate the session \|
#48
#49	---
#50
#51	## Quick Start: One-Shot Tasks
#52
#53	For quick prompts/chats, create a temp git repo and run:
#54
#55	```bash
#56	# Quick chat (Codex needs a git repo!)
#57	SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"
#58
#59	# Or in a real project - with PTY!
#60	bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"
#61	```
#62
#63	Why git init? Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.
#64
#65	---
#66
#67	## The Pattern: workdir + background + pty
#68
#69	For longer tasks, use background mode with PTY:
#70
#71	```bash
#72	# Start agent in target directory (with PTY!)
#73	bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
#74	# Returns sessionId for tracking
#75
#76	# Monitor progress
#77	process action:log sessionId:XXX
#78
#79	# Check if done
#80	process action:poll sessionId:XXX
#81
#82	# Send input (if agent asks a question)
#83	process action:write sessionId:XXX data:"y"
#84
#85	# Submit with Enter (like typing "yes" and pressing Enter)
#86	process action:submit sessionId:XXX data:"yes"
#87
#88	# Kill if needed
#89	process action:kill sessionId:XXX
#90	```
#91
#92	Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
#93
#94	---
#95
#96	## Codex CLI
#97
#98	Model: `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
#99
#100	### Flags
#101
#102	\| Flag \| Effect \|
#103	\|------\|--------\|
#104	\| `exec "prompt"` \| One-shot execution, exits when done \|
#105	\| `--full-auto` \| Sandboxed but auto-approves in workspace \|
#106	\| `--yolo` \| NO sandbox, NO approvals (fastest, most dangerous) \|
#107
#108	### Building/Creating
#109	```bash
#110	# Quick one-shot (auto-approves) - remember PTY!
#111	bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"
#112
#113	# Background for longer work
#114	bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"
#115	```
#116
#117	### Reviewing PRs
#118
#119	⚠️ CRITICAL: Never review PRs in Clawdbot's own project folder!
#120	Clone to temp folder or use git worktree.
#121
#122	```bash
#123	# Clone to temp for safe review
#124	REVIEW_DIR=$(mktemp -d)
#125	git clone https://github.com/user/repo.git $REVIEW_DIR
#126	cd $REVIEW_DIR && gh pr checkout 130
#127	bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
#128	# Clean up after: trash $REVIEW_DIR
#129
#130	# Or use git worktree (keeps main intact)
#131	git worktree add /tmp/pr-130-review pr-130-branch
#132	bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"
#133	```
#134
#135	### Batch PR Reviews (parallel army!)
#136	```bash
#137	# Fetch all PR refs first
#138	git fetch origin '+refs/pull//head:refs/remotes/origin/pr/'
#139
#140	# Deploy the army - one Codex per PR (all with PTY!)
#141	bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
#142	bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"
#143
#144	# Monitor all
#145	process action:list
#146
#147	# Post results to GitHub
#148	gh pr comment <PR#> --body "<review content>"
#149	```
#150
#151	---
#152
#153	## Claude Code
#154
#155	```bash
#156	# With PTY for proper terminal output
#157	bash pty:true workdir:~/project command:"claude 'Your task'"
#158
#159	# Background
#160	bash pty:true workdir:~/project background:true command:"claude 'Your task'"
#161	```
#162
#163	---
#164
#165	## OpenCode
#166
#167	```bash
#168	bash pty:true workdir:~/project command:"opencode run 'Your task'"
#169	```
#170
#171	---
#172
#173	## Pi Coding Agent
#174
#175	```bash
#176	# Install: npm install -g @mariozechner/pi-coding-agent
#177	bash pty:true workdir:~/project command:"pi 'Your task'"
#178
#179	# Non-interactive mode (PTY still recommended)
#180	bash pty:true command:"pi -p 'Summarize src/'"
#181
#182	# Different provider/model
#183	bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"
#184	```
#185
#186	Note: Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!
#187
#188	---
#189
#190	## Parallel Issue Fixing with git worktrees
#191
#192	For fixing multiple issues in parallel, use git worktrees:
#193
#194	```bash
#195	# 1. Create worktrees for each issue
#196	git worktree add -b fix/issue-78 /tmp/issue-78 main
#197	git worktree add -b fix/issue-99 /tmp/issue-99 main
#198
#199	# 2. Launch Codex in each (background + PTY!)
#200	bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
#201	bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'"
#202
#203	# 3. Monitor progress
#204	process action:list
#205	process action:log sessionId:XXX
#206
#207	# 4. Create PRs after fixes
#208	cd /tmp/issue-78 && git push -u origin fix/issue-78
#209	gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
#210
#211	# 5. Cleanup
#212	git worktree remove /tmp/issue-78
#213	git worktree remove /tmp/issue-99
#214	```
#215
#216	---
#217
#218	## ⚠️ Rules
#219
#220	1. Always use pty:true - coding agents need a terminal!
#221	2. Respect tool choice - if user asks for Codex, use Codex.
#222	- Orchestrator mode: do NOT hand-code patches yourself.
#223	- If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
#224	3. Be patient - don't kill sessions because they're "slow"
#225	4. Monitor with process:log - check progress without interfering
#226	5. --full-auto for building - auto-approves changes
#227	6. vanilla for reviewing - no special flags needed
#228	7. Parallel is OK - run many Codex processes at once for batch work
#229	8. NEVER start Codex in ~/clawd/ - it'll read your soul docs and get weird ideas about the org chart!
#230	9. NEVER checkout branches in ~/Projects/clawdbot/ - that's the LIVE Clawdbot instance!
#231
#232	---
#233
#234	## Progress Updates (Critical)
#235
#236	When you spawn coding agents in the background, keep the user in the loop.
#237
#238	- Send 1 short message when you start (what's running + where).
#239	- Then only update again when something changes:
#240	- a milestone completes (build finished, tests passed)
#241	- the agent asks a question / needs input
#242	- you hit an error or need user action
#243	- the agent finishes (include what changed + where)
#244	- If you kill a session, immediately say you killed it and why.
#245
#246	This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.
#247
#248	---
#249
#250	## Auto-Notify on Completion
#251
#252	For long-running background tasks, append a wake trigger to your prompt so Clawdbot gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):
#253
#254	```
#255	... your task here.
#256
#257	When completely finished, run this command to notify me:
#258	clawdbot gateway wake --text "Done: [brief summary of what was built]" --mode now
#259	```
#260
#261	Example:
#262	```bash
#263	bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.
#264
#265	When completely finished, run: clawdbot gateway wake --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"
#266	```
#267
#268	This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.
#269
#270	---
#271
#272	## Learnings (Jan 2026)
#273
#274	- PTY is essential: Coding agents are interactive terminal apps. Without `pty:true`, output breaks or agent hangs.
#275	- Git repo required: Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work.
#276	- exec is your friend: `codex exec "prompt"` runs and exits cleanly - perfect for one-shots.
#277	- submit vs write: Use `submit` to send input + Enter, `write` for raw data without newline.
#278	- 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" 🦞
#279

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public