Related Pages

Related topics: Product Comparison and Use Cases, Hub-Spoke Architecture

Introduction to Cline

Cline is an autonomous AI coding agent capable of creating and editing files, running terminal commands, using browsers, and integrating with Model Context Protocol (MCP) servers. The project enables AI-assisted software development by providing a unified agent runtime that works across multiple IDEs and interfaces.

Overview

Cline functions as an intelligent coding assistant that reads your project structure, understands file relationships, and makes coordinated changes across your codebase. As it works, it monitors linter and compiler output in real time, automatically fixing issues like missing imports, type mismatches, and syntax errors before you see them.

The core agent technology is shared across multiple surfaces:

Source: README.md

Core Capabilities

Autonomous Code Editing

Cline reads your project structure and understands relationships between files. It makes coordinated changes across your entire codebase while monitoring linter and compiler errors in real time. In VS Code and JetBrains, every edit appears as a diff you can review, modify, or revert. All changes are tracked with checkpoints, enabling easy rollback.

Terminal Command Execution

Cline executes commands directly in your terminal and watches output in real time. You can use it to install packages, run build scripts, execute tests, deploy applications, and manage databases. Long-running processes like development servers are supported with proper output streaming.

Multi-Provider Support

Cline supports a wide range of AI providers and models:

• Direct API providers: Anthropic, OpenAI, Google Gemini, AWS Bedrock, GCP Vertex, Cerebras, Groq
• Aggregators: OpenRouter
• Custom endpoints: Any OpenAI-compatible API endpoint
• Special integrations: ChatGPT Subscription via openai-codex, LM Studio

Recent additions include support for Claude Opus 4.7, GPT-5.5 for OpenAI Codex subscription users, SAP AI Core, Z AI, and Azure Blob Storage as a storage provider.

Source: sdk/apps/cli/README.md

MCP Server Integration

Cline supports the Model Context Protocol, allowing integration with external tools and services. Users can add MCP servers from the Cline marketplace, and the community has requested quality validation for MCP servers through integrations like Clarvia AEO scoring.

Source: Community Issues #10068

Architecture

The Cline SDK is organized into four primary packages that build upon each other:

graph TD
    A["@cline/llms<br/>Model Catalog + Provider Settings"] --> B["@cline/agents<br/>Agent Runtime Loop"]
    B --> C["@cline/core<br/>Runtime Orchestration + Sessions"]
    C --> D["CLI / Desktop Apps"]
    A --> D
    B --> D
    E["@cline/shared<br/>Shared Primitives"] --> A
    E --> B
    E --> C

Package Responsibilities

Source: sdk/packages/README.md

SDK Packages Detail

#### @cline/llms

The model and provider layer providing typed provider settings, model catalogs, shared gateway contracts, and AI SDK-backed handler creation for supported LLM backends. Key exports include:

• createHandler() - Creates a handler for a specific provider and model
• createLlmsRuntime() - Creates a small registry with configured providers and builtin provider discovery
• registerBuiltinProvider() - Registers custom providers

import { createHandler } from "@cline/llms";

const handler = createHandler({
    providerId: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY ?? "",
    modelId: "claude-sonnet-4-6",
});

Source: sdk/packages/llms/README.md

#### @cline/agents

The stateless agent runtime loop that handles tool execution, hooks, extensions, and streaming. This package manages the core agent logic independent of any specific interface.

#### @cline/core

The stateful runtime orchestration layer that handles session lifecycle, storage, and local or hub-backed runtime services. Key responsibilities include:

• ClineCore.create() - App-facing session API
• Built-in host tools and executors via createBuiltinTools(), createDefaultTools(), createDefaultExecutors()
• Storage and settings helpers like ProviderSettingsManager and CoreSettingsService
• MCP settings helpers

Source: sdk/packages/core/README.md

#### @cline/shared

Cross-package shared primitives including path resolution utilities, session common types, and indexing helpers. Exported subpaths include .browser, .types, .storage, .db, .automation, and .remote-config.

Source: sdk/packages/shared/package.json

Command Line Interface

The Cline CLI (version 3.0.15) provides terminal-based access to the agent capabilities:

npm install -g cline

For nightly builds:

npm install -g cline@nightly

Platform binaries are published for macOS, Linux, and Windows on arm64 and x64, requiring no runtime dependency at install time.

CLI Usage Modes

Source: sdk/apps/cli/README.md

Authentication

cline auth                              # Interactive auth setup
cline auth add openai                   # Add specific provider
cline models                            # List available models

Plugins System

Cline supports plugins that extend the CLI and SDK with custom capabilities. Plugins can register custom tools, hook into agent lifecycle events, and export reusable modules.

Plugin Installation

cline plugin install <source>

Supported sources:

• Local files
• GitHub file URLs
• Package directories
• Git repositories
• npm packages

Example Plugins

The TypeScript LSP plugin demonstrates advanced plugin capabilities: it uses the TypeScript Language Service API to resolve symbol definitions through imports, re-exports, and type aliases—much more precise than text search.

Source: sdk/examples/plugins/README.md

Hooks and Automation

Hooks

Hooks allow you to intercept and respond to agent lifecycle events. They can modify prompts, handle tool results, manage notifications, and more. Cline removed example hooks in v3.75.0 in favor of documentation-based guidance.

Source: Community: v3.75.0 Release

Cron Automation

Cline automation supports two types of specs:

1. Recurring specs (.cron.md) — Run on a schedule using cron syntax
2. Event-driven specs (.event.md) — Run when specific events occur

Example recurring spec configuration:

schedule: "0 9 * * MON-FRI"      # 9 AM on weekdays
tools: [run_commands, read_files]
mode: act                         # Execute commands
timeoutSeconds: 1800             # 30-minute timeout

Automation specs are stored in ~/.cline/cron/ and automatically reconciled on startup.

Source: sdk/examples/cron/README.md

Advanced Features

Kanban

Cline includes a Kanban feature for multi-agent task management. The CLI launches Kanban by default with a migration view, and the feature is also available in the VS Code extension via a launch modal.

Source: Community: v3.76.0 Release

Subagents

Cline supports spawning background subagents with their own models and personalities. The agents-squad plugin demonstrates multi-agent team orchestration with tools like:

• start_subagent - Start a background subagent
• message_subagent - Send messages to subagents
• get_subagent - Retrieve subagent state
• list_agent_presets - List available agent configurations

Pre-configured agent presets include Anvil (build/compile), Inquisitor (investigation), Oracle (planning), and Phantom (stealth/optimization).

Enterprise Features

Recent versions add enterprise capabilities:

• Remote globalSkills - Enterprise-managed skills appear under a dedicated "Enterprise Skills" section with alwaysEnabled enforcement
• Global AGENTS rules - Agent rules applied across all sessions, not just per-project
• Dynamic model fetching - Onboarding uses dynamically fetched recommended models instead of hardcoded lists

Source: Community: v3.80.0 Release

SDK Examples

The SDK includes practical examples ordered from beginner to advanced:

Running Examples

cd sdk/apps/examples/<example-name>
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev

Requires Node.js 22+.

Source: sdk/apps/examples/README.md

Known Limitations and Community Concerns

Active Community Issues

Context Window Issues

