🤖 subagent-cli

English | 中文

⚡ Wrap any Agent CLI as a reusable subAgent for your primary Agent, with parallel task dispatch.

---

🎬 Natural Language Demo

Trigger subagent-cli by natural language in Codex and Claude Code, without using scripts/*.sh as the entrypoint.

---

🧭 What is this?

TL;DR: Let expensive Agents think, let cheap Agents work.

🎭 Role	👤 Who	⚙️ Does What
Boss (Orchestrator)	Codex / Claude Code / any primary Agent	Understand requirements, split tasks, review results
Worker (SubAgent)	Claude Code / DeepSeek / Codex / ...	Execute coding, testing, review in parallel

┌─────────────┐
│  Primary     │  ← Thinks, plans, reviews (expensive model)
│  Agent       │
└──────┬──────┘
       │ dispatch
  ┌────┼────┬────┐
  ▼    ▼    ▼    ▼
┌───┐┌───┐┌───┐┌───┐
│ S1││ S2││ S3││ S4│  ← Execute in parallel (cheap models, mix & match)
└───┘└───┘└───┘└───┘

🎯 Use cases:

• Save Codex quota — GPT-5.5 plans only, Claude Code + DeepSeek V4 do the heavy lifting
• Heterogeneous teams — Architect (Claude) designs, Developer (Codex) codes, Reviewer (CodeBuddy) audits
• Batch processing — 10 files to migrate? 10 subAgents in parallel, primary Agent collects results

Core value: Separate "thinking" from "doing". Use premium models for decisions, low-cost models for execution. Total cost can be 1/5 of using premium models for everything.

🔎 Common Search Phrases

People looking for this project may search for:

• Claude Code subAgent, Claude Code plugin, Claude Code slash command
• Codex CLI wrapper, Codex subAgent, OpenAI Codex CLI automation
• OpenCode CLI wrapper, CodeBuddy CLI wrapper, Gemini CLI automation, Aider automation
• AI coding agent, multi-agent coding, agent orchestration, parallel coding agents
• LLM CLI wrapper, subagent tool, background task execution, JSON output

---

🚀 Usage

🗣️ Trigger in Agent CLI

# Claude Code slash command
/subagent-cli

# Natural language (works in Claude Code & Codex)
"Use Codex CLI as a subAgent"
"Wrap OpenCode CLI"
"Run 3 Claude Code subAgents in parallel to write tests"

💻 Terminal commands

# Foreground (sync)
bash scripts/claude-ctl.sh run --task-id t1 --permission-mode acceptEdits -- "List files"

# Background (async)
bash scripts/codex-ctl.sh run --task-id t2 --bg --sandbox workspace-write --skip-git-check -- "Analyze code"

# Status / Result / Cancel / Cleanup
bash scripts/claude-ctl.sh status --task-id t1
bash scripts/codex-ctl.sh result --task-id t2
bash scripts/claude-ctl.sh cancel --task-id t1
bash scripts/claude-ctl.sh cleanup

📤 Output format

All commands output JSON:

{"task_id":"t1","status":"completed","exit_code":0,"result":"Hello, World!"}
{"task_id":"t1","status":"running","pid":1234,"mode":"background"}
{"error":"connection_or_auth_failure","detail":"...","action":"Please check API Key..."}

---

📦 Install

🧩 Option 1: Claude Code Plugin (Recommended)

# Add marketplace
/plugin marketplace add silicon-based-Lin/subagent-cli

# Install from marketplace
/plugin install subagent-cli@<marketplace-name>

Automatically registers the /subagent-cli slash command and skill triggers.

📥 Option 2: Git Clone (any Agent CLI)

Clone the repo and copy to your Agent CLI's skills directory. Example with Codex:

git clone https://github.com/silicon-based-Lin/subagent-cli.git /tmp/subagent-cli
mkdir -p .agents/skills
cp -r /tmp/subagent-cli .agents/skills/subagent-cli
rm -rf /tmp/subagent-cli

For other CLIs, copy to the corresponding skills directory:

CLI	📁 Skills directory
Claude Code	.claude/skills/
Codex	.agents/skills/

✅ Prerequisites

Requirement	📝 Notes
Bash	Built-in on macOS/Linux; Git Bash on Windows
Target CLI	Installed and authenticated (see references/cli-patterns.md)
Python	Used for UTF-8 result extraction

🧩 Supported Agent CLI Wrappers

Agent CLI	Wrapper	Common use case
Claude Code	scripts/claude-ctl.sh	Claude Code subAgent, review agent, test generation worker
Codex CLI	scripts/codex-ctl.sh	Codex subAgent, implementation worker, code analysis task runner
OpenCode	scripts/opencode-ctl.sh	OpenCode wrapper for parallel coding and refactoring tasks
CodeBuddy	scripts/codebuddy-ctl.sh	Code review agent, QA agent, verification worker
Gemini CLI / Aider / other Agent CLIs	Template extension	Add a new *-ctl.sh wrapper with the same JSON task interface

---

⚠️ Warning

Caution

All *-ctl.sh scripts run Agent CLIs in sandbox or permission-bypass mode. SubAgents will have file read/write and command execution permissions without human confirmation.

Do NOT run in production, directories with sensitive data, or with unreviewed prompts.

Risks:

• SubAgents may perform unexpected file operations
• SubAgents may access files outside the working directory
• Parallel tasks may exhaust system resources or API quotas

Always run inside a Git repo so you can git diff and git checkout to rollback.

---

🧪 Multi-Agent Examples

🔁 Homogeneous parallel — same CLI, multiple tasks

"Run 3 Claude Code subAgents in parallel:
 - subAgent-1: Write unit tests for user module
 - subAgent-2: Write unit tests for order module
 - subAgent-3: Write unit tests for payment module
 Aggregate coverage report when all complete"

🧬 Heterogeneous — different CLIs, different roles

"Build a 4-agent team:
 - Architect (Claude Code): Design DB schema and API interfaces
 - Backend (Codex): Implement API logic
 - Frontend (OpenCode): Write React components
 - QA (CodeBuddy): Code review and test verification
 Run in parallel, QA agent produces final report"

✅ Pipeline with review gates

"Complete dev pipeline with subAgents:
 Phase 1 (parallel): Codex-1 writes feature A, Codex-2 writes feature B
 Phase 2: Claude Code cross-reviews both features
 Phase 3: CodeBuddy runs tests and outputs quality report"

---

🛠️ CLI Options Reference

🐚 claude-ctl.sh

🚩 Flag	📝 Description
--task-id <id>	Task ID (required)
--bg	Run in background
--permission-mode <mode>	acceptEdits / bypassPermissions / default / plan
--allowed-tools <tools>	Restrict tools, e.g. "Bash,Write,Read"
--max-turns <n>	Limit agent turns
--model <model>	Specify model

🤖 codex-ctl.sh

🚩 Flag	📝 Description
--task-id <id>	Task ID (required)
--bg	Run in background
--sandbox <mode>	read-only / workspace-write / danger-full-access
--bypass	Skip all approvals and sandbox
--model <model>	Specify model (e.g. o3, o4-mini, gpt-4.1)
--workdir <dir>	Working directory
--skip-git-check	Allow running outside Git repos

🧰 opencode-ctl.sh

🚩 Flag	📝 Description
--task-id <id>	Task ID (auto-generated if omitted)
--bg	Run in background
--model <provider/model>	Specify model (e.g. anthropic/claude-sonnet-4-6)
--agent <name>	Specify agent
--dir <dir>	Working directory
--skip-permissions	Auto-approve all permissions (dangerous)
--files <f1,f2>	Attach files (comma-separated)

🔎 codebuddy-ctl.sh

🚩 Flag	📝 Description
--task-id <id>	Task ID (auto-generated if omitted)
--bg	Run in background
--permission-mode <mode>	acceptEdits / bypassPermissions / default / plan
--allowed-tools <tools>	Restrict tools
--max-turns <n>	Limit agent turns
--model <model>	Specify model

---

🧱 Design Decisions

🐚 Why Bash?

• Zero dependencies — Bash is built-in everywhere (Git Bash on Windows)
• Zero code invasion — Only calls CLI public interfaces, never modifies target CLI
• Process isolation — Each task is an independent OS process; crashes don't cascade
• Transparent — cat *.ctl.sh to audit the full behavior
• Unified interface — All CLIs share run / status / result / cancel / cleanup
• JSON-native output — Structured output, no regex parsing needed

🔌 Why not MCP?

SubAgent's core need is "batch dispatch + parallel execution + result collection". Bash's stateless process model is a perfect fit. MCP is better suited for real-time interactive tool calls with bidirectional streaming.

🛡️ Auth Error Detection

All *-ctl.sh scripts include built-in check_auth_errors that scans output for keywords like auth, unauthorized, 401, 403, timeout, ECONNREFUSED. On match: immediately kill the task, mark as failed, return actionable error JSON.

---

🗂️ Project Structure

subagent-cli/
├── .claude-plugin/
│   └── plugin.json             # Claude Code plugin manifest
├── commands/
│   └── subagent-cli.md         # Slash command definition
├── scripts/
│   ├── check_cli.sh            # CLI availability check
│   ├── claude-ctl.sh           # Claude Code wrapper
│   ├── codex-ctl.sh            # Codex CLI wrapper
│   ├── opencode-ctl.sh         # OpenCode wrapper
│   └── codebuddy-ctl.sh        # CodeBuddy wrapper
├── references/
│   └── cli-patterns.md         # CLI install & usage reference
├── SKILL.md                    # Skill definition (shared by all install methods)
└── README.md

---

➕ Adding a New CLI

# 1. Recon: find non-interactive mode and output format flags
<cli> --help 2>&1

# 2. Copy template
cp scripts/claude-ctl.sh scripts/<cli>-ctl.sh

# 3. Modify: replace CLI command, flag mappings, auth error keywords

See SKILL.md for the full workflow.

---

📄 License

MIT