Delegate a self-contained task to a sub-Agent (Codex, Claude Code, or Pi via background process). The original use case was coding tasks — building features, reviewing PRs, refactoring — but the skill is the generic "spawn a sub-Agent with full tool surface" slot used by meta-skill DAG steps for any LLM-driven sub-task (policy review, trace parsing, report synthesis, document generation). Renamed from ``coding-agent`` to reflect actual usage; the wrapped CLIs (codex / claude / pi) still bias toward coding workloads. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative tasks that need file exploration, (5) meta-skill steps requiring full tool/LLM agency. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents
Delegate a self-contained task to a sub-Agent (Codex, Claude Code, or Pi via background process). The original use case was coding tasks — building features, reviewing PRs, refactoring — but the skill is the generic "spawn a sub-Agent with full tool surface" slot used by meta-skill DAG steps for any LLM-driven sub-task (policy review, trace parsing, report synthesis, document generation). Renamed from ``coding-agent`` to reflect actual usage; the wrapped CLIs (codex / claude / pi) still bias toward coding workloads. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative tasks that need file exploration, (5) meta-skill steps requiring full tool/LLM agency. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). Prefer non-interactive CLI modes such as codex exec, claude --print, opencode run, or pi -p.
description_zh
将一个自包含任务委派给子代理（Codex、Claude Code或后台运行的Pi）。最初用于编码任务（构建功能、审查PR、重构），但本技能是meta-skill DAG步骤用于任何LLM驱动子任务（策略审查、跟踪解析、报告综合、文档生成）的通用'启动带完整工具面的子代理'插槽，由 coding-agent 更名以反映实际用途。适用于：构建新功能/应用、审查PR（在临时目录中启动）、重构大型代码库、需文件探索的迭代任务、需完整工具/LLM能力的meta-skill步骤。不适用于：简单一行修复、读代码、聊天中线程绑定的ACP请求，或在~/clawd工作区内的任何工作。优先使用非交互CLI模式，如 codex exec、claude --print、opencode run 或 pi -p。
Generic "spawn a sub-Agent" entry point for delegating self-contained
tasks to Codex / Claude Code / OpenCode / Pi via background process.
Wrapping CLIs are coding-oriented, but the skill itself is used as
the generic sub-Agent slot by meta-skill DAGs for any LLM-driven
sub-task (file edits, document generation, policy review, etc.).
Use opensquilla's exec_command, background_process, and process tools for coding agent work. OpenSquilla does not expose a bash tool; do not use the legacy bash tool-call DSL.
Non-Interactive CLI Mode
OpenSquilla's process tools do not expose a pty parameter. Prefer non-interactive command modes that run and exit cleanly:
# ✅ Correct for Codex/Pi/OpenCode
exec_command(command="codex exec 'Your prompt'")
For Claude Code (claude CLI), use --print --permission-mode bypassPermissions instead.
--dangerously-skip-permissions with PTY can exit after the confirmation dialog.
--print mode keeps full tool access and avoids interactive confirmation:
# ✅ Correct for Claude Code (no PTY needed)cd /path/to/project && claude --permission-mode bypassPermissions --print'Your task'# For background execution: use background_process# ❌ Wrong for Claude Code
exec_command(command="claude --dangerously-skip-permissions 'task'")
OpenSquilla Tool Parameters
Tool
Key parameters
Description
exec_command
command, workdir, timeout
Run a foreground shell command.
background_process
command, workdir, timeout
Start a long-running command and return .
session_id
process
action, session_id, data, offset, limit
Poll, log, write to, or stop a background process.
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)
eof
Close stdin
remove
Remove a finished session from the process list
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
exec_command(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_process
For longer tasks, use background_process:
# Start agent in target directory.
background_process(workdir="~/project", command="codex exec --full-auto 'Build a snake game'")
# Returns session_id for tracking# Wait for it to finish — blocks until the process exits (or the timeout# elapses, in which case just call wait again). Prefer this over polling in a# loop: a looped process(action="poll") burns a full turn + tokens each time.
process(action="wait", session_id="XXX")
# Peek at output without blocking (optional, for progress)
process(action="log", session_id="XXX")
# Send input (if agent asks a question)
process(action="write", session_id="XXX", data="y")
# Submit with Enter (like typing "yes" and pressing Enter)
process(action="submit", session_id="XXX", data="yes")
# Kill if needed
process(action="kill", session_id="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
exec_command(workdir="~/project", command="codex exec --full-auto 'Build a dark mode toggle'")
# Background for longer work
background_process(workdir="~/project", command="codex exec --full-auto 'Refactor the auth module'")
Reviewing PRs
⚠️ CRITICAL: Never review PRs in OpenSquilla'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_DIRcd$REVIEW_DIR && gh pr checkout 130
exec_command(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
exec_command(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
background_process(workdir="~/project", command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'")
background_process(workdir="~/project", 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>"
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_process(workdir="/tmp/issue-78", command="pnpm install && codex exec --full-auto 'Fix issue #78: <description>. Commit and push.'")
background_process(workdir="/tmp/issue-99", command="pnpm install && codex exec --full-auto 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'")
# 3. Monitor progress
process(action="list")
process(action="log", session_id="XXX")
# 4. Create PRs after fixescd /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
Use the right execution mode per agent:
Codex/Pi/OpenCode: non-interactive command mode (codex exec, opencode run, pi -p)
Claude Code: --print --permission-mode bypassPermissions (no PTY required)
Respect tool choice - if user asks for Codex, use Codex.
Orchestrator mode: do NOT hand-code patches yourself.
If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
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 inside your OpenSquilla state directory ($OPENSQUILLA_STATE_DIR, default ~/.opensquilla/state) - keep agent state separate from project worktrees.
NEVER checkout branches inside the live OpenSquilla runtime state/workspace directories - use an explicit project worktree.
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).
Then only update again when something changes:
a milestone completes (build finished, tests passed)
the agent asks a question / needs input
you hit an error or need user action
the agent finishes (include what changed + where)
If you kill a session, immediately say you killed it and why.
This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.
Auto-Notify on Completion
For long-running background tasks, ask the agent to print a clear completion line so progress is visible in process(action="log", ...) output:
... your task here.
When completely finished, send a brief status update in this session.
Example:
background_process(workdir="~/project", command="codex exec --full-auto 'Build a REST API for todos.
When completely finished, print: Done: Built todos REST API with CRUD endpoints'")
This makes completion visible in the background process log.
Learnings (Jan 2026)
Prefer non-interactive modes: Coding agents are easiest to supervise when they print progress and exit cleanly.
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" 🦞