Users have reported that LM Studio does not report correct context size for models in chat. When using LM Studio as an API provider, context window information may not be accurately displayed.

Source: Community Issue #11158

MCP Server Logging

Some MCP servers return errors via stderr, but Cline does not currently expose these logs to users. The community has requested the ability to view MCP server console output for debugging purposes.

Source: Community Issue #1959

Licensing

Cline is licensed under Apache 2.0, which allows commercial use and does not require contractual obligations. However, users have noted unclear separation between the open source license and service terms, particularly regarding content rights requirements.

Source: LICENSE

Getting Started

1. Install the CLI: npm install -g cline
2. Configure authentication: cline auth
3. Add providers: cline auth add <provider-name>
4. Start coding: cline for interactive mode or cline "<task>" for single commands

For VS Code: Install from the Visual Studio Marketplace

For SDK development: See the SDK Documentation for end-to-end tutorials and the Architecture Overview for structural details.

Source: sdk/README.md

Related Pages

Related topics: Introduction to Cline, Provider System and Model Adapters

Quick Start Guide

Overview

Cline is an open-source autonomous coding agent available across multiple platforms: VS Code, JetBrains IDEs, and a CLI. It can create and edit files, run commands, use browsers, and interact with MCP servers for extended capabilities.

This guide covers installation, initial configuration, and first steps for all Cline distributions. Choose your platform below or follow the SDK quick start to build custom agents programmatically.

Installation

CLI Installation

Install Cline globally via npm:

npm i -g cline

Verify the installation:

cline --version

The CLI requires Node.js 22 or later and supports interactive chat or fully headless operation for CI/CD and scripting. Source: README.md:1

VS Code Extension

Install from the VS Code Marketplace or search "Cline" in the Extensions view (Ctrl+Shift+X). The extension runs entirely within VS Code with no external dependencies. Source: README.md:1

JetBrains Plugin

Install from the JetBrains Marketplace for support across IntelliJ IDEA, PyCharm, WebStorm, GoLand, and other JetBrains family IDEs. Source: README.md:1

Initial Configuration

API Provider Setup

Cline requires an API provider to power its agent capabilities. On first launch, you'll be prompted to configure one. The supported providers include:

The onboarding flow dynamically fetches recommended models instead of using a hardcoded list, allowing access to the latest available models. Source: sdk/README.md:1

SDK Quick Start

For programmatic usage, install the Cline SDK:

npm install @cline/sdk

The SDK requires Node.js 22 or later. Source: sdk/packages/core/package.json:1

#### Your First Agent

Create a simple agent that streams a response:

import { Agent } from "@cline/sdk";

const agent = new Agent({
  model: "anthropic/claude-sonnet-4",
  apiProvider: "openrouter", // or your configured provider
});

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

await agent.run("Explain what autonomous agents are in 2 sentences.");

This minimal example demonstrates the core Agent class, event subscription via subscribe(), and the async run() method. Source: sdk/apps/examples/README.md:1

CLI Usage Modes

The CLI supports multiple operation modes:

Interactive Mode

Run without arguments to enter interactive chat:

cline

Single Task Mode

Pass your task as an argument:

cline -i "Fix the authentication bug in src/auth/login.ts"

Headless/Yolo Mode

For CI/CD and automation, use yolo mode to skip approval prompts:

cline -i "Run the test suite and report results" -y

Background Dispatch

Dispatch a task to the background hub and exit immediately:

cline -i "Refactor the database layer" -z

Source: sdk/apps/cli/README.md:1

CLI Command Reference

Source: sdk/apps/cli/README.md:1

SDK Examples

The SDK includes runnable examples demonstrating progressively advanced concepts. All examples require Node.js 22+ and use Bun for builds:

cd apps/examples/<example-name>
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev

Beginner Examples

Intermediate Examples

Advanced Examples

Source: sdk/apps/examples/README.md:1 and sdk/examples/README.md:1

Package Architecture

Understanding the SDK's package structure helps when building custom integrations:

Source: sdk/packages/README.md:1

Workflow: Interactive Code Review

For a complete working example, the code review bot demonstrates real-world SDK usage:

1. Paste a GitHub PR URL into the dashboard
2. The app fetches metadata, changed files, patches, and check status
3. An agent streams a review over the real PR diff
4. Reviewers can copy findings or post a summary comment back to GitHub

export CLINE_API_KEY="cline_..."
export GITHUB_TOKEN="github_pat_..."  # Optional for public PRs
export ENABLE_GITHUB_REVIEW_POSTING=1  # Enable GitHub comment posting
cd sdk/apps/examples/code-review-bot
bun install && bun run build:sdk
bun dev

Open http://localhost:3457 to use the dashboard. Source: sdk/apps/examples/code-review-bot/README.md:1

Next Steps

• VS Code/JetBrains Users: Explore the built-in tools panel, MCP server integration, and skill management in the UI
• CLI Users: Run cline --help for all available flags and cline --kanban to launch the Kanban task board
• SDK Developers: Install the Cline SDK skill to give your coding agent context on SDK APIs and best practices
• Automation: Set up cron jobs and event-driven automations for recurring tasks or PR-triggered workflows

Troubleshooting

For additional help, join the Discord community or check the GitHub Discussions.

Related Pages

Related topics: Introduction to Cline

Product Comparison and Use Cases

Overview

Cline provides a unified coding agent experience across multiple delivery platforms: IDE extensions, command-line interface, and a software development kit for custom integrations. All products share the same underlying agent runtime, tool ecosystem, and model provider infrastructure, while offering distinct interaction paradigms suited to different workflows. Source: README.md

Product Portfolio

Cline's product family consists of four primary offerings, each designed for specific user scenarios and deployment contexts.

Source: README.md:1-50

Feature Comparison

Core Capabilities Matrix

Source: sdk/packages/README.md:1-20

Context Management Features

These fields are defined in the model catalog and should not be treated as additive guarantees. For example, a catalog entry with contextWindow: 200000, maxInputTokens: 200000, and maxTokens: 128000 means the prompt may approach 200,000 tokens while the model can generate up to 128,000 tokens—but an individual request must still fit within provider rules. Source: sdk/packages/llms/src/catalog/README.md:1-35

VS Code Extension

Use Cases

The VS Code Extension targets individual developers working in their primary coding environment. It provides seamless integration with the editor, allowing agents to read files, propose edits, and run commands without context-switching.

Ideal for:

• Solo development sessions with complex refactoring tasks
• Code reviews and bug investigation within the IDE
• Learning unfamiliar codebases with interactive exploration
• Quick prototyping and iterative development

Key Features

The extension supports VS Code foreground terminal restoration and settings preservation in version 3.82.0. It provides dedicated UI elements for enterprise-managed skills appearing under an "Enterprise Skills" section with alwaysEnabled enforcement. Source: community_context/v3.82.0

JetBrains Plugin

Use Cases

The JetBrains Plugin serves developers in the JetBrains ecosystem, including IntelliJ IDEA, PyCharm, WebStorm, GoLand, and the full JetBrains family. Installation is available through the JetBrains Marketplace.

Ideal for:

• Teams already invested in JetBrains tooling
• Python developers (PyCharm) requiring deep language support
• Multi-language projects requiring IDE-specific features
• Enterprise environments with JetBrains license management

