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
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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" 🦞
