sdk/README.md
The Cline SDK is a TypeScript framework for building AI agents that can edit files, run shell commands, browse the web, call APIs, and use any custom tool you give them. It's the same engine that powers Cline, packaged as a library you can embed in your own applications.
import { Agent } from "@cline/sdk"
const agent = new Agent({
providerId: "cline",
modelId: "openai/gpt-5.5",
systemPrompt: "You are a helpful coding assistant.",
tools: [],
})
const result = await agent.run("Create a REST API with Express and TypeScript")
console.log(result.text)
That's it. The agent streams its response, calls tools if you give it any, and returns when the task is done.
npm install @cline/sdk
If you use a coding agent (Claude Code, Codex, Cline, etc.), install the Cline SDK skill to give your agent context on the SDK's APIs and best practices to help you build with the Cline SDK.
npx skills add cline/sdk-skill
Prompt it to scaffold agents, create custom tools, wire up plugins, configure providers, and more.
Coding agents, Slack bots, scheduled automations, code review pipelines, multi-agent teams, IDE integrations -- anything that benefits from an LLM that can take actions, not just generate text.
// Slack bot: each thread gets its own agent with conversation memory
const agents = new Map<string, Agent>()
async function handleMessage(threadId: string, message: string) {
let agent = agents.get(threadId)
if (!agent) {
agent = new Agent({
providerId: "gemini",
modelId: "gemini-3.1-pro-preview",
systemPrompt: "You are a concise Slack assistant.",
tools: [],
})
agents.set(threadId, agent)
}
const result = agent.hasRun
? await agent.continue(message)
: await agent.run(message)
return result.text
}
Explore full working examples in examples/ and app examples in apps/examples/:
| Example | Description |
|---|---|
| Plugins | Custom tools with workspace-aware context, lifecycle hooks, and branch-level safety policies |
| Subagent Orchestration | Spawn and manage background agents with presets, skills, and cross-agent handoffs |
| Hooks | File-based and runtime hooks for logging, review gates, context injection, and lifecycle automation |
| Cron Automations | Recurring and event-driven automation specs for scheduled quality checks and PR workflows |
| Desktop App | Tauri desktop shell with a Bun sidecar backend and Next.js UI |
| VS Code Extension App | VS Code extension example that runs Cline sessions over the RPC runtime |
Tools are how agents interact with the world. Define a tool with a name, a description the model reads, a JSON Schema for inputs, and a function that does the work:
import { createTool } from "@cline/sdk"
const deploy = createTool({
name: "deploy",
description: "Deploy the app to staging or production.",
inputSchema: {
type: "object",
properties: {
environment: { type: "string", enum: ["staging", "production"] },
},
required: ["environment"],
},
execute: async (input) => {
const result = await runDeployment(input.environment)
return { url: result.url, status: "success" }
},
})
const agent = new Agent({
providerId: "moonshot",
modelId: "kimi-k2.5",
systemPrompt: "You are a deployment assistant.",
tools: [deploy],
})
The agent decides when to call the tool based on the description. It sees the result and incorporates it into its response.
Every event during execution is observable in real time:
const agent = new Agent({
providerId: "anthropic",
modelId: "claude-opus-4-7",
systemPrompt: "You are a helpful assistant.",
tools: [myTool],
onEvent: (event) => {
switch (event.type) {
case "content_update":
if (event.contentType === "text") process.stdout.write(event.text)
break
case "content_start":
if (event.contentType === "tool") console.log(`\n[${event.toolName}]`)
break
case "usage":
console.log(`\ntokens: ${event.inputTokens} in, ${event.outputTokens} out`)
break
}
},
})
Package reusable capabilities as extensions. An extension can register tools, observe lifecycle events, and modify agent behavior:
const metrics: AgentPlugin = {
name: "metrics",
manifest: { capabilities: ["tools", "hooks"] },
setup(api) {
api.registerTool(myCustomTool)
},
hooks: {
beforeRun() {
console.time("agent")
},
beforeTool({ toolCall }) {
console.log(`tool: ${toolCall.toolName}`)
},
afterRun({ result }) {
console.timeEnd("agent")
console.log(`${result.iterations} iterations, ${result.usage.outputTokens} tokens`)
},
},
}
When you need session persistence, built-in tools, config discovery, and multi-process support, use ClineCore:
import { ClineCore } from "@cline/sdk"
const cline = await ClineCore.create({ clientName: "my-app" })
const session = await cline.start({
prompt: "Set up CI with GitHub Actions",
config: {
providerId: "anthropic",
modelId: "claude-sonnet-4-6",
apiKey: process.env.ANTHROPIC_API_KEY,
cwd: "/path/to/project",
enableTools: true,
},
})
console.log(session.result?.text)
ClineCore gives the agent built-in tools (bash, editor, read_files, apply_patch, search, fetch_web), persists sessions to SQLite, discovers config from .cline/ directories, and optionally connects to an RPC sidecar for scheduled agents and cross-process session management.
The SDK is a layered stack. Use as much or as little as you need:
| Package | What it does |
|---|---|
@cline/sdk | Everything you need -- install this one |
@cline/core | Sessions, persistence, built-in tools, config discovery, RPC |
@cline/agents | Stateless agent loop with tool execution and streaming |
@cline/llms | LLM provider gateway (Anthropic, OpenAI, Google, Bedrock, Mistral, and more) |
@cline/shared | Types, tool creation helpers, hook engine |
@cline/sdk is an alias for @cline/core that re-exports from all packages, so a single install gives you the full API. The individual packages are available if you want a minimal dependency footprint.
The Cline CLI gives you terminal access to the full SDK:
# Interactive agent
cline
# Single prompt
cline "Refactor the auth module to use JWT"
# Schedule an agent to run daily
cline schedule create "PR summary" --cron "0 9 * * MON-FRI" --prompt "Summarize open PRs"
# Connect a Telegram bot created with @BotFather
cline connect telegram -m my_bot -k "$TELEGRAM_BOT_TOKEN"
# Then send /help or /start to the bot in Telegram
For Telegram-specific connector behavior, see apps/cli/src/connectors/adapters/telegram.md.
Works with every major LLM provider out of the box:
| Provider | Models |
|---|---|
| Anthropic | Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 |
| OpenAI | GPT-5.5, GPT-5.3 Codex |
| Gemini 3.1 Pro Preview, Gemini 3 Flash Preview | |
| AWS Bedrock | Claude, Llama |
| Mistral | Mistral Large, Codestral |
| Any OpenAI-compatible | vLLM, Together, Fireworks, Groq, etc. |
Full documentation at docs.cline.bot/sdk:
To contribute to the project, start with our Contributing Guide to learn the basics. You can also join our Discord to chat with other contributors in the #contributors channel. If you're looking for full-time work, check out our open positions on our careers page!