Installation

The plugin installs directly from the JetBrains Marketplace, providing the same core functionality as the VS Code extension within the JetBrains interface. Source: README.md:1-50

CLI

Use Cases

The CLI offers terminal-based interaction with two operational modes: interactive chat for human-driven sessions and fully headless execution for automation and scripting.

Interactive mode suits developers who prefer terminal workflows or need remote server access. Headless mode enables CI/CD pipelines, automated testing, and scheduled task execution.

Ideal for:

• CI/CD pipeline integration and automation scripts
• Remote server development without GUI dependencies
• Batch processing multiple files or projects
• Integration with existing shell-based workflows

Command Options

Source: sdk/apps/cli/README.md:1-80

Headless Execution Patterns

graph LR
    A[CI/CD Trigger] --> B[CLI Invocation]
    B --> C{Mode?}
    C -->|Yolo| D[Execute with auto-approve]
    C -->|Zen| E[Dispatch to Hub]
    C -->|Standard| F[Interactive with approval]
    D --> G[Tool Execution]
    E --> H[Background Processing]
    F --> G
    G --> I[Result Output]

Headless mode is particularly valuable for automation scenarios where human approval is impractical. The -y flag enables submit_and_exit mode, allowing scripts to dispatch tasks and retrieve results without waiting. Source: sdk/apps/cli/README.md:1-80

SDK

Use Cases

The SDK provides programmatic access to Cline's agent runtime for teams building custom tools, integrations, and automated workflows. It exposes the same engine powering the CLI, IDE extensions, and Kanban application.

Ideal for:

• Building custom agent-powered applications
• Integrating coding agents into existing platforms
• Multi-agent orchestration for complex workflows
• Enterprise automation with custom tool requirements

Package Architecture

Source: sdk/packages/README.md:1-25

Package Interaction Flow

graph TD
    A[Application] --> B[@cline/core]
    B --> C[@cline/agents]
    C --> D[@cline/llms]
    C --> E[@cline/shared]
    D --> E
    F[Model Providers] --> D
    G[Tool Execution] --> C
    H[Hub Services] --> B

The @cline/llms package defines model and provider capabilities while building concrete request handlers. The @cline/agents package runs the agent loop using those handlers and tool execution primitives. The @cline/core package composes runtime behavior with persistent sessions and local or hub-backed services. Source: sdk/packages/README.md:1-25

Example Applications

Code Review Bot

A production-ready application demonstrating PR analysis with the SDK. It fetches real GitHub pull requests, renders diffs in a dashboard, and streams agent-powered reviews.

Capabilities demonstrated:

• GitHub API integration for PR metadata and diffs
• Real-time streaming of agent responses
• Structured finding generation with add_review_finding
• Optional review posting back to GitHub

Source: sdk/apps/examples/code-review-bot/README.md:1-40

Multi-Agent War Room

An example application spawning four specialist agents in parallel, streaming responses via SSE, then synthesizing findings into a unified decision brief.

Agent roles:

Source: sdk/apps/examples/multi-agent/README.md:1-50

Choosing the Right Product

Decision Framework

graph TD
    A[Use Case Assessment] --> B{Team Size?}
    B -->|Individual| C{Interface Preference?}
    C -->|IDE Integration| D[VS Code or JetBrains]
    C -->|Terminal| E[CLI Interactive]
    B -->|Team| F{Automation Needs?}
    F -->|Basic| G[CLI + Hub]
    F -->|Complex| H[SDK Custom Build]
    B -->|Enterprise| I{Custom Integration?}
    I -->|Yes| H
    I -->|No| J[Hub with Global Rules]

Scenario Recommendations

Version Considerations

Recent releases have enhanced specific products:

• v3.82.0: VS Code foreground terminal support and settings restoration
• v3.80.0: Enterprise remote config with globalSkills UI
• v3.76.0: Kanban integration, CLI spawn fixes for Windows
• v3.0.15 CLI: Hub web app for monitoring and session management

Source: community_context/v3.82.0, community_context/v3.80.0, community_context/v3.76.0

Common Community Issues

Model Context Size Reporting

Some third-party providers like LM Studio do not report correct context sizes for models. This manifests as incorrect context window information displayed in chat. Source: community_context/issue-11158

Multi-Directory Workspace Limitations

Users with multi-directory workspaces may only be able to select files from one directory at a time when using file picker tools. Source: community_context/issue-653

API Request Timeouts

API requests may occasionally load indefinitely without completing. This has been reported with various providers including Deepseek. Source: community_context/issue-1157

See Also

• SDK Documentation for detailed API reference
• Architecture Overview for system design details
• Building an Agent Guide for implementation tutorials

Related Pages

Related topics: Core Components: ClineCore, Agents, and Session Management

Hub-Spoke Architecture

Overview

The Hub-Spoke Architecture is Cline's distributed runtime model that enables centralized coordination of multiple AI agent clients from a single local hub instance. This architecture allows the Cline Hub to act as a central orchestrator while individual clients (CLI, VS Code extension, agents) serve as spokes that connect to and receive work from the hub.

The hub provides a WebSocket server that broadcasts UI notifications and commands to all connected subscribers, enabling unified session management, monitoring, and control across multiple client connections.

Source: sdk/apps/examples/menubar/README.md

Related Pages

Related topics: Hub-Spoke Architecture, Code Editing Tools and File Operations

Core Components: ClineCore, Agents, and Session Management

Overview

The Cline SDK architecture is organized into four primary packages, each with distinct responsibilities. At the heart of this architecture lies @cline/core, which provides stateful runtime orchestration, session lifecycle management, and local or hub-backed runtime services. This package sits atop @cline/agents (the stateless agent runtime loop) and @cline/llms (the model and provider layer), composing them into a cohesive system that powers the CLI, VS Code extension, JetBrains plugin, and custom integrations.

The core components covered in this page—ClineCore, Agent Runtime, and Session Management—form the foundational building blocks for any application built on the Cline SDK.

Architecture Overview

graph TD
    subgraph "Application Layer"
        CLI[CLI App]
        EXT[VS Code Extension]
        JBP[JetBrains Plugin]
        CUSTOM[Custom Integration]
    end

    subgraph "@cline/core"
        CC[ClineCore]
        RH[RuntimeHost]
        SS[Session Service]
        CRS[Checkpoint Restore]
    end

    subgraph "@cline/agents"
        AR[Agent Runtime]
        TOOLS[Tools]
        HOOKS[Hooks]
        EXTENSIONS[Extensions]
    end

    subgraph "@cline/llms"
        HANDLERS[LLM Handlers]
        CATALOG[Model Catalog]
        PROVIDERS[Providers]
    end

    CLI --> CC
    EXT --> CC
    JBP --> CC
    CUSTOM --> CC

    CC --> RH
    CC --> SS
    CC --> CRS

    RH --> AR
    AR --> TOOLS
    AR --> HOOKS
    AR --> EXTENSIONS

    AR --> HANDLERS
    HANDLERS --> CATALOG
    HANDLERS --> PROVIDERS

ClineCore: The Application-Facing API

ClineCore is the primary entry point for applications integrating the Cline SDK. It provides a high-level session API that abstracts the underlying runtime primitives, making it straightforward to create, manage, and interact with agent sessions.

