cline/sdk/examples/plugins/agents-squad

Agent Squad Plugin

Spin up background subagents from any Cline SDK agent. Each subagent runs as its own session with its own provider, model, and system prompt — useful for parallel recon, planning, implementation, and review.

Quick start

import { ClineCore } from "@cline/core";

const cline = await ClineCore.create({ backendMode: "auto" });

await cline.start({
  config: {
    providerId: "cline",
    modelId: "anthropic/claude-sonnet-4.6",
    cwd: process.cwd(),
    enableTools: true,
    systemPrompt: "You are a coding assistant with access to subagents.",
    pluginPaths: ["./examples/plugins/agents-squad"],
  },
  prompt: "Use subagents to investigate and refactor this repo.",
  interactive: true,
});

Pass the plugin directory as the path. The loader reads package.json and discovers entry points from the cline.plugins field.

Tools

Tool	Purpose
start_subagent	Start a subagent in the background and return a session ID immediately.
message_subagent	Send a follow-up message to a running subagent.
get_subagent	Poll status, output, or error for a subagent session.
list_agent_presets	List bundled, global, and project agent presets.
list_skills / get_skill	Discover and load loadable skill instructions.
save_handoff / read_handoff	Share text between subagents in the same conversation.

start_subagent accepts preset and/or instructions. When preset is omitted it defaults to phantom (configurable via CLINE_SUBAGENT_DEFAULT_PRESET).

Bundled agents

Agent	Model	Role
phantom	google/gemini-3-flash-preview	Fast codebase recon — maps structure, surfaces conventions, never implements.
oracle	anthropic/claude-opus-4.6	Opinionated planning — challenges assumptions and produces execution-ready plans.
anvil	anthropic/claude-opus-4.6	Surgical implementation — reads before writing, stays in scope, reports exact diffs.
inquisitor	openai/gpt-5.5	Adversarial review — finds bugs, severity-ranks findings.

Typical orchestration

parent → start_subagent(preset: "phantom", task: "Map the auth module")
       → phantom: save_handoff("auth/recon.md", ...)
       → start_subagent(preset: "oracle", task: "Plan refactor from auth/recon.md")
       → oracle: save_handoff("auth/plan.md", ...)
       → start_subagent(preset: "anvil", task: "Execute auth/plan.md")
       → start_subagent(preset: "inquisitor", task: "Review anvil's changes")

Custom agents and skills

Drop a Markdown file with YAML frontmatter into one of these directories. Project overrides global, global overrides bundled (by name).

Kind	Bundled	Global	Project
Agents	agents/ next to index.ts	~/.cline/data/settings/agents/	<cwd>/.cline/agents/
Skills	skills/ next to index.ts	~/.cline/data/settings/skills/	<cwd>/.cline/skills/

Agent file:

---
name: my-agent
description: One-line description shown in list_agent_presets
providerId: cline
modelId: anthropic/claude-sonnet-4.6
cwd: ./src
maxIterations: 25
---

You are a specialized agent that...

Skill file:

---
name: my-skill
description: What this skill teaches
---

When performing this task, follow these steps...

Skills are reusable instructions any agent can pull in at runtime via get_skill. Bundled skills include code-review, test-generation, refactoring, debugging, api-design, migration, and documentation.

Handoff store

Subagents in the same conversation share a small file store, scoped to the conversation ID:

• save_handoff({ path, content }) — writes a file
• read_handoff({ path }) — reads it back

Files live under ~/.cline/data/plugins/subagents/handoffs/<conversationId>/. Paths are validated to prevent traversal.

Configuration

All optional. Environment variables override defaults:

Variable	Default
CLINE_SUBAGENT_PROVIDER_ID	cline
CLINE_SUBAGENT_MODEL_ID	anthropic/claude-sonnet-4.6
CLINE_SUBAGENT_DEFAULT_PRESET	phantom
CLINE_SUBAGENTS_BACKEND_MODE	auto (auto | hub | local)
CLINE_SUBAGENT_CWD	process.cwd()
CLINE_DATA_DIR	~/.cline/data

How it works

Each subagent is a full Cline SDK session created via ClineCore.create(...). start_subagent resolves the preset, merges any overrides, starts a non-interactive session, and returns the session ID immediately. The first turn runs in the background; when it finishes (or fails) the result is stored and — unless notifyParent: false — pushed back to the parent session as a steer message. The parent can also poll with get_subagent.

Observability

The plugin reports through both host observability channels (feature-detected, so it works on hosts without them):

• ctx.logger — structured, session-scoped logs: plugin setup, each subagent start, and queued follow-ups, tagged with the plugin name in the host's log sink.
• ctx.telemetry — aggregated signals: a subagents_setup event, a subagents.started counter (by preset/provider), a subagent_turn_completed event (status, preset, finish reason), and a subagents.turn_duration_ms histogram. Properties are low-cardinality only — never task text or subagent output. The host namespaces everything under plugin. and stamps plugin_name.

See telemetry.ts for the full ctx.telemetry / ctx.logger contract.