Run OpenCode, Codex CLI, Claude Code, or Gemini CLI via bash for programmatic coding agent control. Use when delegating coding tasks to an AI coding agent, building features, reviewing PRs, or running parallel development workflows.
Use coding agents (OpenCode, Codex, Claude Code, Gemini) via bash for delegated development work.
Use agents in this priority order:
| Priority | Agent | When to Use |
|---|---|---|
| 1 | OpenCode | Default for all coding tasks |
| 2 | Codex | OpenCode unavailable or usage limits |
| 3 | Claude Code | Codex unavailable or usage limits |
| 4 | Gemini | All above unavailable |
Signs to fall back:
Full docs (Load this only if you need to): https://opencode.ai/docs
For CLI usage, read references/opencode/cli.md.
For programmatic SDK control (Only read this if you need to write code that controls OpenCode programmatically), read references/opencode/sdk.md.
OpenCode remembers the last used model. To set a persistent default, add to opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"model": "github-copilot/claude-opus-4-5"
}
Model format: provider/model (e.g., github-copilot/claude-opus-4-5, openai/gpt-5.2-codex)
If the user doesn't specify a model, always use Opus (github-copilot/claude-opus-4-5).
Fallback model: Only if github-copilot is unavailable or rate-limited, use:
opencode run -m openai/gpt-5.2-codex --variant xhigh "Your prompt"
Variants (OpenAI/Other Provider reasoning models only, GitHub-Copilot doesn't support this): low, medium, high, xhigh — controls reasoning effort.
List available models:
opencode models # List all
opencode models github-copilot # Filter by provider
opencode models openai # Show OpenAI models
opencode models --verbose # Show variants & capabilities
opencode models --refresh # Refresh from models.dev
Override per-command:
opencode run -m github-copilot/claude-opus-4-5 "Your prompt"
opencode run -m openai/gpt-5.2-codex --variant xhigh "Your prompt"
# One-shot task (non-interactive, no PTY needed)
opencode run "Add error handling to src/api.ts"
# Continue last session
opencode run -c "Now add tests for that"
# Use specific model
opencode run -m anthropic/claude-sonnet-4-5 "Complex refactor"
# Plan mode (read-only, no modifications)
opencode run --agent plan "Review this architecture"
For long-running tasks, use serve + attach:
# Terminal 1: Start headless server
opencode serve --port 4096
# Terminal 2: Run commands against it (fast, no MCP cold boot)
opencode run --attach http://localhost:4096 "Build the feature"
Or with bash background mode (when PTY is needed):
bash pty:true workdir:~/project background:true command:"opencode"
process action:log sessionId:XXX
# List recent sessions
opencode session list -n 5
# Resume specific session
opencode run -s <sessionID> "Continue from here"
# Continue most recent
opencode run -c "Follow up"
For new projects without AGENTS.md:
cd /path/to/project
opencode
# Then run /init in the TUI
This generates an AGENTS.md file that helps the agent navigate the codebase. Commit it to Git.
OpenCode uses config-based permissions (not CLI flags like Codex's --yolo). Create opencode.json in project root:
Safe defaults (recommended):
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "allow",
"bash": {
"*": "allow",
"rm -rf *": "deny",
"rm -r *": "deny",
"git push *": "ask"
},
"external_directory": "deny",
"doom_loop": "ask"
}
}
Full auto (like Codex --full-auto):
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "allow",
"bash": "allow",
"external_directory": "deny"
}
}
YOLO mode (like Codex --yolo) — use with caution:
{
"$schema": "https://opencode.ai/config.json",
"permission": "allow"
}
Permission values:
"allow" — Run without approval"ask" — Prompt for approval"deny" — Block the actionKey settings:
external_directory: deny — Agent stays in project directorydoom_loop: ask — Catches repeated failing operationsWhen agent hits a permission wall, it should:
openclaw gateway wake --text "Need permission: <details>" --mode now
For multiline prompts, use heredoc syntax:
# No variable expansion (literal text)
opencode run <<'EOF'
Build a REST API for todos with the following requirements:
- CRUD endpoints for /todos
- SQLite database
EOF
# WITH variable expansion (when you need to pass variables)
opencode run <<EOF
Fix the bug described here: $BUG_DESCRIPTION
The relevant file is: $TARGET_FILE
EOF
Use <<'EOF' (single quotes) when you want literal text with no shell interpretation.
Use <<EOF (no quotes) when you need shell variables like $VAR to expand.
Some scenarios need a pseudo-terminal. Use pty:true when:
opencode run)# ✅ OpenCode run - no PTY needed
opencode run "Your prompt"
# ✅ OpenCode TUI - PTY recommended
bash pty:true workdir:~/project command:"opencode"
# ✅ Codex always needs PTY
bash pty:true workdir:~/project command:"codex exec 'Your prompt'"
Requires git repository. Codex won't run outside a trusted git directory.
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt"
| Flag | Effect |
|---|---|
exec "prompt" | One-shot execution, exits when done |
--full-auto | Sandboxed, auto-approves in workspace |
--yolo | NO sandbox, NO approvals (fastest, dangerous) |
# One-shot with PTY
bash pty:true workdir:~/project command:"codex exec 'Add dark mode toggle'"
# Full auto (auto-approves changes)
bash pty:true workdir:~/project command:"codex exec --full-auto 'Build REST API'"
# Background for longer work
bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor auth module'"
Detailed docs: See references/claude-code.md for Claude, references/gemini-cli.md for Gemini.
| Codex | Claude Equivalent |
|---|---|
codex exec "prompt" | claude -p "prompt" |
codex --full-auto | claude -p --permission-mode acceptEdits |
codex --yolo | claude -p --dangerously-skip-permissions |
# Non-interactive
claude -p "Add error handling to src/api.ts"
# Interactive with PTY
bash pty:true workdir:~/project command:"claude 'Your task'"
| Codex | Gemini Equivalent |
|---|---|
codex exec "prompt" | gemini "prompt" |
codex --full-auto | gemini --approval-mode auto_edit |
codex --yolo | gemini -y |
# Non-interactive
gemini "Add error handling to src/api.ts"
# Interactive with PTY
bash pty:true workdir:~/project command:"gemini -i 'Your task'"
For fixing multiple issues in parallel:
# Create worktrees
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main
# Launch agents in each
opencode run "Fix issue #78: <description>" &
# (from /tmp/issue-78)
opencode run "Fix issue #99: <description>" &
# (from /tmp/issue-99)
# Or with Codex (needs PTY)
bash pty:true workdir:/tmp/issue-78 background:true command:"codex --yolo 'Fix issue #78'"
bash pty:true workdir:/tmp/issue-99 background:true command:"codex --yolo 'Fix issue #99'"
# Monitor
process action:list
# Create PRs after
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --title "fix: issue #78" --body "..."
# Cleanup
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99
For advanced multi-agent control, use tmux skill instead of bash background.
| Use Case | Recommended |
|---|---|
| Quick one-shot | opencode run |
| Long-running with monitoring | bash background:true |
| Multiple parallel agents | tmux |
| Agent forking (context transfer) | tmux |
| Session persistence | tmux |
| Interactive debugging | tmux |
SOCKET="${TMPDIR:-/tmp}/coding-agents.sock"
# Create sessions
tmux -S "$SOCKET" new-session -d -s agent-1 -c /tmp/worktree-1
tmux -S "$SOCKET" new-session -d -s agent-2 -c /tmp/worktree-2
# Launch agents
tmux -S "$SOCKET" send-keys -t agent-1 "opencode run 'Fix issue #1'" Enter
tmux -S "$SOCKET" send-keys -t agent-2 "opencode run 'Fix issue #2'" Enter
# Monitor
tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -100
Transfer context from one agent to another:
CONTEXT=$(tmux -S "$SOCKET" capture-pane -p -t planner -S -500)
tmux -S "$SOCKET" new-session -d -s executor
tmux -S "$SOCKET" send-keys -t executor "opencode run <<EOF
Based on this plan: $CONTEXT
Execute step 1.
EOF" Enter
-i need PTYrun doesn't need PTY — It's already non-interactiveWhen spawning coding agents in background, you MUST provide progress updates to the USER:
For background tasks, append wake trigger to prompts so openclaw (YOU) is notified immediately when done:
opencode run <<'EOF'
Build a REST API for todos.
When completely finished, run:
openclaw gateway wake --text "Done: Built todos REST API with CRUD endpoints" --mode now
EOF
opencode run is non-interactive: No PTY required for simple tasks--session or --continue for multi-turn workexternal_directory: deny: Smart default keeps agent focused in projectserve + attach pattern: Avoids MCP cold boot for repeated runs