Cline SDK Guide

What it does

When your agent uses it

• Writing an agent with the Cline SDK
• Defining custom tools with createTool
• Subscribing to Agent or ClineCore events
• Building multi-agent teams or scheduling runs
• Preparing a Cline SDK agent for production

Example prompts

• “Build a Cline SDK agent with a custom tool that looks up order status and ends the run once it returns an answer.”
• “Why does agent.subscribe() never fire the content_update events I expected?”
• “Run this ClineCore session and make sure its resources are cleaned up afterwards.”

Requirements

• Node.js 22 or later
• The @cline/sdk package

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

1. 1Install with npm install @cline/sdk. The @cline/sdk package re-exports everything from @cline/core, @cline/agents, @cline/llms, and…
2. 2Requires Node.js 22 or later.
3. 3Use createTool() from @cline/sdk (or @cline/shared) to define tools. Tool names must be snake_case.
4. 4Return errors as structured data from tool execute functions. Throwing counts as a "mistake" against the agent's mistake limit.
5. 5Use lifecycle: { completesRun: true } on tools that should end the agent loop (e.g. a "submit answer" tool).
6. 6When using ClineCore, always call dispose() when done to clean up resources.
7. 7The standalone Agent and ClineCore have different event systems. For Agent: use agent.subscribe() to get AgentRuntimeEvent types (text…

What it can do on your machine

Read from SKILL.md and the folder at commit fa840c7. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • npm

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • docs.cline.bot
  • discord.gg

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Cline SDK Guide loads about 2.2k tokens when it runs, and up to ~27k if it reads all its reference files. Until then it costs about 68 tokens; SKILL.md has 544 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~68

When it runs · the whole SKILL.md, loaded when a task matches

~2.2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~27k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from cline/cline at commit fa840c7, republished under its Apache-2.0 licence (© cline). 544 words, ~2,198 tokens.

name

cline-sdk

description

Comprehensive Cline SDK skill for building AI agents. Covers the Agent runtime, ClineCore sessions, custom tools, plugins, events, LLM providers, scheduling, multi-agent teams, and production deployment. Use for any task involving @cline/sdk or its sub-packages.

metadata.references

agent, clinecore

./references/agent/REFERENCE.md           # Start here for lightweight agents
./references/clinecore/REFERENCE.md       # Start here for full runtime
./references/agent/api.md                 # Agent class, config, methods
./references/tools/REFERENCE.md           # Creating and using tools
./references/plugins/REFERENCE.md         # Plugin system
./references/providers/REFERENCE.md       # LLM provider configuration

Which API?
+-- I want a simple, stateless agent with custom tools
|   +-- agent/ (Agent class from @cline/agents)
+-- I need session persistence, built-in tools, config discovery
|   +-- clinecore/ (ClineCore from @cline/core)
+-- I want built-in file/shell/search/web tools
|   +-- clinecore/ (has built-in tools; Agent does not)
+-- I want scheduled or recurring agents
|   +-- clinecore/ (automation API)
+-- I need multi-process or multi-client session sharing
|   +-- clinecore/ (hub-backed runtime)
+-- I'm building a browser-compatible agent
|   +-- agent/ (no Node.js dependencies)

Tools?
+-- Define a custom tool with schema -> tools/REFERENCE.md
+-- Use built-in tools (bash, editor, read_files) -> tools/REFERENCE.md (built-in section)
+-- Control tool approval/policies -> tools/REFERENCE.md (policies section)
+-- Tool that ends the agent loop -> tools/REFERENCE.md (completion tools)
+-- Package tools as a reusable plugin -> plugins/REFERENCE.md

Events?
+-- Stream text/reasoning in real time -> events/REFERENCE.md
+-- Track token usage and costs -> events/REFERENCE.md
+-- Watch tool calls -> events/REFERENCE.md
+-- Detect completion/errors -> events/REFERENCE.md
+-- Hook into lifecycle stages -> plugins/REFERENCE.md

Providers?
+-- Anthropic (Claude) -> providers/REFERENCE.md
+-- OpenAI (GPT) -> providers/REFERENCE.md
+-- Google (Gemini/Vertex) -> providers/REFERENCE.md
+-- AWS Bedrock -> providers/REFERENCE.md
+-- Mistral -> providers/REFERENCE.md
+-- OpenAI-compatible (vLLM, Together, etc.) -> providers/REFERENCE.md
+-- Custom/self-hosted provider -> providers/REFERENCE.md

Plugins?
+-- Package tools + hooks together -> plugins/REFERENCE.md
+-- Observe tool calls (logging, metrics) -> plugins/REFERENCE.md
+-- Intercept lifecycle events -> plugins/REFERENCE.md
+-- Add system prompt rules -> plugins/REFERENCE.md
+-- Distribute via npm/git -> plugins/REFERENCE.md

Multi-agent?
+-- Spawn one-off background agents -> multi-agent/REFERENCE.md (sub-agents)
+-- Persistent cross-session teams -> multi-agent/REFERENCE.md (teams)
+-- Parent-child delegation -> multi-agent/REFERENCE.md (sub-agents)
+-- Peer-to-peer task board -> multi-agent/REFERENCE.md (teams)

Scheduling?
+-- Recurring cron jobs -> scheduling/REFERENCE.md
+-- One-off scheduled tasks -> scheduling/REFERENCE.md
+-- Event-driven triggers -> scheduling/REFERENCE.md
+-- CLI schedule management -> scheduling/REFERENCE.md

Production?
+-- Error handling and status checks -> production/REFERENCE.md
+-- Cost control and token limits -> production/REFERENCE.md
+-- Observability (OpenTelemetry) -> production/REFERENCE.md
+-- Security and sandboxing -> production/REFERENCE.md
+-- Deployment patterns -> production/REFERENCE.md

© cline, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 18 other files (references) in .agents/skills/cline-sdk of cline/cline.

• SKILL.md
• references/agent/REFERENCE.md
• references/agent/api.md
• references/agent/gotchas.md
• references/agent/patterns.md
• references/clinecore/REFERENCE.md
• references/clinecore/api.md
• references/clinecore/gotchas.md
• references/clinecore/patterns.md
• references/events/REFERENCE.md
• references/multi-agent/REFERENCE.md
• references/plugins/REFERENCE.md
• references/production/REFERENCE.md
• references/providers
• … and 5 more

Open the folder on GitHubat commit fa840c7