Guide intermediate

Cline SDK: Run Your First Coding Agent in TypeScript (May 2026)

Published May 17, 2026 · by Pondero Editorial

The short version

Cline released @cline/sdk on May 13, 2026 - an open-source TypeScript runtime for building coding agents with native CRON, checkpointing, multi-agent teams, and MCP connectors. This guide covers the four-package architecture, a nightly audit agent walkthrough, and how to choose between Cline SDK and LangChain.js.

Table of Contents

Cline SDK: Run Your First Coding Agent in TypeScript (May 2026)

On May 13, 2026, the Cline team extracted the agent harness that powers their VS Code extension and CLI into a standalone TypeScript package: @cline/sdk. The runtime that 7 million developers already run inside their editors is now something any team can npm install and wire into their own product. CRON scheduling, checkpointing, multi-agent teams, and MCP connectors all ship out of the box. You get the full execution harness, not a thin wrapper around an LLM API.

This guide covers the five-package architecture, walks through a nightly audit agent, and lays out where Cline SDK beats LangChain.js and where it doesn't. We assume you know what Cline is and want to understand the architecture before building on it.

What the Cline SDK is and why it exists now

From embedded harness to open runtime

The Cline extension always had a sophisticated agent loop underneath the VS Code UI. It handled tool calling, multi-step reasoning, session persistence, and context management. For years that loop was tightly coupled to the editor surface. The @cline/sdk release cuts that coupling. Per the official announcement, the team refactored the internals into a layered TypeScript stack that runs in Lambda, a Cloudflare Worker, or a long-running Node process on a VPS.

You're not building an agent framework. You're building on top of one that's already battle-tested at scale.

Who the SDK is for

If you're on a team that needs to automate a coding-adjacent workflow (repo audits, PR triage, test generation, dependency scanning), the SDK gives you a production-grade execution loop without the orchestration tax. You configure a provider, define a task, and the agent runs it.

Teams doing non-coding automation, complex RAG pipelines, or multi-modal document processing will find the tool primitives are scoped to coding. LangChain.js fits those cases better. We cover that comparison in detail below.

The 7-million-user baseline

The Cline GitHub repository has over 61,900 stars and ships under Apache 2.0. The SDK inherits the same license. That matters for teams evaluating open-source dependencies at the legal layer.

Installing and configuring @cline/sdk

Prerequisites

Node.js 22 or later. The SDK uses top-level await and some Node 22 runtime APIs, so older Node versions won't work.

npm install - what you get

npm install @cline/sdk

That single install pulls in the full runtime: provider routing, tool execution, session management, checkpointing, and the agent loop. The @cline/sdk package re-exports @cline/core, so you don't need to manage sub-package versions separately for most projects.

Provider setup (Anthropic, OpenAI, LiteLLM)

The SDK ships support for Anthropic, OpenAI, Google, AWS Bedrock, Mistral, and LiteLLM (which in turn covers vLLM, Together, Fireworks, and any OpenAI-compatible endpoint). Set your API key as an environment variable - no config files required for the common case.

For a custom provider, register a handler through @cline/llms before instantiating an agent:

import { llms } from "@cline/sdk"

llms.registerHandler("my-provider", handler)

Running a stateless hello-world session

The example below comes directly from the official SDK docs. It's the minimum viable agent: one provider, one task, one iteration.

import { Agent } from "@cline/sdk"

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxIterations: 1,
})

const result = await agent.run("List all TypeScript files in ./src with more than 100 lines.")

maxIterations: 1 makes this stateless - one pass, no continuation. The task is a natural-language instruction; the SDK's tool layer translates it into filesystem calls. No manual tool wiring.

For streaming output, attach a subscriber before calling run:

agent.subscribe((event) => {
  if (event.type === "assistant-text-delta") {
    process.stdout.write(event.text ?? "")
  }
})

Building a nightly audit agent

What the agent does

This agent scans a repository for open issues on a schedule, checkpoints progress so a restart picks up where it left off, and posts findings to a Slack channel via an MCP connector. The same pattern works for dependency scanning, test coverage drift, or PR backlog management.

import { Agent } from "@cline/sdk"

const auditAgent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  checkpointEnabled: true,
  plugins: [slackMcpPlugin],
})

await auditAgent.run(
  "Scan the ./src directory for TODO comments and files with cyclomatic complexity above 10. " +
  "Group findings by severity and post a summary to the #eng-audit Slack channel."
)

The checkpointEnabled: true flag tells @cline/core to persist agent state between iterations. If the run fails mid-task, the next invocation resumes from the last successful checkpoint.

Adding CRON scheduling

@cline/core ships a scheduler. Register the audit agent as a CRON job with a standard cron expression:

import { schedule } from "@cline/core"

schedule("0 2 * * *", async () => {
  await auditAgent.run(
    "Run the nightly repo audit and post findings to #eng-audit."
  )
})

The "0 2 * * *" expression runs the job at 2 AM every day. The scheduler respects checkpoints, so if the previous night's run was interrupted and a checkpoint exists, the next scheduled invocation resumes from that checkpoint first.

Checkpointing

Checkpointing is a first-class primitive in @cline/core, not a plugin. When checkpointEnabled is true, the agent persists its tool-call history, context window state, and progress markers to disk after each iteration. The checkpoint path defaults to .cline/checkpoints/<agent-id>/ and is configurable.

For long-running audit jobs, this prevents the worst failure mode: an agent that completes most of a large repo scan, hits a provider error, and starts over from file one.

Wiring the Slack connector

MCP connectors plug into the agent as tool sources. The Slack MCP server exposes posting as a tool the agent can call in its natural reasoning flow.

import { Agent, McpConnector } from "@cline/sdk"

const slackMcpPlugin = new McpConnector({
  server: "npx",
  args: ["-y", "@modelcontextprotocol/server-slack"],
  env: {
    SLACK_BOT_TOKEN: process.env.SLACK_BOT_TOKEN,
    SLACK_TEAM_ID: process.env.SLACK_TEAM_ID,
  },
})

const auditAgent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  checkpointEnabled: true,
  plugins: [slackMcpPlugin],
})

The agent doesn't need explicit instructions to "use Slack" - the MCP connector registers the post-message tool in the agent's tool set, and the model routes to it when the task calls for a Slack notification. See our MCP overview if this connector pattern is new to you.

The four-package architecture

The SDK is a layered stack. You'll mostly interact with @cline/sdk, but understanding what sits underneath helps when you need to go off the standard path.

@cline/shared

Types, schemas, tool helpers, hooks, and storage helpers. The shared foundation that the other packages build on. You rarely import this directly in application code - it's the type layer that makes the other packages coherent.

@cline/llms

The provider gateway and model catalogs. This package handles authentication, request formatting, streaming, and retry logic for Anthropic, OpenAI, Google, AWS Bedrock, Mistral, and LiteLLM. You can use @cline/llms standalone for serverless LLM routing without pulling in the full agent runtime.

import { llms } from "@cline/llms"

const response = await llms.complete({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  prompt: "Write a one-line summary of this diff.",
})

This is the right layer to reach for when you need multi-provider routing in a Cloudflare Worker or Lambda without the rest of the agent machinery.

@cline/agents

The browser-compatible stateless agent execution loop. No file system access, no persistence, no sessions. Give it a system prompt, a task, and a tool set; it executes one pass of the agent loop and returns. Runs in Lambda, Cloudflare Worker, Deno Deploy, or the browser. The stateless loop has no Node.js dependencies, which is what makes it portable.

@cline/core

The Node runtime layer. Sessions, persistence, the scheduler, hub support, and automation primitives. @cline/core wraps @cline/agents with a session manager, a checkpoint store, and the CRON scheduler. Node.js 22+ required; won't run in a browser or Worker.

@cline/sdk (full)

The public SDK surface. Re-exports @cline/core plus a stable versioned API. Use this when building a product on top of the runtime. It's the right import for most projects - you get the full stack and don't need to track sub-package compatibility.

Native multi-agent teams and MCP connectors

Spawning a subagent

An orchestrator agent can spawn subagents and pass them tasks. The handoff is a typed message, not a string. The parent agent waits for the subagent result before continuing its own reasoning loop.

import { Agent, SubAgent } from "@cline/sdk"

const orchestrator = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxIterations: 5,
})

// Within the agent's tool configuration, register a subagent spawner
const subagent = new SubAgent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  task: "Analyze the test coverage report at ./coverage/lcov.info and return a list of uncovered functions.",
})

const coverage = await subagent.run()

The orchestrator can spawn multiple subagents in parallel for independent subtasks. Useful for repo audits where you want separate agents scanning different directories concurrently, then aggregate results.

Handoff notes

Subagents receive structured context from the parent: what's been done, the subagent's scope, and the expected output format. This prevents the subagent from re-reading all parent context.

const subagent = new SubAgent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  task: "Scan ./src/auth for security issues.",
  handoffNotes: {
    parentProgress: "Main audit is 40% complete. Auth module not yet scanned.",
    expectedOutputFormat: "JSON array of { file, line, severity, description }",
    contextFiles: ["./src/auth/index.ts", "./src/auth/middleware.ts"],
  },
})

Connecting an MCP server