Key Responsibilities

Creating a ClineCore Instance

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

const cline = await ClineCore.create({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const result = await cline.start({
  systemPrompt: "You are a concise assistant.",
  prompt: "Summarize this project.",
  interactive: false,
});

console.log(result.result?.text);
await cline.dispose();

Runtime Host Types

ClineCore supports multiple runtime transport strategies through the RuntimeHost abstraction:

The RuntimeHost boundary uses primitive names such as startSession and runTurn, keeping transport concerns separate from product-level methods like start and send.

Agent Runtime

The agent runtime, provided by @cline/agents, implements a stateless runtime loop that orchestrates tool execution, hook invocation, and response streaming. This package is intentionally decoupled from transport and storage concerns, making it portable across different deployment scenarios.

Runtime Loop Architecture

sequenceDiagram
    participant Host as Runtime Host
    participant Agent as Agent Runtime
    participant Tools as Tool Executor
    participant LLM as LLM Handler
    participant Hooks as Hook System

    Host->>Agent: runTurn(task)
    Agent->>LLM: createMessage()
    LLM-->>Agent: response stream
    Agent->>Hooks: invoke hooks
    alt tool_calls present
        Agent->>Tools: execute(tools, args)
        Tools-->>Agent: tool results
        Agent->>LLM: continue with results
        LLM-->>Agent: final response
    end
    Agent-->>Host: result

Built-in Tools

@cline/core owns the built-in host tools and their executors. The tool creation API follows a consistent pattern:

import { createBuiltinTools, createDefaultTools } from "@cline/core";

const builtinTools = await createBuiltinTools({
  workspaceUri: workspaceDir,
  // tool-specific options
});

const customTools = await createDefaultTools({
  // custom tool configurations
});

Bundled Agent Presets

The SDK includes four pre-configured agent presets optimized for specific roles:

These presets can be used directly with the start_subagent tool, passing either the preset name or custom instructions.

Multi-Agent Orchestration

The agent runtime supports multi-agent teams through the start_subagent tool, enabling sophisticated orchestration patterns:

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", ...)
       → ...

The save_handoff and read_handoff tools enable agents to share state within the same conversation, supporting iterative workflows where one agent's output becomes another agent's input.

Session Management

Session management in @cline/core handles the complete lifecycle of agent sessions, including creation, persistence, checkpointing, and restoration. This system ensures that long-running agent tasks can survive process restarts and enables advanced features like pause-and-resume.

Session Service

The SessionService is the central coordinator for session lifecycle operations:

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

const sessionService = createSessionService({
  storageDir: "./sessions",
  // configuration options
});

const session = await sessionService.createSession({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
});

Session Lifecycle States

stateDiagram-v2
    [*] --> Created: createSession()
    Created --> Active: start()
    Active --> Paused: pause()
    Paused --> Active: resume()
    Active --> Completed: task finished
    Active --> Failed: error occurred
    Paused --> [*]: dispose()
    Completed --> [*]: dispose()
    Failed --> [*]: dispose()

Checkpoint and Restore

The checkpoint/restore system enables durable agent state persistence across process restarts:

This feature is particularly valuable for:

• Long-running tasks that may be interrupted
• Building resilient automation workflows
• Implementing pause-and-resume UI patterns

Session Configuration Options

Integration Patterns

Standalone CLI Usage

The CLI provides a ready-made interface built on top of ClineCore:

# Interactive session
cline

# Single prompt
cline "Audit this package and propose fixes"

# With stdin
cat file.txt | cline "Summarize this"

Custom Application Integration

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

const host = await createLocalRuntimeHost({
  workspaceRoot: process.cwd(),
});

const cline = await ClineCore.create({
  host,
  providerId: "openrouter",
  modelId: "anthropic/claude-sonnet-4",
});

await cline.start({
  prompt: "Explain this codebase structure",
  interactive: true,
});

await cline.dispose();

Hub Integration

For distributed scenarios, connect to a Cline Hub instance:

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

const hub = await createHubRuntimeHost({
  hubUrl: "https://hub.example.com",
  roomSecret: process.env.CLINE_HUB_SECRET,
});

const cline = await ClineCore.create({
  host: hub,
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
});

Key Source Files

The following files implement the core components described in this page:

Related Documentation

• SDK Overview — General SDK documentation
• Building an Agent — Step-by-step tutorial
• API Reference — Complete API documentation
• Architecture — System-level architecture guide

Related Pages

Related topics: Plan Mode and Act Mode, Core Components: ClineCore, Agents, and Session Management

Code Editing Tools and File Operations

Overview

Code editing tools and file operations form the core interaction layer between Cline's agent runtime and the developer's workspace. These tools enable AI agents to read source files, write new code, apply structured changes via patches, and navigate complex codebases with precision.

Cline provides a comprehensive set of file operation tools that agents use to:

• Inspect file contents and project structure
• Make targeted edits to source files
• Apply diffs and patches atomically
• Resolve symbol definitions using language services
• Search codebase patterns across large repositories

Source: sdk/packages/README.md

Architecture

Cline's file operation system follows a layered architecture where tools are defined declaratively and executed through a handler pipeline.

graph TD
    A[Agent Decision] --> B[Tool Call Request]
    B --> C[Tool Handler]
    C --> D[File System / LSP]
    D --> E[Result Serialization]
    E --> F[Agent Context Update]
    
    G[Hook System] -.->|Pre/Post| C
    
    style A fill:#e1f5fe
    style F fill:#e8f5e8

Tool Handler Pipeline

Source: sdk/packages/README.md

File Reading Tools

read_file Tool

The read_file tool retrieves file contents from the workspace, supporting both full file reads and targeted chunked access.

Capabilities:

• Full file content retrieval
• Chunked reading for targeted file access (v3.77.0+)
• Line range specification for partial reads
• Automatic handling of large files through streaming

The tool supports showing actual read_file line ranges in the chat UI, providing transparency about what portion of a file was accessed.

Source: sdk/examples/README.md

Chunked Reading (v3.77.0+)

For large files, Cline supports chunked reading to avoid loading entire files into context:

// Chunked read specification example
{
  filePath: "src/large-file.ts",
  startLine: 100,
  endLine: 200
}

This approach reduces memory overhead and context consumption when working with files that contain thousands of lines.

File Read Deduplication (v3.74.0+)

Cline implements a file read deduplication cache to prevent repeated reads of the same file within a session. This optimization:

• Reduces redundant I/O operations
• Improves performance in loops and multi-pass analysis
• Maintains consistency within the session context

Code Editing Tools

write_to_file Tool

The write_to_file tool creates new files or overwrites existing ones with agent-generated content.

Usage Pattern:

1. Agent decides to create or update a file
2. Content is validated against workspace constraints
3. File is written atomically
4. Result confirms success or provides error details

apply_patch Tool

The apply_patch tool applies structured diffs to existing files, enabling precise, reversible modifications.

Key Features:

• Standard unified diff format support
• Atomic application with rollback on failure
• Conflict detection and reporting
• Preservation of file permissions and encoding

Diff Application Flow:

graph LR
    A[Diff Input] --> B[Parse Diffs]
    B --> C[Validate Paths]
    C --> D[Backup Original]
    D --> E[Apply Changes]
    E --> F{Success?}
    F -->|Yes| G[Confirm]
    F -->|No| H[Rollback]
    
    style D fill:#fff3e0
    style H fill:#ffebee

TypeScript Language Service Integration

Cline provides advanced symbol resolution through the TypeScript Language Service, going beyond simple text search.

goto_definition Tool

The TypeScript LSP plugin enables precise symbol navigation:

// Given an import line like:
import { disposeAll, initVcr } from "@cline/shared"

// The tool resolves:
disposeAll -> packages/shared/src/dispose.ts:19
initVcr    -> packages/shared/src/vcr.ts:699

Capabilities:

• Resolves through imports and re-exports
• Handles type aliases correctly
• Supports declaration merging
• Zero extra dependencies (resolves typescript from target project)

Source: sdk/examples/plugins/typescript-lsp/index.ts

Plugin Implementation Pattern

Custom tools can be registered via createTool() and AgentExtension:

import { createTool } from "@cline/agents";
import { AgentExtension } from "@cline/core";

export const gotoDefinitionTool = createTool({
  name: "goto_definition",
  description: "Navigate to symbol definition",
  parameters: {
    file: { type: "string" },
    line: { type: "number" }
  },
  execute: async (params, context) => {
    // Implementation using TypeScript LS
  }
});

Hooks for File Operations

The hook system allows customization of file operation behavior through pre and post execution interceptors.

Pre-Tool-Use Hooks

Hooks can inspect and modify tool calls before execution:

#!/bin/bash
# .cline/hooks/PreToolUse.sh
read event
tool_name=$(echo "$event" | jq -r '.tool_call.name')

if [ "$tool_name" = "read_files" ]; then
  file_path=$(echo "$event" | jq -r '.tool_call.input.filePath')
  if [[ "$file_path" == *.test.ts ]]; then
    echo '{"context": "This is a test file"}'
  fi
fi

Source: sdk/examples/hooks/README.md

Hook Event Structure

Code Review Bot Example

The code review bot demonstrates file operation tools in a real-world scenario:

graph TD
    A[PR URL Input] --> B[Fetch PR Metadata]
    B --> C[Fetch Changed Files]
    C --> D[Render Diff View]
    D --> E[get_file_context Tool]
    E --> F[add_review_finding Tool]
    F --> G[Post Review]

Tools Used:

Source: sdk/apps/examples/code-review-bot/README.md

Configuration Options

File Operation Limits

Workspace Constraints

Cline supports multi-directory workspaces with the following behavior:

• File operations scope to the active workspace root
• Relative paths resolved against workspace boundaries
• Permission checks before write operations

Best Practices

1. Use chunked reading for large files to minimize context usage
2. Leverage LSP tools for precise navigation instead of grep
3. Implement hooks for security-sensitive file operations
4. Prefer patches over full file writes for targeted changes
5. Cache analysis is automatic—avoid manual deduplication

Related Tools

Version History

Related Pages

Related topics: Code Editing Tools and File Operations, Rules and Skills System

Plan Mode and Act Mode

Cline provides two distinct operational modes that control how the agent executes tasks: Plan Mode and Act Mode. These modes define the agent's behavior regarding tool usage, workspace modifications, and execution authority, enabling users to switch between exploratory planning and direct execution workflows.

Overview

Plan Mode and Act Mode are fundamental operating states in Cline that determine the agent's level of autonomy when processing tasks. The mode selection affects which tools are available, whether the agent can modify workspace files, and how the system prompt instructs the agent to behave.

Architecture

The Plan/Act mode system is implemented through several interconnected components that affect system prompts, tool definitions, and runtime behavior.

graph TD
    A[User Task] --> B{Mode Selection}
    B -->|Plan| C[Plan Mode System Prompt]
    B -->|Act| D[Act Mode System Prompt]
    
    C --> E[Restricted Tool Set]
    C --> F[Plan Mode Response Tool]
    D --> G[Full Tool Set]
    D --> H[Act Mode Response Tool]
    
    E --> I[read_files, search_codebase<br/>analysis_only_tools]
    G --> J[All tools including<br/>write and command tools]
    
    F --> K[Proposal Output]
    H --> L[Direct Execution]

Core Components

Plan Mode

Plan Mode is designed for scenarios where you want the agent to analyze, investigate, and propose solutions without making any changes to your codebase. This mode is particularly valuable when:

• Exploring unfamiliar codebases
• Understanding complex architecture decisions
• Reviewing security or performance implications
• Preparing for implementation work
• Onboarding new team members

Tool Restrictions in Plan Mode

In Plan Mode, the agent operates with a restricted toolset focused on analysis and investigation:

Plan Mode Response Tool

The Plan Mode Respond tool is the primary mechanism for the agent to communicate findings and recommendations when operating in Plan Mode.

Implementation Details:

The tool is configured to accept structured responses that include:

• Analysis summary of the investigated code
• Identified issues or opportunities
• Proposed implementation approach
• Estimated complexity and risks
• Recommendations for next steps

When the agent calls this tool, it signals that planning is complete and the user should review the output before deciding whether to proceed.

Act Mode

Act Mode enables full autonomous operation, allowing the agent to use all available tools including those that modify the workspace. This is the default mode for productive work sessions.

Full Tool Access in Act Mode

Act Mode provides access to the complete Cline toolset:

Act Mode Response Tool

The Act Mode Respond tool signals task completion and provides a summary of work performed.

Implementation Details:

This tool captures:

• Summary of changes made
• Files created, modified, or deleted
• Commands executed
• Results and outcomes
• Any remaining considerations

Mode Switching

Users can switch between modes at any time during a session. The mode toggle affects both the current system prompt and available toolset.

graph LR
    A[Plan Mode] -->|Toggle| B[Act Mode]
    B -->|Toggle| A
    
    A -->|Concludes with| C[Proposal/Analysis]
    B -->|Concludes with| D[Implementation/Changes]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0

CLI Usage

In the Cline CLI, modes can be controlled through command-line options:

# Act Mode (default) - executes commands
cline -i "Implement the new feature"

# Yolo Mode - Act Mode with reduced guardrails
cline --yolo "Quick refactor"

# Plan Mode simulation via restricted tools
cline -i "Analyze this module and propose improvements"

System Prompt Integration

The mode behavior is implemented through system prompt components that define agent behavior based on the current mode setting.

Mode Component Structure

The act_vs_plan_mode.ts component provides conditional logic that:

1. Checks the current mode setting
2. Selects appropriate system prompt instructions
3. Configures tool availability based on mode
4. Sets response format expectations

Response Format Differences

Workflow Examples

Exploratory Workflow (Plan → Act)

graph TD
    A[Start in Plan Mode] --> B[Investigate codebase]
    B --> C[Identify implementation approach]
    C --> D[User reviews proposal]
    D --> E{Switch to Act Mode}
    E -->|Approved| F[Implement changes]
    E -->|Modify| G[Refine proposal]
    G --> B
    F --> H[Task complete]

Plan-Only Workflow

For scenarios where you only need analysis without implementation:

1. Start session in Plan Mode
2. Request investigation of specific code area
3. Review agent's analysis and proposals
4. End session or switch to Act Mode for implementation

Quick Implementation (Act Mode)

For straightforward tasks where you trust the agent:

1. Start session in Act Mode
2. Describe the desired outcome
3. Agent executes changes directly
4. Review changes and iterate as needed

Configuration and Settings

Per-Session Mode Selection

The mode can be set at session start or toggled mid-session through:

• UI toggle in the VS Code extension
• Command palette commands
• CLI flags for headless execution

Mode Persistence

Mode preferences can be configured in Cline settings:

Best Practices

When to Use Plan Mode

• Codebase exploration: When navigating unfamiliar code, Plan Mode prevents accidental changes
• Architecture discussions: Useful for discussing design decisions without modifying code
• Risk assessment: Evaluate potential changes before committing to implementation
• Learning: Understand how existing systems work before making modifications

When to Use Act Mode

• Feature implementation: When you have a clear understanding of requirements
• Bug fixes: Direct execution for targeted changes
• Refactoring: Well-defined restructuring tasks
• Testing: Running test suites and verification scripts

Switching Between Modes

• Use Plan Mode to scope and understand the problem first
• Switch to Act Mode once you have reviewed and approved the approach
• Return to Plan Mode if requirements change or new understanding emerges

Related Features

Yolo Mode

For fully autonomous operation without approval prompts, Yolo Mode extends Act Mode behavior:

• Disables submit_and_exit restrictions
• Enables all spawn/team tools by default
• Reduces user intervention requirements

Subagent Orchestration

Both modes support spawning subagents for parallel investigation or implementation tasks, with subagents inheriting the parent session's mode unless explicitly overridden.

Cron and Event-Driven Automation

Automated tasks can specify their mode through spec files:

mode: plan  # or "act"
tools: [read_files, search_codebase]  # restricted in plan mode

Troubleshooting

Common Issues

Mode Detection

If uncertain about current mode:

• Check the mode indicator in the UI
• Observe tool availability in the agent's capabilities
• Review system prompt for mode-specific instructions

References

• System prompt component: act_vs_plan_mode.ts
• Plan mode implementation: plan_mode_respond.ts
• Act mode implementation: act_mode_respond.ts
• User documentation: docs/core-workflows/plan-and-act.mdx
• CLI mode configuration: sdk/apps/cli/README.md

Related Pages

Related topics: MCP (Model Context Protocol) Integration

Provider System and Model Adapters

The Provider System is the abstraction layer that allows Cline to communicate with various LLM (Large Language Model) backends through a unified interface. It normalizes differences between providers like OpenAI, Anthropic, Google, and local providers such as LM Studio, enabling the agent runtime to work with any supported model without provider-specific logic.

Architecture Overview

graph TD
    subgraph "Client Layer"
        VSCode[VS Code Extension]
        CLI[CLI Application]
        SDK[SDK Integration]
    end
    
    subgraph "Provider System"
        Providers[Provider Registry]
        Catalog[Model Catalog]
        Handlers[Handler Factory]
    end
    
    subgraph "Provider Adapters"
        OpenAI[OpenAI Provider]
        Anthropic[Anthropic Provider]
        LMStudio[LM Studio Provider]
        Custom[Custom Providers]
    end
    
    subgraph "External APIs"
        API1[OpenAI API]
        API2[Claude API]
        API3[Local API]
    end
    
    VSCode --> Providers
    CLI --> Providers
    SDK --> Providers
    Providers --> Catalog
    Providers --> Handlers
    Handlers --> OpenAI
    Handlers --> Anthropic
    Handlers --> LMStudio
    Handlers --> Custom
    OpenAI --> API1
    Anthropic --> API2
    LMStudio --> API3

Core Concepts

Provider

A Provider represents a specific LLM service endpoint that Cline can communicate with. Each provider has:

• Unique identifier (providerId) - e.g., openai, anthropic, lmstudio
• Configuration fields - API keys, base URLs, custom headers
• Model list - Available models from that provider
• Capabilities - Vision, reasoning, attachments support

Model Adapter

A Model Adapter normalizes provider-specific model metadata into a common format. It handles:

• Context window size normalization
• Token limits (input/output)
• Feature capabilities (vision, reasoning, tool use)
• Provider-specific request formatting

Provider Configuration Schema

The provider configuration is defined by the Provider interface:

Configuration Field Types

Providers can define custom configuration fields with these types:

Built-in Providers

Cline includes support for multiple built-in providers. The provider factory registry maps provider IDs to their handler creation logic.

OpenAI Provider

The OpenAI provider supports OpenAI's full model lineup including GPT-4, GPT-4o, and GPT-5 models.

Configuration fields:

• apiKey (required) - OpenAI API key
• baseUrl (optional) - Override endpoint for proxies or Azure

Source: apps/vscode/src/core/api/providers/openai.ts:1-50

Anthropic Provider

The Anthropic provider supports Claude models including Claude 3.5, Claude Opus 4.7, and reasoning models.

Configuration fields:

• apiKey (required) - Anthropic API key
• baseUrl (optional) - Custom endpoint

Source: apps/vscode/src/core/api/providers/anthropic.ts:1-50

LM Studio Provider

The LM Studio provider enables connection to locally running LLM servers via OpenAI-compatible API.

Configuration fields:

• baseUrl (required) - Local server URL (default: http://localhost:1234/v1)
• apiKey (optional) - Local authentication key

Known Issues: The community has reported that LM Studio may not correctly report context size for models in chat. This is a known limitation when the local server does not properly expose model metadata.

Source: apps/vscode/src/core/api/providers/lmstudio.ts:1-50

Model Catalog

The model catalog provides normalized metadata for all supported models. It sources data from models.dev and generates the catalog.generated.ts file.

Catalog Fields

Catalog Semantics

The token-limit fields have specific semantics that developers should understand:

contextWindow:  200000
maxInputTokens: 200000
maxTokens:      128000

This configuration indicates:

• The prompt may approach 200,000 tokens
• The model can generate up to 128,000 tokens
• An individual request must still fit within provider rules

Important: These fields are not additive. maxInputTokens + maxTokens is not required to be less than contextWindow — each represents a separate constraint from the provider.

Source: sdk/packages/llms/src/catalog/README.md:1-45

Handler Factory

The handler factory creates provider-specific request handlers that implement the unified AgentModel interface.

graph LR
    Config[Provider Config] --> Registry[Factory Registry]
    Registry --> Handler[Agent Handler]
    Handler --> Stream[Streaming Response]
    Handler --> Chunk[Usage/Metadata]

Creating Handlers

import { createHandler } from "@cline/llms";

const handler = createHandler({
    providerId: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY ?? "",
    modelId: "claude-sonnet-4-6",
});

for await (const chunk of handler.createMessage(systemPrompt, messages)) {
    // Process streaming chunks
}

Source: sdk/packages/llms/README.md:1-60

Runtime Configuration

Provider Form (Recommended)

The preferred way to configure an agent with a provider:

new Agent({
    providerId: "openai",
    modelId: "gpt-4o",
    apiKey: process.env.OPENAI_API_KEY,
    baseUrl: "https://api.openai.com/v1",  // optional
    headers: {},                            // optional
    tools: [/* ... */],
});

Model Form (Advanced)

Supply a pre-built AgentModel directly when the host owns gateway construction:

import { createGateway } from "@cline/llms";

const gateway = createGateway({ providerConfigs: [/* ... */] });
const model = gateway.createAgentModel({ providerId, modelId });

new Agent({
    model,
    tools: [/* ... */],
});

Source: sdk/packages/agents/README.md:1-40

SDK Package Structure

The provider system is implemented across the @cline/llms package:

Package Responsibilities

Source: sdk/packages/README.md:1-30

Live Provider Testing

The SDK supports live testing against real provider APIs with cassette recording for replay tests.

Environment Variables

Live Assertions

Per-provider expectations can be configured:

Source: sdk/packages/llms/README.md:100-150

Webview Provider Schema

The VS Code extension's webview communicates provider data through typed interfaces:

interface ProviderModel {
    id: string;
    name: string;
    supportsAttachments?: boolean;
    supportsVision?: boolean;
    supportsReasoning?: boolean;
}

interface ProviderCatalogResponse {
    providers: Provider[];
    settingsPath: string;
}

Source: sdk/apps/cline-hub/src/webview/src/lib/provider-schema.ts:1-60

Adding Custom Providers

Custom providers can be registered through the factory registry:

1. Define the provider configuration schema
2. Implement handler creation logic
3. Register with registerBuiltinProvider()

Provider Entry Structure

{
    id: "my-provider",
    name: "My Custom Provider",
    apiKeyEnv: "MY_PROVIDER_API_KEY",  // Load from env
    baseUrlEnv: "MY_PROVIDER_URL",
    headersEnv: {},                    // Custom headers
}

This allows live configs to reference secrets without writing them to JSON files.

Troubleshooting

Common Issues

API Request Loading Indefinitely

• Check network connectivity to provider endpoints
• Verify API key is valid and has not expired
• Check provider status pages for outages
• Community reports affecting various providers including Deepseek

Incorrect Context Size (LM Studio)

• Local LLM servers may not correctly report model metadata
• Ensure LM Studio is updated to the latest version
• Verify the model is properly loaded in LM Studio

403 Forbidden Errors

• Some providers restrict access to coding agents only
• Kimi For Coding specifically requires agent-type requests
• Verify provider terms of service allow your use case

Getting Help

• Check provider-specific documentation
• Review the GitHub issues for similar reports
• Join the Cline Discord for community support

Related Pages

Related topics: Provider System and Model Adapters

MCP (Model Context Protocol) Integration

Overview

MCP (Model Context Protocol) is a standardized protocol that enables Cline to connect with external tools and services through MCP servers. This integration allows the coding agent to extend its capabilities by leveraging specialized tools provided by MCP servers, effectively creating a pluggable architecture where new capabilities can be added without modifying the core agent implementation.

Cline's MCP integration supports multiple deployment scenarios including the VS Code extension, CLI, and the broader SDK ecosystem. MCP servers communicate with Cline through a well-defined protocol that handles tool discovery, tool execution, and streaming responses.

Architecture

Cline's MCP integration is built around several core components that work together to provide seamless MCP server management and tool execution.

graph TD
    A[Cline Agent] --> B[MCP Tool Layer]
    B --> C[McpHub Service]
    C --> D[MCP Servers]
    D --> E[External Tools/APIs]
    C --> F[Server Configuration Store]
    G[User/Extension Config] --> C

Core Components

McpHub Service

The McpHub serves as the central orchestrator for all MCP operations. It handles:

• Server Lifecycle Management: Starting, stopping, and monitoring MCP server processes
• Tool Discovery: Enumerating available tools from connected servers
• Request Routing: Directing tool calls to the appropriate MCP server
• Response Streaming: Handling streamed responses from MCP servers

The hub maintains a registry of configured servers and their associated tools, enabling the agent to select and invoke tools dynamically during task execution.

Type System

The MCP type definitions (types.ts) provide the contract between Cline and MCP servers:

// Core type structure from types.ts
interface McpServer {
  id: string;
  name: string;
  command: string;
  args?: string[];
  env?: Record<string, string>;
  enabled: boolean;
}

interface McpTool {
  name: string;
  description?: string;
  inputSchema: object;
  serverId: string;
}

These types ensure type-safe communication and enable IDE features like autocomplete when configuring MCP servers.

Configuration

Server Configuration

MCP servers are configured through Cline's settings interface. Each server configuration includes:

Settings Storage

Server configurations are persisted to providers.json in the Cline data directory:

{
  "mcpServers": [
    {
      "id": "filesystem",
      "name": "Filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "enabled": true
    }
  ]
}

MCP Tool Integration

Tool Discovery Flow

sequenceDiagram
    participant Agent as Cline Agent
    participant Hub as McpHub
    participant Server as MCP Server
    participant Store as Config Store
    
    Agent->>Hub: Request available tools
    Hub->>Store: Load enabled servers
    Store-->>Hub: Server configs
    Hub->>Server: Initialize connection
    Server-->>Hub: Connection established
    Hub->>Server: List tools request
    Server-->>Hub: Tool manifest
    Hub-->>Agent: Aggregated tool list

Tool Invocation

When the agent calls an MCP tool:

1. The tool request is routed through the agent's tool execution layer
2. McpHub receives the request with tool name and input parameters
3. The appropriate MCP server is identified from the tool manifest
4. The request is serialized according to the MCP protocol
5. The server processes the request and returns a response or stream
6. The response is deserialized and returned to the agent

SDK Integration

The Cline SDK provides MCP support through @cline/core, enabling applications built on the SDK to leverage MCP servers:

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

const cline = await ClineCore.create({
  providers: [],
  mcpServers: [
    { id: "custom-server", command: "node", args: ["server.js"] }
  ]
});

Source: sdk/packages/core/package.json

The SDK's MCP integration follows the same architectural patterns as the VS Code extension, ensuring consistent behavior across all Cline deployment targets.

Known Issues and Limitations

MCP Server Logging

Community Issue #1959: Some MCPs are buggy - they are running but returning errors back to Cline via stderr. Cline spawns MCPs but hides logs that these MCPs may write to the console.

Current Behavior: MCP server stderr output is captured by the extension but not exposed to users through a dedicated log viewer. This makes debugging problematic MCP servers difficult.

Workaround: Run MCP servers manually in a terminal to observe stderr output, then configure them in Cline once operational.

Recommended MCP Servers

Community Issue #10068: Cline users frequently add MCP servers from the Cline marketplace, but there's no quality signal to help them identify which servers are well-implemented and will work reliably.

The community has proposed integrating quality scoring services like Clarvia to provide AEO (Automated Evaluation and Optimization) scores for recommended MCP servers, helping users make informed decisions about which servers to install.

Best Practices

Server Selection

1. Start with official MCP servers from the Model Context Protocol repository for reliability
2. Verify server compatibility with your Cline version before adding to your configuration
3. Test servers individually before enabling multiple servers simultaneously

Configuration Guidelines

Performance Considerations

• MCP server processes run as child processes and consume memory and CPU
• Tool responses are network-local (when servers run locally) or network-dependent
• Minimize the number of enabled servers to reduce latency and resource usage

Troubleshooting

Server Connection Failures

1. Verify the server command is executable and in your PATH
2. Check that required dependencies are installed (e.g., npx for npm-based servers)
3. Review the server's documentation for specific configuration requirements
4. Run the server manually in a terminal to identify startup errors

Tool Not Found

• Ensure the server is enabled in settings
• Restart Cline after adding new MCP servers
• Verify the tool is exposed by the server's manifest

Timeout Issues

Some MCP servers may experience timeout issues during long-running operations. Consider:

• Breaking complex tasks into smaller tool invocations
• Using servers that support streaming for better interactivity

References

• MCP Protocol Specification
• Official MCP Servers
• Cline MCP Documentation

Related Documentation

• CLI MCP Usage - MCP support in the CLI application
• Provider Schema Types - Interface definitions for provider integration

Related Pages

Related topics: Plan Mode and Act Mode

Rules and Skills System

The Rules and Skills System provides two complementary mechanisms for customizing agent behavior in Cline. Rules are explicit behavioral directives that constrain or guide agent actions, while Skills are modular instructional packages that extend the agent's capabilities for specific task domains.

Overview

Cline's agent is driven by system instructions that combine multiple sources of configuration:

• ClineRules: Explicit directives stored as .md files in .cline/rules/
• Skills: Modular instructional packages from .cline/skills/ or remote configurations
• Remote Config: Enterprise-managed globalSkills delivered via remote configuration

The system loads and merges these instruction sources at runtime, combining them into the agent's system prompt. Both rules and skills can be toggled per-project or enforced globally by enterprise administrators.

Source: sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts

Architecture

graph TD
    A[User Configuration] --> B[UserInstructionConfigLoader]
    B --> C[Rules Loader]
    B --> D[Skills Loader]
    B --> E[Remote Config Loader]
    
    C --> F[.cline/rules/\*.md]
    D --> G[.cline/skills/\*.md]
    E --> H[Remote globalSkills]
    
    F --> I[Rules Content]
    G --> J[Skills Content]
    H --> K[Enterprise Skills]
    
    I --> L[System Prompt Composition]
    J --> L
    K --> L
    
    L --> M[Agent Runtime]
    
    subgraph Enterprise Features
        H --> K
    end

Package Responsibilities

The Rules and Skills System spans multiple packages:

Source: sdk/packages/README.md

ClineRules

ClineRules are .md files containing explicit behavioral directives. They provide deterministic, structured guidance that the agent should follow during execution.

Rule File Structure

Rules are Markdown files stored in the project workspace:

.cline/rules/
├── coding-standards.md
├── security-guidelines.md
├── test-requirements.md

Each rule file contains directive text that is loaded and injected into the agent's system prompt. Rules can be toggled on or off via the VS Code extension UI, allowing per-project customization.

Rule Loading

Rules are loaded through the ClineRulesProvider class, which:

1. Scans the .cline/rules/ directory for .md files
2. Reads and validates rule content
3. Makes rules available for toggle UI
4. Includes enabled rules in the system prompt

Source: apps/vscode/src/core/context/instructions/user-instructions/cline-rules.ts

Enterprise Rules

Enterprise deployments can apply rules globally across all sessions using globalAgentRules. These rules are:

• Applied automatically to all projects
• Cannot be disabled by individual users
• Delivered via remote configuration

The CLI v3.0.15 release introduced "Support global AGENTS rules so agent rules can be applied across all sessions, not just per-project."

Skills

Skills are modular instructional packages that teach the agent specialized knowledge and approaches for specific task domains. Unlike rules which are simple directives, skills provide comprehensive guidance for entire workflow categories.

Bundled Skills

The agents-squad plugin includes pre-configured skills:

Source: sdk/examples/plugins/agents-squad/README.md

Skill Discovery

The SDK provides tools for discovering and loading skills at runtime:

Source: sdk/examples/plugins/agents-squad/README.md

Skill Loading

Skills are loaded through the SkillsProvider class, which:

1. Scans local .cline/skills/ directories
2. Checks remote configurations for globalSkills
3. Validates skill format and content
4. Makes skills available for selection in the UI

Source: apps/vscode/src/core/context/instructions/user-instructions/skills.ts

Enterprise Skills (globalSkills)

Enterprise deployments can manage skills centrally using globalSkills in remote configuration. This feature was introduced in v3.79.0 and enhanced in v3.80.0.

Enterprise-managed skills appear under a dedicated "Enterprise Skills" section in the UI and support alwaysEnabled enforcement, meaning they cannot be disabled by individual users.

Key capabilities:

• Remote configuration of skill content
• UI toggle support for optional enterprise skills
• System prompt integration for automatic inclusion
• Enforcement of required skills via alwaysEnabled

Source: apps/vscode/src/core/context/instructions/user-instructions/skills.ts

Integration with Bundled Agents

The Rules and Skills System integrates with Cline's bundled agent presets, which use skills to define their specialized behaviors:

Source: sdk/examples/plugins/agents-squad/README.md

Automation Integration

The Rules and Skills System extends into Cline's automation framework through .cron.md and .event.md specifications.

Automation Spec Configuration

Automation specs can reference rules and skills:

Doramagic Pitfall Log

Found 35 structured pitfall item(s), including 12 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_6c666b426e184cc68942e447f8497b34 | https://github.com/cline/cline/issues/11130

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_8f4e7a4ae6d14f019020c38d0e8e981b | https://github.com/cline/cline/issues/10068

3. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_c6e2166cf8bd485abada3621694898a3 | https://github.com/cline/cline/issues/11142

4. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_b494d39931824fb08752c30da1e491f1 | https://github.com/cline/cline/issues/10596

5. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_1e50ca8cdb714e1a95984b3de7f39e12 | https://github.com/cline/cline/issues/11155

6. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_ce82c0e9e38b4b56a313e37ac27b2efd | https://github.com/cline/cline/issues/11158

7. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_abc760ef752e4e21acc8b3c659b68e53 | https://github.com/cline/cline/issues/10307

8. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_726383b653d748969aa41afa2ea71e30 | https://github.com/cline/cline/issues/10076

9. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_4b312123333840f4bf88b05c25c6f2f5 | https://github.com/cline/cline/issues/11105

10. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_08df034f6cea401c828566efcc7c5bc9 | https://github.com/cline/cline/issues/4389

11. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_44f9b2daf34f42bbbd3cd52934bc43a2 | https://github.com/cline/cline/issues/5251

12. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_7dfcdf7724b3448f9a676341aa03c5dd | https://github.com/cline/cline/issues/11154

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using cline with real data or production workflows.

• Feature: Add Clarvia MCP quality scorer to recommended MCP servers - github / github_issue
• Clarvia AEO Score: Quality validation for MCP servers used in Cline - github / github_issue
• lm studio issues - github / github_issue
• Add HVTracker badge to README? - github / github_issue
• 403 Kimi For Coding is currently only available for Coding Agents such a - github / github_issue
• Cline's OpenRouter integration lacks provider pinning, inflating costs b - github / github_issue
• Installation risk requires verification - GitHub / issue
• Installation risk requires verification - GitHub / issue
• Configuration risk requires verification - GitHub / issue
• Security or permission risk requires verification - GitHub / issue
• Security or permission risk requires verification - GitHub / issue
• Security or permission risk requires verification - GitHub / issue