tomevault-io 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:
# ✅ 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:
# 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:
# 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 (like your soul.md 😅).
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!
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
⚠️ CRITICAL: Never review PRs in Clawdbot'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
bash pty: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
bash pty: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!)
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
# Post results to GitHub
gh pr comment <PR#> --body "<review content>"
Claude Code
# 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'"
OpenCode
bash pty:true workdir:~/project command:"opencode run 'Your task'"
Pi Coding Agent
# Install: npm install -g @mariozechner/pi-coding-agent
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)!
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!)
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. NEVER offer to build it yourself!
- 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 ~/clawd/ — it'll read your soul docs and get weird ideas about the org chart!
- NEVER checkout branches in ~/Projects/clawdbot/ — that's the LIVE Clawdbot instance!
Learnings (Jan 2026)
- 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 initfor scratch work. - exec is your friend:
codex exec "prompt"runs and exits cleanly - perfect for one-shots. - submit vs write: Use
submitto send input + Enter,writefor 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" 🦞
Converted and distributed by TomeVault — claim your Tome and manage your conversions.