Any MCP server - not just Slack - plugs in as a McpConnector. The agent gets that server's tools in its tool set at runtime. For coding agents, useful MCP servers include GitHub (PR creation, issue reading), Linear (ticket management), and database connectors for querying schema information.

See the full MCP overview and the AI agent fundamentals pages for context on how MCP fits into the broader agent architecture.

Cline SDK vs. LangChain.js

Where Cline SDK wins

Cline SDK is the better choice when your agent is doing coding work. CRON scheduling, checkpointing, MCP connectors, and multi-agent teams all ship with npm install @cline/sdk. You configure what you need; you don't assemble an orchestration layer from primitives.

The announcement includes a specific number: claude-opus-4.7 on the Cline runtime scored 74.2% on Terminal Benchmark. For teams choosing a runtime for coding automation, that's the relevant signal.

The SDK also inherits 7 million users worth of edge case handling. Tool call failure recovery, context window management, and retry logic have been stress-tested in the VS Code extension for years.

Where LangChain.js wins

LangChain.js is a better fit when your automation spans domains outside of coding. Financial RAG pipelines, document processing workflows, custom retrieval strategies - these need compositional flexibility that LangChain's chain primitives provide. You build the orchestration layer yourself, but you get more control over the data flow.

LangChain also has broader community integrations for non-coding tool sources (vector databases, document loaders, output parsers). If your agent needs to pull from a custom knowledge base and route through specialized retrievers, LangChain is the right fit.

Cline SDK's tools are scoped to coding contexts. Forcing it into a document summarization pipeline is working against the grain.

The middle path

For teams building products that blend retrieval and code execution, the two aren't mutually exclusive. Use LangChain for the retrieval and chunking layer, then hand the retrieved context to a Cline SDK agent as the execution layer. LangChain's retriever produces the relevant files or code snippets; the Cline SDK agent acts on them.

This pattern also applies if you already have a LangChain.js pipeline you don't want to rewrite. Drop the Cline SDK in as the execution component for the coding tasks specifically. The SDK's @cline/agents stateless loop is small enough to slot into an existing chain without pulling in session management overhead.

See also: Cline vs. Cursor and AI coding tools for non-coders.

Deploying the agent

Local development

For local work, run the agent directly with tsx or compile to CommonJS with tsc. The CRON scheduler runs in-process, so a persistent local process will execute scheduled jobs.

npm install -D tsx
npx tsx src/audit-agent.ts

The agent writes checkpoints to .cline/checkpoints/ relative to the working directory. Add that path to .gitignore.

VPS deployment

For a nightly agent that needs to stay running, a VPS is the right deployment target. Cloudways and DigitalOcean both work well here. The agent process is a long-running Node.js app - pm2 handles process management and restarts on crash.

npm install -g pm2
pm2 start dist/audit-agent.js --name "nightly-audit"
pm2 save
pm2 startup

The pm2 startup command generates a systemd unit so the process restarts on reboot. Combined with checkpointEnabled: true, you get a nightly audit that survives both process crashes and server reboots.

Compute requirements

The agent process itself is lightweight - the cost is in LLM API calls and tool calls (file reads, process spawns). For a repo audit on a medium-sized TypeScript codebase (50,000-100,000 lines), 1 GB RAM is sufficient. Running an orchestrator plus subagents concurrently, use 2 GB. The bottleneck in practice is API rate limits, not compute.

FAQ

Does @cline/sdk work with any LLM, or just the listed providers?

Any OpenAI-compatible endpoint works via LiteLLM: Ollama, vLLM, LM Studio, Together, Fireworks. Register a custom provider via llms.registerHandler for anything outside the LiteLLM umbrella.

Can I use @cline/agents in a Cloudflare Worker?

Yes. The @cline/agents package is browser-compatible with no Node.js dependencies. Import from @cline/agents directly to avoid pulling in the Node-dependent @cline/core.

What's the minimum Node version?

Node.js 22 for @cline/core. If you need to run in a Worker or Lambda, use @cline/agents directly - no Node version constraint there.

Is the SDK production-ready?

Released May 13, 2026. The underlying runtime has been in the Cline extension for the full 7-million-user install base. The SDK packaging is new; the execution logic is not. Start with non-critical automation, then graduate to production workflows.

Does the license allow commercial use?

Apache 2.0, as confirmed in the Cline repository. Commercially permissive. Attribution is required; you cannot claim the Cline name as your own.

How does checkpointing interact with the CRON scheduler?

On each scheduled run, @cline/core checks for an existing checkpoint for that agent ID. A checkpoint found means the agent resumes mid-task rather than starting fresh. A failed midnight run that checkpointed at 60% picks up at that point on the next scheduled execution.