subagent-cli

Run external AI agent CLIs as subprocesses via Bash to delegate complex coding tasks. Use as a "power tool" to extend execution capability while keeping your identity, judgment, and memory.

Relationship with Framework Execution Modes

This skill applies only when the Bash tool is available.

Important: For Mode C (codex/*), Mode D (cursor/*), and Mode G (gemini/*), the framework runs each engine directly. You do not need to call codex exec (Mode C), cursor-agent -p (Mode D), or the Gemini CLI (Mode G) from Bash yourself. Refer to the relevant sections only when you explicitly want a different CLI (cursor-agent, claude -p, codex exec, etc.).

Windows exception: On native Windows, if shell execution becomes policy blocked, or codex exec exited with code 1 keeps recurring, stop retrying local codex exec. For shell-required tasks, use machine as the standard fallback with engine=claude and an explicit working_directory.

Tool Selection Priority

Choose by cost efficiency.

Rule: In non-Windows or otherwise healthy shell environments, try codex exec first. On native Windows when shell execution is blocked or unstable, skip local codex exec and use machine (engine=claude) as the standard path. For other failures or unsuitable tasks, fall back to cursor-agent → claude.

When to Use

• Multi-file code changes
• Test creation or modification
• Code review
• Refactoring
• Bug investigation and implementation
• New feature implementation

When NOT to Use

• Small edit in a single file (do it yourself)
• Memory read/write (use your tools)
• External API calls (use dedicated tools)
• Search or research only (web_search or Read is enough)

1. codex exec (Recommended)

Applicability: Mode S or Mode A/B (with Bash permission). Not needed in Mode C — the framework runs Codex directly. In Mode D/G, the framework runs those engines; skip this section unless you intentionally use codex as an alternative.

Basic Syntax

codex exec --full-auto -C /path/to/workspace "prompt"

Specify the project path for working directory -C. For the main project, $ANIMAWORKS_PROJECT_DIR may be available (set in Mode S Bash execution environment).

Key Options

Examples

Code Generation

codex exec --full-auto --ephemeral -C /home/user/dev/myproject \
  "Implement Markdown parser in src/utils/parser.py. Do not break existing tests."

Code Review

codex exec --full-auto --ephemeral -C /home/user/dev/myproject \
  review

Test Creation

codex exec --full-auto --ephemeral -C /home/user/dev/myproject \
  "Create unit tests for src/utils/parser.py in tests/test_parser.py."

Save Result to File

codex exec --full-auto --ephemeral -C /home/user/dev/myproject \
  -o /tmp/codex_result.txt \
  "Analyze this project's architecture and suggest improvements."

2. cursor-agent -p (Alternative)

Applicability: Mode S or Mode A/B (with Bash permission). Also applies in Mode C/G when Bash is available. In Mode D, the framework runs cursor-agent — manual cursor-agent -p is usually unnecessary.

Basic Syntax

cursor-agent -p --trust --force --workspace /path/to/workspace "prompt"

Key Options

Examples

Code Generation

cursor-agent -p --trust --force \
  --workspace /home/user/dev/myproject \
  "Add POST /users endpoint to src/api/routes.py. Include validation."

Read-Only Investigation

cursor-agent -p --trust --mode ask \
  --workspace /home/user/dev/myproject \
  "Are there security issues in this auth flow?"

Save Result to File

cursor-agent -p --trust --force \
  --workspace /home/user/dev/myproject \
  --output-format text \
  "Find modules with low test coverage and improve them" > /tmp/cursor_result.txt

3. claude -p (Fallback)

Applicability: Mode S or Mode A/B (with Bash permission). Also applies in Mode C/D/G when Bash is available.

Use only when codex/cursor-agent cannot handle the task. API cost is high.

Basic Syntax

claude -p --dangerously-skip-permissions --output-format text "prompt"

Key Options

Example

claude -p --dangerously-skip-permissions --no-session-persistence \
  --model haiku --max-budget-usd 0.5 \
  --output-format text \
  "Improve error handling in src/core/parser.py"

Writing Prompts

Subagents do not have AnimaWorks context. Write clear, self-contained prompts.

Good Prompt

Implement a Python module with these requirements:

File: src/utils/validator.py

Requirements:
- Pydantic v2 BaseModel-based validator
- email, username, password fields
- Password: 8+ chars, alphanumeric
- Raise custom exception on validation error

Constraints:
- from __future__ import annotations at top
- Google-style docstring
- Do not break existing tests

Bad Prompt

Fix the validation somehow

→ No context, "somehow" is vague.

Handling Output

Capture stdout

RESULT=$(codex exec --full-auto --ephemeral -C /path "prompt" 2>/dev/null)
echo "$RESULT"

Via File (Recommended for codex)

codex exec --full-auto --ephemeral -C /path \
  -o /tmp/result.txt "prompt"
# Read result
cat /tmp/result.txt

Success/Failure from Exit Code

codex exec --full-auto --ephemeral -C /path "prompt"
if [ $? -eq 0 ]; then
  echo "Success"
else
  echo "Failed — fallback to cursor-agent"
  cursor-agent -p --trust --force --workspace /path "same prompt"
fi

Background Execution (Important)

Subagent runs can take 5–20+ minutes. Foreground execution blocks the session, so always run in the background.

Basic Pattern: nohup + Result File

nohup codex exec --full-auto --ephemeral -C /path/to/workspace \
  -o /tmp/codex_result.txt \
  "prompt" > /tmp/codex_stdout.log 2>&1 &
echo "PID: $!"

For cursor-agent:

nohup cursor-agent -p --trust --force \
  --workspace /path/to/workspace \
  "prompt" > /tmp/cursor_result.txt 2>&1 &
echo "PID: $!"

Completion Check

# Check if process is still running
ps -p <PID> > /dev/null 2>&1 && echo "Running" || echo "Done"

# Read result (after completion)
cat /tmp/codex_result.txt
# or
cat /tmp/cursor_result.txt

Timeout

Use timeout to avoid runaway runs:

nohup timeout 30m codex exec --full-auto --ephemeral -C /path \
  -o /tmp/codex_result.txt \
  "prompt" > /tmp/codex_stdout.log 2>&1 &

• Recommended timeout: 30 min (30m)
• Small tasks: 10 min (10m)
• Large refactors: 60 min (60m)

Continue Other Work While Running

After background run, you may proceed with other tasks without waiting. Periodically check process status; when done, read the result and record in episodes/.

Safety Guidelines

1. Always specify working directory — Otherwise runs in current directory
2. Do not include secrets in prompts — API keys, passwords, etc.
3. codex runs in sandbox with --full-auto — Writes outside workspace are restricted
4. Check changes with git diff after execution — Verify no unintended changes
5. Use --ephemeral — Prevents session file accumulation

Fallback Strategy

1. Try codex exec
   ↓ failure or poor quality
2. Retry with cursor-agent -p
   ↓ failure or poor quality
3. Final attempt with claude -p (with --max-budget-usd)
   ↓ still failure
4. Try yourself or report to supervisor

Notes

• Subagents cannot access AnimaWorks memory or tools. They are "coding hands" only
• Record execution results in your episodes/ and accumulate patterns in knowledge/
• Runs take 5–20+ minutes. Always run in background and set timeout
• Work in git-tracked repositories (easier tracking and rollback)
• In Mode S, ANIMAWORKS_ANIMA_DIR and ANIMAWORKS_PROJECT_DIR are set as environment variables when Bash runs