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 · 中文}

---

Installation

skit (Recommended)

skit install https://github.com/vlln/subagents-skill/tree/main/skills/subagents
skit install https://github.com/vlln/subagents-skill/tree/main/skills/workflow

Manually

Agent	Command
Claude Code	cp -r skills/subagents .claude/skills/ && cp -r skills/workflow .claude/skills/
Codex	cp -r skills/subagents ~/.codex/skills/ && cp -r skills/workflow ~/.codex/skills/
OpenCode	git clone https://github.com/vlln/subagents-skill.git ~/.opencode/skills/subagents-skills
Kimi	cp -r skills/subagents ~/.kimi/skills/ && cp -r skills/workflow ~/.kimi/skills/

---

Skills

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

Requirements

• Python 3.10+

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

🔗 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 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.	⚡ Swarm with TUI subagents swarm launches N agents in parallel with a real-time braille progress grid. Watch tool calls, elapsed time, and status for every agent at once. subagents swarm reviewer rev \ --template "Review {{item}}" \ --items "src/auth.ts" "src/db.ts" "src/api.ts"
📬 Task Queue Background sessions (--bg) support a sequential task queue. Send more tasks with subagents send while the session runs — cancel individual tasks or the whole queue. subagents run --bg reviewer s1 "analyze code" subagents send s1 "refactor based on analysis" subagents send s1 "update tests" subagents cancel s1 --task 2 subagents wait s1	🎯 Goal-Driven Give a high-level goal; the agent self-evaluates and stops when complete or max iterations reached. No micro-management — just the objective. subagents goal reviewer auth-review \ "Refactor auth module: JWT-based, all tests pass, API docs updated" subagents wait auth-review

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 (legacy bg + wait)
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

# Or use swarm with TUI progress grid
scripts/subagents swarm reviewer rev \
  --template "Review {{item}}" \
  --items "src/auth.ts" "src/db.ts" "src/api.ts"

# Goal-driven: let the agent work autonomously
scripts/subagents goal reviewer auth-review \
  "Refactor auth module: JWT-based, all tests pass"

# 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/assets/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/assets/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	82	pytest auto	<1s
Unit	tests/test_progress.py	21	pytest auto	<1s
Unit	tests/test_workflow.py	26	pytest auto	<1s
Integration	tests/test_progress_integration.py	6	pytest auto	~12s
Integration	tests/test_integration.py	8	SKIP_INTEGRATION=0	~3min

License

MIT