Subagents

Turn any AI coding agent into your subagent.
Wrap kimi, claude, codex, pi, opencode, qwen, kiro, gemini — or any CLI agent — as a reusable subagent,
then orchestrate them with dynamic workflows: pipelines, parallel swarms, and nested graphs.

_{English · 中文}

---

Supported Backends

Kimi   Claude Code   Codex   Pi   OpenCode   Qwen Code   Kiro   Gemini CLI

_{Backend and transport are auto-detected. Override with --backend <name> and --transport cli|acp.}

Backend	Command	Transports	System Prompt
kimi	kimi	CLI, ACP	inline
claude	claude	CLI	native (append + overwrite)
codex	codex	CLI	inline
pi	pi	CLI	native (append + overwrite)
opencode	opencode	CLI, ACP	inline
qwen	qwen	CLI, ACP	native (append + overwrite)
kiro	kiro-cli	CLI, ACP	inline
gemini	gemini	CLI, ACP	inline

These skills follow the Agent Skills specification — compatible with any skills-compatible agent, including Claude Code, Codex, and Open Code.

Features

🔗 Dynamic Workflow Orchestration Pipeline, parallel, and nested workflows with workflow.py. Chain agents, split-merge, resume failed stages — compose complex multi-agent topologies declaratively.	🧩 Any Agent CLI as Subagent Wrap any CLI agent as a reusable subagent. Auto-detection picks the right backend; override with --backend. Extensible — add new backends in a few lines.
🔁 Persistent Sessions Every run creates a named session. Resume it later and the agent remembers all prior context. Build up multi-turn conversations over days.	⚡ Parallel Swarms Fan out tasks across multiple agents with --bg, then subagents wait to collect results. Run 10 reviewers against 10 files simultaneously.
📡 JSONL Output --output json for structured, streamable, versioned JSONL. Every event typed and timestamped — ready for piping into other tools.	🪶 Zero Dependencies Python 3.10+ standard library only. No pip install, no virtualenv. Drop the scripts in and run.

Installation

skit (Recommended)

skit install ./subagents-skills --all

Manually

Claude Code cp -r skills/subagents .claude/skills/

Codex cp -r skills/subagents ~/.codex/skills/

OpenCode git clone https://github.com/vlln/subagents-skill.git \ ~/.opencode/skills/subagents-skills

Skills

Skill	Description
subagents	Dispatch tasks to named agent sessions across multiple backends. Session resume, parallel swarms, JSONL output.
workflow	Multi-agent orchestration — pipeline, parallel, and phase-based workflows. Nested sub-workflows, resume, structured output.

Quick Start

# Define an agent (optional)
mkdir -p .agents/subagents
cat > .agents/subagents/reviewer.md << 'EOF'
---
name: reviewer
description: Expert code reviewer
---
You are a code reviewer. Analyze code for correctness, security, and best practices.
EOF

# Run a task
scripts/subagents run reviewer review-auth "Review src/auth.ts for security issues"

# Resume the session with more context
scripts/subagents run reviewer review-auth "Now check the error handling"

# Run 3 reviewers in parallel
scripts/subagents run --bg reviewer r1 "Review src/auth.ts"
scripts/subagents run --bg reviewer r2 "Review src/db.ts"
scripts/subagents run --bg reviewer r3 "Review src/api.ts"
scripts/subagents wait r1 && scripts/subagents wait r2 && scripts/subagents wait r3

# List all agents and sessions
scripts/subagents list

Demo

Record animated terminal demos with console2svg:

# Install
npm install -g console2svg

# Record subagents demo (queue, cwd, send, cancel, status)
console2svg "bash demos/subagents-demo.sh" \
    -o docs/subagents.svg -w 100 -h 40 \
    -d macos --theme dark -v --fps 12 --timeout 25

# Record workflow demo (TTY tree, phases, spinners, live updates)
console2svg "bash demos/workflow-demo.sh" \
    -o docs/workflow.svg -w 100 -h 36 \
    -d macos --theme dark -v --fps 12 --timeout 15

Development

# Unit tests (no backend required, CI-safe)
python3 -m pytest tests/ --ignore=tests/test_integration.py

# Integration tests (requires kimi CLI)
SKIP_INTEGRATION=0 python3 -m pytest tests/test_integration.py -v

# All tests
SKIP_INTEGRATION=0 python3 -m pytest tests/ -v

Layer	File	Count	Trigger	Time
Unit	tests/test_subagents.py	79	pytest auto	<1s
Unit	tests/test_workflow.py	26	pytest auto	<1s
Integration	tests/test_integration.py	8	SKIP_INTEGRATION=0	~3min

License

MIT