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.