Sub-Agent (opensquilla process tools)
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:
bash# ✅ 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:
bash# ✅ 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:
bash# 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:
bash# 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
bash# 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.
bash# 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 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!)
bash# 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>"
Claude Code
bash# Foreground exec_command(workdir="~/project", command="claude --permission-mode bypassPermissions --print 'Your task'") # Background background_process(workdir="~/project", command="claude --permission-mode bypassPermissions --print 'Your task'")
OpenCode
bashexec_command(workdir="~/project", command="opencode run 'Your task'")
Pi Coding Agent
bash# Install: npm install -g @mariozechner/pi-coding-agent exec_command(workdir="~/project", command="pi -p 'Your task'") # Non-interactive mode exec_command(command="pi -p 'Summarize src/'") # Different provider/model exec_command(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:
bash# 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 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
- 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)
- Codex/Pi/OpenCode: non-interactive command mode (
- 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:
bashbackground_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 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" 🦞
