# https://github.com/cline/cline Project Manual
Generated at: 2026-05-31 03:55:14 UTC
## Table of Contents
- [Introduction to Cline](#introduction)
- [Quick Start Guide](#quick-start)
- [Product Comparison and Use Cases](#product-comparison)
- [Hub-Spoke Architecture](#hub-spoke-model)
- [Core Components: ClineCore, Agents, and Session Management](#core-components)
- [Code Editing Tools and File Operations](#code-editing-tools)
- [Plan Mode and Act Mode](#plan-act-mode)
- [Provider System and Model Adapters](#provider-system)
- [MCP (Model Context Protocol) Integration](#mcp-integration)
- [Rules and Skills System](#rules-skills)
## Introduction to Cline
### Related Pages
Related topics: [Product Comparison and Use Cases](#product-comparison), [Hub-Spoke Architecture](#hub-spoke-model)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/cline/cline/blob/main/README.md)
- [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/packages/llms/README.md](https://github.com/cline/cline/blob/main/sdk/packages/llms/README.md)
- [sdk/packages/agents/README.md](https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md)
- [sdk/packages/core/README.md](https://github.com/cline/cline/blob/main/sdk/packages/core/README.md)
- [sdk/examples/README.md](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
- [sdk/packages/shared/package.json](https://github.com/cline/cline/blob/main/sdk/packages/shared/package.json)
- [sdk/apps/cli/package.json](https://github.com/cline/cline/blob/main/sdk/apps/cli/package.json)
- [LICENSE](https://github.com/cline/cline/blob/main/LICENSE)
# 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:
| Surface | Description | Status |
|---------|-------------|--------|
| VS Code Extension | The primary Marketplace extension with full IDE integration | Active |
| JetBrains Plugin | IDE-hosted client that connects to the shared agent core | Active |
| CLI | Terminal-based interface for CI/CD, scripting, and paired sessions | Active (v3.0.15) |
| SDK | Software development kit for building custom agent-powered applications | Active |
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](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/issues/10068)
## Architecture
The Cline SDK is organized into four primary packages that build upon each other:
```mermaid
graph TD
A["@cline/llms Model Catalog + Provider Settings"] --> B["@cline/agents Agent Runtime Loop"]
B --> C["@cline/core Runtime Orchestration + Sessions"]
C --> D["CLI / Desktop Apps"]
A --> D
B --> D
E["@cline/shared Shared Primitives"] --> A
E --> B
E --> C
```
### Package Responsibilities
| Package | Primary Responsibility | Typical Consumers | Internal Dependencies |
|---------|------------------------|-------------------|----------------------|
| `@cline/shared` | Cross-package utilities (path resolution, session types, indexing helpers) | `@cline/agents`, `@cline/core`, apps | None |
| `@cline/llms` | Model catalog, provider settings schema, handler creation SDK | `@cline/agents`, `@cline/core`, apps | None |
| `@cline/agents` | Stateless agent runtime loop (tools, hooks, extensions, teams, streaming) | `@cline/core`, apps | `@cline/llms`, `@cline/shared` |
| `@cline/core` | Stateful runtime orchestration (session lifecycle, storage, hub services) | CLI/Desktop apps | `@cline/agents`, `@cline/llms`, `@cline/shared` |
Source: [sdk/packages/README.md](https://github.com/cline/cline/blob/main/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
```typescript
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](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/blob/main/sdk/packages/shared/package.json)
## Command Line Interface
The Cline CLI (version 3.0.15) provides terminal-based access to the agent capabilities:
```sh
npm install -g cline
```
For nightly builds:
```sh
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
| Mode | Command | Use Case |
|------|---------|----------|
| Interactive | `cline` | Paired coding sessions |
| Single prompt | `cline "Audit this package"` | One-off tasks |
| Piped input | `cat file.txt \| cline "Summarize"` | Batch processing |
| Headless/CI | `cline --headless` | Automated pipelines |
Source: [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
### Authentication
```sh
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
```bash
cline plugin install
```
Supported sources:
- Local files
- GitHub file URLs
- Package directories
- Git repositories
- npm packages
### Example Plugins
| Plugin | Description |
|--------|-------------|
| `weather-metrics.ts` | Weather query tool |
| `mac-notify.ts` | macOS Notification Center alerts |
| `custom-compaction.ts` | Custom context compaction |
| `automation-events.ts` | Plugin event emission |
| `background-terminal.ts` | Background shell jobs with logging |
| `typescript-lsp` | `goto_definition` tool using TypeScript Language Service API |
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](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/releases/tag/v3.75.0)
### 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:
```yaml
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](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/releases/tag/v3.76.0)
### 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](https://github.com/cline/cline/releases/tag/v3.80.0)
## SDK Examples
The SDK includes practical examples ordered from beginner to advanced:
| Level | Example | Description | Key Concepts |
|-------|---------|-------------|---------------|
| Beginner | `quickstart` | Single prompt, streaming response (~15 lines) | `Agent`, `subscribe`, `run()` |
| Beginner | `cli-agent` | Interactive terminal chat with shell tool | `createTool`, multi-turn `run()` |
| Beginner | `cline-core-cli-agent` | Terminal chat powered by ClineCore | `ClineCore.create()`, built-in tools |
| Intermediate | `code-review-bot` | AI-powered PR review dashboard | GitHub integration, streaming reviews |
### Running Examples
```bash
cd sdk/apps/examples/
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
```
Requires Node.js 22+.
Source: [sdk/apps/examples/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md)
## Known Limitations and Community Concerns
### Active Community Issues
| Issue | Description | Engagement |
|-------|-------------|------------|
| #3510 | Licensing Conflict between Apache 2.0 and Terms of Service | 4 comments |
| #63 | IDE support requests (JetBrains, VS2022) | 77 comments |
| #1157 | API requests loading indefinitely | 86 comments |
| #653 | Multi-directory workspace limitations | 30 comments |
| #1959 | No way to view MCP server logs | 5 comments |
### 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](https://github.com/cline/cline/issues/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](https://github.com/cline/cline/issues/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](https://github.com/cline/cline/blob/main/LICENSE)
## Getting Started
1. **Install the CLI**: `npm install -g cline`
2. **Configure authentication**: `cline auth`
3. **Add providers**: `cline auth add `
4. **Start coding**: `cline` for interactive mode or `cline ""` for single commands
For VS Code: Install from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
For SDK development: See the [SDK Documentation](https://docs.cline.bot/sdk/guides/building-an-agent) for end-to-end tutorials and the [Architecture Overview](https://docs.cline.bot/sdk/architecture/overview) for structural details.
Source: [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
---
## Quick Start Guide
### Related Pages
Related topics: [Introduction to Cline](#introduction), [Provider System and Model Adapters](#provider-system)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/cline/cline/blob/main/README.md)
- [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [sdk/apps/examples/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md)
- [sdk/examples/README.md](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
# 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:
```bash
npm i -g cline
```
Verify the installation:
```bash
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](https://github.com/cline/cline/blob/main/README.md)
### VS Code Extension
Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) 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](https://github.com/cline/cline/blob/main/README.md)
### JetBrains Plugin
Install from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/28247-cline) for support across IntelliJ IDEA, PyCharm, WebStorm, GoLand, and other JetBrains family IDEs. Source: [README.md:1](https://github.com/cline/cline/blob/main/README.md)
## 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:
| Provider | Configuration Method |
|----------|---------------------|
| OpenAI | API key + model selection |
| Anthropic | API key + model selection |
| OpenRouter | API key + model selection |
| Google AI | API key + model selection |
| Azure OpenAI | Endpoint + API key + deployment |
| AWS Bedrock | Credentials + region + model |
| Custom providers | Manual endpoint configuration |
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](https://github.com/cline/cline/blob/main/sdk/README.md)
### SDK Quick Start
For programmatic usage, install the Cline SDK:
```bash
npm install @cline/sdk
```
The SDK requires **Node.js 22 or later**. Source: [sdk/packages/core/package.json:1](https://github.com/cline/cline/blob/main/sdk/packages/core/package.json)
#### Your First Agent
Create a simple agent that streams a response:
```typescript
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](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md)
## CLI Usage Modes
The CLI supports multiple operation modes:
### Interactive Mode
Run without arguments to enter interactive chat:
```bash
cline
```
### Single Task Mode
Pass your task as an argument:
```bash
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:
```bash
cline -i "Run the test suite and report results" -y
```
### Background Dispatch
Dispatch a task to the background hub and exit immediately:
```bash
cline -i "Refactor the database layer" -z
```
Source: [sdk/apps/cli/README.md:1](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
## CLI Command Reference
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input ` | Task to execute | Interactive prompt |
| `-m, --model ` | Override model selection | Configured default |
| `--provider ` | Override API provider | Configured default |
| `-c, --cwd ` | Working directory for tools | Current directory |
| `-y, --yolo` | Skip tool approvals, disable spawn/team tools | Off |
| `-z, --zen` | Dispatch to background hub, exit immediately | Off |
| `--thinking ` | Model thinking level (none/low/medium/high/xhigh) | medium if flag provided |
| `--compaction ` | Context compaction (agentic/basic/off) | basic |
| `--retries ` | Max consecutive mistakes before halting | 3 |
| `--json` | Output NDJSON instead of styled text | false |
| `--auto-approve [bool]` | Set auto-approval for all tools | false |
| `--kanban` | Launch the Kanban app | false |
| `--config ` | Configuration directory | ~/.cline |
| `--data-dir ` | Isolated local state directory (sandbox mode) | ~/.cline |
Source: [sdk/apps/cli/README.md:1](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
## SDK Examples
The SDK includes runnable examples demonstrating progressively advanced concepts. All examples require Node.js 22+ and use Bun for builds:
```bash
cd apps/examples/
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
```
### Beginner Examples
| Example | Description | Key Concepts |
|---------|-------------|--------------|
| [quickstart](./quickstart) | Single prompt with streaming | `Agent`, `subscribe`, `run()` |
| [cli-agent](./cli-agent) | Interactive terminal chat | `createTool`, multi-turn streaming |
| [cline-core-cli-agent](./cline-core-cli-agent) | Terminal chat powered by ClineCore | `ClineCore.create()`, session management |
### Intermediate Examples
| Example | Description | Key Concepts |
|---------|-------------|--------------|
| [code-review-bot](./code-review-bot) | Real PR analysis dashboard | GitHub API, structured review output |
| [multi-agent](./multi-agent) | Parallel agent war room | Concurrent agents, SSE streaming |
### Advanced Examples
| Example | Description | Key Concepts |
|---------|-------------|--------------|
| [plugins/typescript-lsp](./plugins/typescript-lsp) | Language service navigation | TypeScript Language Service API |
| [plugins/agents-squad](./plugins/agents-squad) | Background subagent orchestration | Multi-agent teams, skill loading |
Source: [sdk/apps/examples/README.md:1](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md) and [sdk/examples/README.md:1](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
## Package Architecture
Understanding the SDK's package structure helps when building custom integrations:
| Package | Primary Responsibility | Typical Consumers | Internal Dependencies |
|---------|----------------------|-------------------|----------------------|
| `@cline/shared` | Cross-package primitives (path resolution, session types, indexing) | `@cline/agents`, `@cline/core`, apps | None |
| `@cline/llms` | Model catalog, provider settings, handler creation | `@cline/agents`, `@cline/core`, apps | None |
| `@cline/agents` | Stateless agent runtime (tools, hooks, extensions, teams, streaming) | `@cline/core`, apps | `@cline/llms`, `@cline/shared` |
| `@cline/core` | Stateful orchestration (session lifecycle, storage, hub services) | CLI/Desktop apps | `@cline/agents`, `@cline/llms`, `@cline/shared` |
Source: [sdk/packages/README.md:1](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
## 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
```bash
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](https://github.com/cline/cline/blob/main/sdk/apps/examples/code-review-bot/README.md)
## 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](https://github.com/cline/sdk-skill) to give your coding agent context on SDK APIs and best practices
- **Automation**: Set up [cron jobs and event-driven automations](./cron) for recurring tasks or PR-triggered workflows
## Troubleshooting
| Issue | Solution |
|-------|----------|
| API requests loading indefinitely | Check API key validity and quota; try switching models or providers |
| LM Studio context size incorrect | LM Studio may not report accurate context limits for custom models |
| MCP server errors not visible | MCP stderr logs are currently not exposed in the UI |
| Multi-directory workspace issues | Cline may only recognize files from the first workspace directory |
For additional help, join the [Discord community](https://discord.gg/cline) or check the [GitHub Discussions](https://github.com/cline/cline/discussions).
---
## Product Comparison and Use Cases
### Related Pages
Related topics: [Introduction to Cline](#introduction)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/cline/cline/blob/main/README.md)
- [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [sdk/apps/examples/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md)
- [sdk/apps/examples/multi-agent/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/multi-agent/README.md)
- [sdk/apps/examples/code-review-bot/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/code-review-bot/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/packages/llms/src/catalog/README.md](https://github.com/cline/cline/blob/main/sdk/packages/llms/src/catalog/README.md)
# 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.
| Product | Deployment Model | Primary Interface | Typical User |
|---------|-----------------|-------------------|--------------|
| **VS Code Extension** | Local IDE plugin | Chat panel + terminal | Developers preferring GUI-based workflows |
| **JetBrains Plugin** | Local IDE plugin | Chat panel + tool windows | IntelliJ, PyCharm, WebStorm users |
| **CLI** | Terminal executable | Interactive TUI or headless | DevOps, CI/CD, power users |
| **SDK** | Programmatic API | TypeScript/JavaScript | Teams building custom agent integrations |
Source: [README.md:1-50]()
## Feature Comparison
### Core Capabilities Matrix
| Capability | VS Code Extension | JetBrains Plugin | CLI | SDK |
|------------|:-----------------:|:----------------:|:---:|:---:|
| Interactive chat | Yes | Yes | Yes | Yes |
| Tool execution | Yes | Yes | Yes | Yes |
| File system operations | Yes | Yes | Yes | Yes |
| Shell command execution | Yes | Yes | Yes | Yes |
| Streaming responses | Yes | Yes | Yes | Yes |
| MCP server integration | Yes | Yes | Yes | Yes |
| Custom tools | Via plugins | Via plugins | Via plugins | Native |
| Hook system | Yes | Yes | Yes | Yes |
| Agent presets | Yes | Yes | Yes | Yes |
| Multi-agent teams | Via hub | Via hub | Via hub | Native |
| Scheduled automations | Via hub | Via hub | Via hub | Native |
| Session persistence | Yes | Yes | Yes | Via core runtime |
Source: [sdk/packages/README.md:1-20]()
### Context Management Features
| Feature | Details |
|---------|---------|
| **Context window** | Maximum context budget reported for the model |
| **maxInputTokens** | Prompt/input-token budget used for compaction and diagnostics |
| **maxTokens** | Provider-reported output-token budget for generation |
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
| Option | Description |
|--------|-------------|
| `--model ` | Specify the model to use |
| `--provider ` | Specify the API provider |
| `-i, --instruction ` | Single instruction mode |
| `--cwd ` | Working directory for tools |
| `--config ` | Configuration directory |
| `--thinking [none\|low\|medium\|high\|xhigh]` | Model thinking level |
| `--compaction ` | Context compaction mode |
| `--json` | Output NDJSON instead of styled text |
| `-y, --yolo` | Skip tool approval, enable `submit_and_exit` |
| `-z, --zen` | Dispatch to background hub, exit immediately |
| `--auto-approve [true\|false]` | Tool auto-approval setting |
| `--kanban` | Launch the Kanban application |
| `--retries ` | Maximum consecutive retries (default: 3) |
Source: [sdk/apps/cli/README.md:1-80]()
### Headless Execution Patterns
```mermaid
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
| Package | Primary Responsibility | Internal Dependencies |
|---------|----------------------|----------------------|
| `@cline/shared` | Cross-package primitives, path resolution, session types | None |
| `@cline/llms` | Model catalog, provider settings, handler creation | None |
| `@cline/agents` | Stateless agent runtime, tools, hooks, extensions | `@cline/llms`, `@cline/shared` |
| `@cline/core` | Stateful orchestration, session lifecycle, hub services | `@cline/agents`, `@cline/llms`, `@cline/shared` |
Source: [sdk/packages/README.md:1-25]()
### Package Interaction Flow
```mermaid
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:**
| Agent | Focus Area |
|-------|------------|
| Architect | System design |
| Security Analyst | Security audit |
| Pragmatist | Product considerations |
| Skeptic | Red team review |
Source: [sdk/apps/examples/multi-agent/README.md:1-50]()
## Choosing the Right Product
### Decision Framework
```mermaid
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
| Scenario | Recommended Product |
|----------|---------------------|
| Solo development, IDE-native workflow | VS Code Extension or JetBrains Plugin |
| CI/CD automation, scripts | CLI (headless mode) |
| Remote server development | CLI (interactive mode) |
| Custom agent-powered application | SDK |
| Team-wide coding standards automation | SDK with Hub |
| PR review automation | SDK with scheduled cron |
| Multi-agent research synthesis | SDK with multi-agent examples |
### 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](https://docs.cline.bot/cline-sdk/overview) for detailed API reference
- [Architecture Overview](https://docs.cline.bot/sdk/architecture/overview) for system design details
- [Building an Agent Guide](https://docs.cline.bot/sdk/guides/building-an-agent) for implementation tutorials
---
## Hub-Spoke Architecture
### Related Pages
Related topics: [Core Components: ClineCore, Agents, and Session Management](#core-components)
Related Source Files
The following source files were used to generate this page:
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
- [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
- [sdk/packages/agents/README.md](https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md)
- [sdk/packages/core/package.json](https://github.com/cline/cline/blob/main/sdk/packages/core/package.json)
# 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](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## High-Level Architecture
The architecture follows a star topology where the Hub serves as the central node:
```mermaid
graph TD
CLI["CLI Client (cline)"]
VSCode["VS Code Extension (Cline)"]
Agent["Agents (SDK)"]
MenuBar["Menu Bar App (Tauri)"]
HubServer["Hub WebSocket Server @cline/core/hub/server.ts"]
HubState["Hub State Session Tracking"]
Notify["ui.notify ui.show_window"]
CLI -->|"ws://"| HubServer
VSCode -->|"ws://"| HubServer
Agent -->|"ws://"| HubServer
MenuBar -->|"JSON lines"| HubServer
HubServer -->|"broadcasts"| Notify
HubServer --> HubState
HubState -->|"session lifecycle"| CLI
HubState -->|"session lifecycle"| VSCode
HubState -->|"session lifecycle"| Agent
```
Source: [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## Package Responsibilities
The Hub-Spoke Architecture is implemented across multiple SDK packages with distinct responsibilities:
| Package | Role in Hub-Spoke | Description |
|---------|-------------------|-------------|
| `@cline/core` | Hub Server & Runtime Services | Stateful runtime orchestration, session lifecycle/storage, local and hub runtime services, hub discovery and client helpers |
| `@cline/agents` | Session Execution | Stateless agent runtime loop executed within hub-managed sessions |
| `@cline/llms` | Model Abstraction | Handler creation and provider configuration used by hub sessions |
| `@cline/shared` | Common Types | Cross-package shared primitives including session common types |
Source: [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
---
## Hub Components
### Hub WebSocket Server
The Hub WebSocket Server (`@cline/core/hub/server.ts`) is the central communication layer that:
- Accepts WebSocket connections from multiple client types
- Broadcasts UI events (`ui.notify`, `ui.show_window`) to all connected subscribers
- Maintains hub state including connected clients and active sessions
- Handles room secrets for local, LAN, and tunnel access gating
### Hub State Management
The hub maintains runtime state including:
- Connected clients and their session associations
- Active agent sessions and their execution status
- Recent events and notification history
- Background session launcher state
### Sidecar Integration
The Hub supports sidecar processes (like the Menu Bar App) that communicate via JSON lines on stdout:
```
hub_state / notification / ready
```
Source: [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## Client Types (Spokes)
### CLI Client
The Cline CLI (`cline`) connects to the local hub via WebSocket for:
- Session management and persistence
- Access to hub-monitored agent outputs
- Background session execution
### VS Code Extension
The VS Code extension connects to the hub for:
- Unified session tracking across IDE and CLI
- Notification broadcasting
- Hub-aware UI integration
### SDK Agents
Applications built with the `@cline/agents` package can connect to the hub for:
- Shared session management
- Real-time output streaming
- Coordinated multi-agent execution
Source: [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
---
## Communication Protocol
### WebSocket Events
The hub communicates with spokes using structured events:
| Event | Direction | Purpose |
|-------|-----------|---------|
| `ui.notify` | Hub → Spokes | Broadcast notifications to all connected clients |
| `ui.show_window` | Hub → Spokes | Request window display on clients |
| `session.start` | Spoke → Hub | Register new agent session |
| `session.update` | Bidirectional | Session state synchronization |
### JSON Line Protocol (Sidecar)
Sidecar processes communicate via structured JSON lines on stdout:
```typescript
// Hub state updates
{ type: "hub_state", clients: 3, sessions: 2 }
// Notifications
{ type: "notification", message: "...", severity: "info" }
// Ready signal
{ type: "ready" }
```
Source: [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## Session Lifecycle
Sessions managed by the hub follow a defined lifecycle:
```mermaid
stateDiagram-v2
[*] --> Created: client.connect()
Created --> Active: session.start()
Active --> Streaming: agent.createMessage()
Streaming --> Active: streaming.complete
Active --> Paused: hub.pause()
Paused --> Active: hub.resume()
Active --> Completed: session.end()
Completed --> [*]
Active --> Error: runtime.error
Error --> [*]
```
Source: [sdk/packages/agents/README.md](https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md)
---
## Security Model
### Room Secret Gating
Access to the hub is gated by room secrets with three access levels:
| Access Level | Network Scope | Authentication |
|--------------|---------------|----------------|
| Local | localhost only | No room secret required |
| LAN | Local network | Room secret required |
| Tunnel | Remote via tunnel | Room secret required |
Source: [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## Hub Monitor
The Hub Monitor is a web application that provides a UI for monitoring connected clients, viewing and driving sessions, streaming assistant output, and restarting the local hub.
### Features
- Live hub status display (uptime, connected clients, active sessions)
- Running session tracker and inspector
- Recent events log
- Background session launcher
- System tray integration with dynamic menu
### Architecture
```
┌─────────────────────────────────────────────────────┐
│ Hub Monitor Window │
│ ┌───────────────────────────────────────────────┐ │
│ │ Hub Connected — 3 clients, 2 sessions │ │
│ │ ───────────────────── │ │
│ │ ● Live status │ │
│ │ ● Session inspector │ │
│ │ ● Event log │ │
│ └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```
### Access URLs
| Mode | URL | Access |
|------|-----|--------|
| Dev UI | http://127.0.0.1:3466/ | Preview with mock data |
| Full Tauri App | System tray application | Real hub integration |
Source: [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## Configuration
### Hub Server Configuration
The `@cline/core` package exposes hub configuration through:
```typescript
import { createClineCore } from "@cline/core";
const core = createClineCore({
hub: {
port: 3466,
roomSecret: "optional-secret",
allowedOrigins: ["localhost:*"],
},
});
```
### Runtime Requirements
| Requirement | Specification |
|-------------|---------------|
| Node.js | >= 22 |
| Package | @cline/core |
| WebSocket | Required for client connections |
Source: [sdk/packages/core/package.json](https://github.com/cline/cline/blob/main/sdk/packages/core/package.json)
---
## Use Cases
### Multi-Client Session Management
When running both the CLI and VS Code extension, sessions can be shared and monitored through the hub, providing a unified view of all agent activity.
### Background Task Execution
Long-running agent tasks can be executed in the background via the hub, with notifications broadcast to all connected clients when significant events occur.
### Distributed Monitoring
The Hub Monitor allows operators to observe multiple agent sessions from a single interface, enabling centralized oversight of distributed AI workflows.
### Menu Bar Integration
The Tauri-based menu bar application provides always-accessible hub monitoring without requiring a browser window, with system tray notifications for critical events.
Source: [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
---
## Related Components
| Component | Description | Location |
|-----------|-------------|----------|
| Hub Daemon | Background hub service | `sdk/packages/core/src/hub/daemon/` |
| Local Runtime Host | Local session execution | `sdk/packages/core/src/runtime/host/` |
| Hub Monitor | Web UI for hub monitoring | `sdk/apps/examples/menubar/` |
| Menu Bar Sidecar | TypeScript/Bun process for Tauri integration | `sdk/apps/examples/menubar/sidecar/` |
Source: [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
---
## See Also
- [SDK Architecture Overview](https://docs.cline.bot/sdk/architecture/overview)
- [Agent Runtime](https://docs.cline.bot/sdk/architecture/runtime)
- [Cline Hub Documentation](https://docs.cline.bot/hub)
- [@cline/core API Reference](https://docs.cline.bot/sdk/reference/cline-core)
---
## Core Components: ClineCore, Agents, and Session Management
### Related Pages
Related topics: [Hub-Spoke Architecture](#hub-spoke-model), [Code Editing Tools and File Operations](#code-editing-tools)
Related Source Files
The following source files were used to generate this page:
- [sdk/packages/core/src/ClineCore.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/ClineCore.ts)
- [sdk/packages/core/src/agent-runtime.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/agent-runtime.ts)
- [sdk/packages/core/src/runtime/orchestration/session-runtime-orchestrator.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/runtime/orchestration/session-runtime-orchestrator.ts)
- [sdk/packages/core/src/session/services/session-service.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/session/services/session-service.ts)
- [sdk/packages/core/src/session/checkpoint-restore.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/session/checkpoint-restore.ts)
- [sdk/packages/core/README.md](https://github.com/cline/cline/blob/main/sdk/packages/core/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/packages/agents/README.md](https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md)
# 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
```mermaid
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
| Responsibility | Description |
|---------------|-------------|
| Session creation | Bootstrap new agent sessions with configured providers and tools |
| Transport abstraction | Support local and remote (Hub) runtime transports |
| Lifecycle management | Handle session start, pause, resume, and disposal |
| Service operations | Expose pending prompt edits, usage lookup, and model switching |
### Creating a ClineCore Instance
```typescript
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:
| Host Type | Description |
|-----------|-------------|
| `LocalRuntimeHost` | Runs agent sessions directly in the local process |
| `HubRuntimeHost` | Connects to a remote Cline Hub instance for distributed execution |
| `RemoteRuntimeHost` | Connects to a remote runtime service |
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
```mermaid
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:
```typescript
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:
| Agent | Default Model | Purpose |
|-------|---------------|---------|
| `phantom` | `google/gemini-3-flash-preview` | Fast codebase reconnaissance—maps structure, surfaces conventions, never implements |
| `oracle` | `anthropic/claude-opus-4.6` | Opinionated planning—challenges assumptions, produces execution-ready plans |
| `anvil` | `anthropic/claude-opus-4.6` | Surgical implementation—reads before writing, stays in scope, reports exact diffs |
| `inquisitor` | `openai/gpt-5.5` | Adversarial review—finds bugs, severity-ranks findings |
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:
```typescript
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
```mermaid
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:
| Operation | Description |
|-----------|-------------|
| `checkpoint` | Serializes current session state to persistent storage |
| `restore` | Reconstructs session state from a checkpoint |
| `checkpointStatus` | Query checkpoint metadata and validity |
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
| Option | Type | Description |
|--------|------|-------------|
| `providerId` | `string` | The LLM provider identifier |
| `modelId` | `string` | The model identifier within the provider |
| `apiKey` | `string` | API key for authentication |
| `systemPrompt` | `string` | System-level instructions for the agent |
| `rules` | `Rule[]` | Agent rules to apply |
| `skills` | `Skill[]` | Skills to load for this session |
| `tools` | `Tool[]` | Additional tools beyond built-ins |
| `extensions` | `Extension[]` | Agent extensions to register |
## Integration Patterns
### Standalone CLI Usage
The CLI provides a ready-made interface built on top of ClineCore:
```bash
# Interactive session
cline
# Single prompt
cline "Audit this package and propose fixes"
# With stdin
cat file.txt | cline "Summarize this"
```
### Custom Application Integration
```typescript
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:
```typescript
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:
| Component | Primary Source File |
|-----------|---------------------|
| ClineCore | `sdk/packages/core/src/ClineCore.ts` |
| Agent Runtime | `sdk/packages/core/src/agent-runtime.ts` |
| Session Orchestrator | `sdk/packages/core/src/runtime/orchestration/session-runtime-orchestrator.ts` |
| Session Service | `sdk/packages/core/src/session/services/session-service.ts` |
| Checkpoint/Restore | `sdk/packages/core/src/session/checkpoint-restore.ts` |
## Related Documentation
- [SDK Overview](https://docs.cline.bot/sdk/overview) — General SDK documentation
- [Building an Agent](https://docs.cline.bot/sdk/guides/building-an-agent) — Step-by-step tutorial
- [API Reference](https://docs.cline.bot/sdk/reference/cline-core) — Complete API documentation
- [Architecture](https://docs.cline.bot/sdk/architecture/overview) — System-level architecture guide
---
## Code Editing Tools and File Operations
### Related Pages
Related topics: [Plan Mode and Act Mode](#plan-act-mode), [Core Components: ClineCore, Agents, and Session Management](#core-components)
Related Source Files
The following source files were used to generate this page:
- [sdk/examples/README.md](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
- [sdk/examples/plugins/typescript-lsp/index.ts](https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/index.ts)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/examples/hooks/README.md](https://github.com/cline/cline/blob/main/sdk/examples/hooks/README.md)
- [sdk/apps/examples/code-review-bot/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/code-review-bot/README.md)
# 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](./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.
```mermaid
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
| Layer | Responsibility | Location |
|-------|---------------|----------|
| Tool Definition | Declarative schema with input/output types | `@cline/agents` |
| Handler Implementation | Execution logic for each tool | `@cline/core` |
| Hook Interceptors | Pre/post execution hooks for customization | Hook system |
| Result Serialization | Normalized response format | `@cline/shared` |
Source: [sdk/packages/README.md](./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](./sdk/examples/README.md)
### Chunked Reading (v3.77.0+)
For large files, Cline supports chunked reading to avoid loading entire files into context:
```typescript
// 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:**
```mermaid
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:
```typescript
// 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](./sdk/examples/plugins/typescript-lsp/index.ts)
### Plugin Implementation Pattern
Custom tools can be registered via `createTool()` and `AgentExtension`:
```typescript
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:
```bash
#!/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](./sdk/examples/hooks/README.md)
### Hook Event Structure
| Field | Type | Description |
|-------|------|-------------|
| `tool_call.name` | string | Tool identifier |
| `tool_call.input` | object | Tool-specific parameters |
| `context` | object | Optional context injection |
## Code Review Bot Example
The code review bot demonstrates file operation tools in a real-world scenario:
```mermaid
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:**
| Tool | Purpose |
|------|---------|
| `get_file_context` | Reads full file contents for surrounding context |
| `add_review_finding` | Records structured findings from review |
| File reading | Retrieves actual PR diff and metadata |
Source: [sdk/apps/examples/code-review-bot/README.md](./sdk/apps/examples/code-review-bot/README.md)
## Configuration Options
### File Operation Limits
| Setting | Default | Description |
|---------|---------|-------------|
| `maxFileReadSize` | 1MB | Maximum file size for direct reading |
| `enableChunkedReading` | true | Allow partial file access |
| `deduplicateReads` | true | Cache repeated file access |
### 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
| Tool | Category | Primary Use Case |
|------|----------|-------------------|
| `read_file` | Reading | Content inspection |
| `write_to_file` | Writing | File creation/overwrite |
| `apply_patch` | Editing | Precise modifications |
| `search_codebase` | Search | Pattern matching |
| `goto_definition` | Navigation | Symbol resolution |
## Version History
| Version | Change |
|---------|--------|
| v3.78.0 | Show actual `read_file` line ranges in chat UI |
| v3.77.0 | Add chunked reading for targeted file access |
| v3.74.0 | Add file read deduplication cache |
---
## Plan Mode and Act Mode
### Related Pages
Related topics: [Code Editing Tools and File Operations](#code-editing-tools), [Rules and Skills System](#rules-skills)
Related Source Files
The following source files were used to generate this page:
- [apps/vscode/src/core/prompts/system-prompt/components/act_vs_plan_mode.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/prompts/system-prompt/components/act_vs_plan_mode.ts)
- [apps/vscode/src/core/prompts/system-prompt/tools/plan_mode_respond.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/prompts/system-prompt/tools/plan_mode_respond.ts)
- [apps/vscode/src/core/prompts/system-prompt/tools/act_mode_respond.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/prompts/system-prompt/tools/act_mode_respond.ts)
- [docs/core-workflows/plan-and-act.mdx](https://github.com/cline/cline/blob/main/docs/core-workflows/plan-and-act.mdx)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
# 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.
| Aspect | Plan Mode | Act Mode |
|--------|-----------|----------|
| **Primary Purpose** | Analysis, exploration, and proposal | Direct execution and implementation |
| **Tool Availability** | Limited (read-only, search) | Full tool access including write operations |
| **Workspace Changes** | Read-only | Can create, modify, and delete files |
| **Command Execution** | Disabled | Enabled with optional approval |
| **Typical Use Case** | Exploring unfamiliar codebases, understanding architecture | Implementing features, fixing bugs, refactoring |
## Architecture
The Plan/Act mode system is implemented through several interconnected components that affect system prompts, tool definitions, and runtime behavior.
```mermaid
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 analysis_only_tools]
G --> J[All tools including write and command tools]
F --> K[Proposal Output]
H --> L[Direct Execution]
```
### Core Components
| Component | File Location | Purpose |
|-----------|---------------|---------|
| Mode Decision Component | `act_vs_plan_mode.ts` | Determines current mode and applies appropriate system prompt rules |
| Plan Mode Response | `plan_mode_respond.ts` | Handles agent responses in plan mode, generates proposals |
| Act Mode Response | `act_mode_respond.ts` | Handles agent responses in act mode, enables execution |
| Documentation | `plan-and-act.mdx` | User-facing documentation for mode workflows |
## 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:
| Tool Category | Available Tools | Purpose |
|---------------|------------------|---------|
| **File Reading** | `read_file`, `read_files`, `glob` | Access file contents and project structure |
| **Search** | `search_codebase`, `grep` | Find patterns, symbols, and references |
| **Analysis** | `WebFetch`, `Read` | External research and documentation |
| **Response** | `Plan Mode Respond` | Submit analysis and proposals |
### 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:
| Tool Category | Available Tools | Purpose |
|---------------|------------------|---------|
| **File Operations** | `read_file`, `write_to_file`, `insert_content`, `create_file`, `move_file`, `delete_file` | File system manipulation |
| **Search** | `search_codebase`, `grep`, `glob` | Code exploration and navigation |
| **Execution** | `execute_command` | Run shell commands |
| **Tools** | `create_tool`, `use_tool` | Custom tool management |
| **MCP Integration** | MCP server tools | Additional capabilities via MCP |
| **Communication** | `ask`, `human_in_loop` | Request user input |
| **Response** | `Act Mode Respond` | Complete task and report results |
### 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.
```mermaid
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:
```bash
# 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
| Aspect | Plan Mode | Act Mode |
|--------|-----------|----------|
| **Output Format** | Structured proposal | Execution summary |
| **Confidence Expression** | Recommendations with caveats | Direct statements of action taken |
| **Next Steps** | Explicit suggestions | Optional follow-up recommendations |
| **Error Handling** | Analysis of potential issues | Recovery actions taken |
## Workflow Examples
### Exploratory Workflow (Plan → Act)
```mermaid
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:
| Setting | Description | Default |
|---------|-------------|---------|
| `defaultMode` | Initial mode for new sessions | `act` |
| `confirmModeSwitch` | Prompt before mode changes | `false` |
## 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:
```yaml
mode: plan # or "act"
tools: [read_files, search_codebase] # restricted in plan mode
```
## Troubleshooting
### Common Issues
| Issue | Cause | Resolution |
|-------|-------|------------|
| Agent cannot write files | Running in Plan Mode | Toggle to Act Mode |
| Commands not executing | Plan Mode restrictions | Switch modes or use Act Mode |
| Unexpected changes | Accidentally left in Act Mode | Review changes; use Plan Mode for exploration |
### 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`
---
## Provider System and Model Adapters
### Related Pages
Related topics: [MCP (Model Context Protocol) Integration](#mcp-integration)
Related Source Files
The following source files were used to generate this page:
- [apps/vscode/src/core/api/providers/types.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/api/providers/types.ts)
- [apps/vscode/src/core/api/providers/openai.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/api/providers/openai.ts)
- [apps/vscode/src/core/api/providers/anthropic.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/api/providers/anthropic.ts)
- [apps/vscode/src/core/api/providers/lmstudio.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/api/providers/lmstudio.ts)
- [sdk/packages/llms/src/providers/factory-registry.ts](https://github.com/cline/cline/blob/main/sdk/packages/llms/src/providers/factory-registry.ts)
- [sdk/packages/llms/src/catalog/README.md](https://github.com/cline/cline/blob/main/sdk/packages/llms/src/catalog/README.md)
- [sdk/packages/llms/README.md](https://github.com/cline/cline/blob/main/sdk/packages/llms/README.md)
- [sdk/packages/llms/src/catalog/models.ts](https://github.com/cline/cline/blob/main/sdk/packages/llms/src/catalog/models.ts)
- [apps/vscode/src/core/api/providers.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/api/providers.ts)
# 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
```mermaid
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:
| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique provider identifier |
| `name` | `string` | Display name for the provider |
| `models` | `number \| null` | Count of available models |
| `color` | `string` | UI color for the provider |
| `letter` | `string` | Single letter identifier |
| `enabled` | `boolean` | Whether the provider is active |
| `apiKey` | `string?` | API key for authentication |
| `oauthAccessTokenPresent` | `boolean?` | OAuth token status |
| `baseUrl` | `string?` | Custom endpoint URL |
| `defaultModelId` | `string?` | Default model selection |
| `configFields` | `ProviderConfigField[]?` | Custom configuration schema |
| `configValues` | `Record?` | Runtime configuration values |
### Configuration Field Types
Providers can define custom configuration fields with these types:
| Type | Description |
|------|-------------|
| `text` | Free-form text input |
| `password` | Secret value (masked in UI) |
| `url` | URL validation |
| `number` | Numeric input |
| `select` | Dropdown selection |
| `boolean` | Toggle switch |
## 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](https://models.dev) and generates the `catalog.generated.ts` file.
### Catalog Fields
| Field | Description | Source |
|-------|-------------|--------|
| `contextWindow` | Maximum context budget reported | `limit.context` |
| `maxInputTokens` | Prompt/input-token budget | `limit.input` or fallback to `contextWindow` |
| `maxTokens` | Maximum output tokens | `limit.output` |
### Catalog Semantics
The token-limit fields have specific semantics that developers should understand:
```text
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.
```mermaid
graph LR
Config[Provider Config] --> Registry[Factory Registry]
Registry --> Handler[Agent Handler]
Handler --> Stream[Streaming Response]
Handler --> Chunk[Usage/Metadata]
```
### Creating Handlers
```typescript
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:
```typescript
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:
```typescript
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:
| Module | Purpose |
|--------|---------|
| `@cline/llms/runtime` | Declarative config and runtime registry |
| `@cline/llms/providers` | Handler creation and provider settings |
| `@cline/llms/models` | Model catalogs and query helpers |
| `@cline/llms` (root) | Gateway registry and shared contracts |
### Package Responsibilities
| Package | Primary Responsibility | Consumers |
|---------|----------------------|-----------|
| `@cline/shared` | Path resolution, session types, indexing | `@cline/agents`, `@cline/core` |
| `@cline/llms` | Model catalog, provider settings, handler creation | `@cline/agents`, `@cline/core` |
| `@cline/agents` | Stateless agent runtime loop | `@cline/core` |
| `@cline/core` | Stateful orchestration, session storage | CLI/Desktop apps |
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
| Variable | Purpose |
|----------|---------|
| `LLMS_LIVE_PROVIDERS_PATH` | Path to live provider JSON config |
| `LLMS_LIVE_REASONING_PROVIDERS_PATH` | Path to reasoning-enabled suite |
| `LLMS_LIVE_TOOL_PROVIDERS_PATH` | Path to tool-use suites |
| `CLINE_VCR` | Set to `record` for recording |
| `CLINE_VCR_INCLUDE_REQUEST_BODY` | Include body in recordings |
### Live Assertions
Per-provider expectations can be configured:
| Option | Description |
|--------|-------------|
| `requireUsage` | Fail if no usage chunk emitted (default: true) |
| `requireCacheReadTokens` | Require cache token reads |
| `minCacheReadTokens` | Stricter cache floor check |
| `requireReasoningChunk` | Require at least one reasoning chunk |
| `requireNoReasoningChunk` | Fail if reasoning chunks present |
| `minInputTokens` / `minOutputTokens` | Enforce token lower bounds |
| `requireToolCall` | Require tool call in response |
Source: [sdk/packages/llms/README.md:100-150]()
## Webview Provider Schema
The VS Code extension's webview communicates provider data through typed interfaces:
```typescript
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
```typescript
{
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](https://github.com/cline/cline/issues) for similar reports
- Join the [Cline Discord](https://discord.gg/cline) for community support
---
## MCP (Model Context Protocol) Integration
### Related Pages
Related topics: [Provider System and Model Adapters](#provider-system)
Related Source Files
The following source files were used to generate this page:
- [apps/vscode/src/services/mcp/McpHub.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/services/mcp/McpHub.ts)
- [apps/vscode/src/services/mcp/types.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/services/mcp/types.ts)
- [apps/vscode/src/core/controller/mcp/subscribeToMcpServers.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/controller/mcp/subscribeToMcpServers.ts)
- [docs/mcp/mcp-overview.mdx](https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [sdk/packages/core/package.json](https://github.com/cline/cline/blob/main/sdk/packages/core/package.json)
# 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.
```mermaid
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
| Component | Responsibility | Location |
|-----------|---------------|----------|
| McpHub | Central service managing MCP server lifecycle, tool discovery, and request routing | `apps/vscode/src/services/mcp/McpHub.ts` |
| McpTypes | Type definitions and interfaces for MCP communication | `apps/vscode/src/services/mcp/types.ts` |
| McpSubscription | Handles real-time server state updates and notifications | `apps/vscode/src/core/controller/mcp/subscribeToMcpServers.ts` |
| MCP Client Library | Protocol implementation for server communication | Bundled dependency |
### 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:
```typescript
// Core type structure from types.ts
interface McpServer {
id: string;
name: string;
command: string;
args?: string[];
env?: Record;
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:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique identifier for the server |
| `name` | string | Yes | Display name shown in the UI |
| `command` | string | Yes | Executable path or command to start the server |
| `args` | string[] | No | Command-line arguments passed to the server |
| `env` | Record | No | Environment variables for the server process |
| `enabled` | boolean | No | Whether the server is active (default: true) |
### Settings Storage
Server configurations are persisted to `providers.json` in the Cline data directory:
```json
{
"mcpServers": [
{
"id": "filesystem",
"name": "Filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"enabled": true
}
]
}
```
## MCP Tool Integration
### Tool Discovery Flow
```mermaid
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:
```typescript
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
| Practice | Rationale |
|----------|-----------|
| Use absolute paths for commands | Prevents PATH resolution issues |
| Limit concurrent servers | Reduces resource consumption and debugging complexity |
| Enable servers incrementally | Simplifies troubleshooting when issues arise |
| Document custom server configurations | Aids team collaboration and reproducibility |
### 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](https://modelcontextprotocol.io)
- [Official MCP Servers](https://github.com/modelcontextprotocol/servers)
- [Cline MCP Documentation](https://docs.cline.bot/mcp/overview)
## Related Documentation
- [CLI MCP Usage](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md) - MCP support in the CLI application
- [Provider Schema Types](https://github.com/cline/cline/blob/main/sdk/apps/cline-hub/src/webview/src/lib/provider-schema.ts) - Interface definitions for provider integration
---
## Rules and Skills System
### Related Pages
Related topics: [Plan Mode and Act Mode](#plan-act-mode)
Related Source Files
The following source files were used to generate this page:
- [apps/vscode/src/core/context/instructions/user-instructions/cline-rules.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/context/instructions/user-instructions/cline-rules.ts)
- [apps/vscode/src/core/context/instructions/user-instructions/skills.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/context/instructions/user-instructions/skills.ts)
- [sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts)
- [docs/customization/cline-rules.mdx](https://github.com/cline/cline/blob/main/docs/customization/cline-rules.mdx)
- [docs/customization/skills.mdx](https://github.com/cline/cline/blob/main/docs/customization/skills.mdx)
- [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/agents-squad/README.md)
- [sdk/examples/cron/README.md](https://github.com/cline/cline/blob/main/sdk/examples/cron/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
# 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](https://github.com/cline/cline/blob/main/sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts)
## Architecture
```mermaid
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:
| Package | Responsibility |
|---------|----------------|
| `@cline/core` | Stateful runtime orchestration, session lifecycle, local and hub runtime services |
| `@cline/agents` | Stateless agent runtime loop including tools, hooks, extensions, teams, streaming |
| `@cline/shared` | Cross-package shared primitives including session common types |
| `@cline/llms` | Model catalog and provider settings schema |
Source: [sdk/packages/README.md](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/blob/main/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:
| Skill | Purpose |
|-------|---------|
| API Design | Guidelines for designing clean, consistent APIs |
| Code Review | Standards for reviewing pull requests and code changes |
| Debugging | Systematic approaches to identifying and fixing issues |
| Documentation | Best practices for writing and maintaining docs |
| Migration | Strategies for upgrading codebases and dependencies |
| Refactoring | Patterns for improving code structure safely |
| Test Generation | Techniques for creating effective tests |
Source: [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/agents-squad/README.md)
### Skill Discovery
The SDK provides tools for discovering and loading skills at runtime:
| Tool | Description |
|------|-------------|
| `list_skills` | List all available bundled, global, and project skills |
| `get_skill` | Load and retrieve instructions for a specific skill |
Source: [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/blob/main/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](https://github.com/cline/cline/blob/main/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:
| Agent | Model | Role | Primary Skills |
|-------|-------|------|----------------|
| `phantom` | `google/gemini-3-flash-preview` | Fast codebase recon — maps structure, surfaces conventions, never implements | Documentation, Code Review |
| `oracle` | `anthropic/claude-opus-4.6` | Opinionated planning — challenges assumptions and produces execution-ready plans | API Design, Migration |
| `anvil` | `anthropic/claude-opus-4.6` | Surgical implementation — reads before writing, stays in scope, reports exact diffs | Refactoring, Test Generation |
| `inquisitor` | `openai/gpt-5.5` | Adversarial review — finds bugs, severity-ranks findings | Debugging, Code Review |
Source: [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/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:
```yaml
---
id: daily-code-review
title: Daily Code Review
workspaceRoot: /path/to/repo
schedule: "0 9 * * MON-FRI"
tools: read_files,run_commands
mode: act
timeoutSeconds: 1800
extensions:
- rules
- skills
---
```
### Automation Fields
| Field | Type | Description |
|-------|------|-------------|
| `extensions` | array | Extensions to load including `rules` and `skills` |
| `tags` | array | Arbitrary tags for grouping |
| `metadata` | object | Custom metadata |
| `modelSelection` | object | Override model/provider for the automation |
| `maxIterations` | number | Iteration limit |
| `timeoutSeconds` | number | Run timeout |
Source: [sdk/examples/cron/README.md](https://github.com/cline/cline/blob/main/sdk/examples/cron/README.md)
## User Instruction Configuration
The unified configuration loader orchestrates all instruction sources:
```typescript
interface UserInstructionConfig {
rules: Rule[];
skills: Skill[];
globalRules?: Rule[]; // Enterprise global
globalSkills?: Skill[]; // Enterprise global
}
```
The loader combines local configuration with remote enterprise settings, respecting `alwaysEnabled` flags for mandatory enterprise rules and skills.
Source: [sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts)
## Usage Patterns
### Enabling Rules for a Project
1. Create `.cline/rules/` directory in the project root
2. Add `.md` files with behavioral directives
3. Toggle rules on/off using the VS Code extension UI or CLI
### Using Skills with Subagents
The agents-squad plugin enables skill loading in subagent workflows:
```typescript
// List available skills
const skills = await tools.list_skills();
// Get specific skill instructions
const apiDesignSkill = await tools.get_skill("api-design");
// Use with subagent
await tools.start_subagent({
task: "Design a REST API for the user service",
skills: ["api-design", "documentation"]
});
```
Source: [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/agents-squad/README.md)
### Enterprise Deployment
Administrators configure `globalSkills` in the remote configuration:
```json
{
"globalSkills": [
{
"id": "enterprise-security",
"name": "Enterprise Security Guidelines",
"content": "...",
"alwaysEnabled": true
},
{
"id": "code-style",
"name": "Code Style Guide",
"content": "...",
"alwaysEnabled": false
}
]
}
```
Users see enterprise skills in the UI under "Enterprise Skills" section, with locked indicators for `alwaysEnabled` skills.
## Best Practices
### Writing Effective Rules
- Use clear, actionable language
- Focus on constraints rather than general guidance
- Keep rules focused on specific behaviors
- Use concrete examples where helpful
### Organizing Skills
- One skill per file with comprehensive coverage
- Include examples and edge cases
- Update skills when tools or workflows change
- Leverage the appropriate skill for each task type
### Enterprise Configuration
- Use `alwaysEnabled` sparingly for critical compliance requirements
- Provide optional skills users can enable as needed
- Document skill purposes in the enterprise knowledge base
- Version skills to track changes over time
## Related Documentation
- [ClineRules Documentation](https://github.com/cline/cline/blob/main/docs/customization/cline-rules.mdx)
- [Skills Documentation](https://github.com/cline/cline/blob/main/docs/customization/skills.mdx)
- [Architecture Overview](https://docs.cline.bot/sdk/architecture/overview)
- [SDK Reference](https://docs.cline.bot/sdk/reference/cline-core)
---
---
## Pitfall Log
Project: cline/cline
Summary: 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
## 13. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: ACP new sessions do not persist last selected provider/model in Zed on Windows
- User impact: Developers may fail before the first successful local run: ACP new sessions do not persist last selected provider/model in Zed on Windows
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: ACP new sessions do not persist last selected provider/model in Zed on Windows. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_9781d06dd135650eb7443b989cb3f119 | https://github.com/cline/cline/issues/11130
## 14. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: CLI v3.0.12
- User impact: Upgrade or migration may change expected behavior: CLI v3.0.12
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: CLI v3.0.12. Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_b3c36610dc82ecf1b5b3517bd705ce71 | https://github.com/cline/cline/releases/tag/cli-v3.0.12
## 15. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: CLI v3.0.15
- User impact: Upgrade or migration may change expected behavior: CLI v3.0.15
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: CLI v3.0.15. Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_50a911befc28c5946ad67615c88a1a9c | https://github.com/cline/cline/releases/tag/cli-v3.0.15
## 16. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Context mentions menu can't find @ files (since upgrading VS Code)
- User impact: Developers may fail before the first successful local run: Context mentions menu can't find @ files (since upgrading VS Code)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Context mentions menu can't find @ files (since upgrading VS Code). Context: Observed when using windows, linux, cuda
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_14575f606192f4b17f8e3d2cebdf56bd | https://github.com/cline/cline/issues/11105
## 17. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Feature: Add Clarvia MCP quality scorer to recommended MCP servers
- User impact: Developers may fail before the first successful local run: Feature: Add Clarvia MCP quality scorer to recommended MCP servers
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature: Add Clarvia MCP quality scorer to recommended MCP servers. Context: Observed when using node
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_e1aadce51a7a5c20910d8bdb03189ff4 | https://github.com/cline/cline/issues/10068
## 18. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)
- User impact: Developers may fail before the first successful local run: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails). Context: Observed when using linux
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_8bb8953b67d872dd363792a46908cff3 | https://github.com/cline/cline/issues/11142
## 19. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.
- User impact: Developers may misconfigure credentials, environment, or host setup: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.. Context: Observed when using linux
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_61bfcf097e3bc5ac5df144e36437977c | https://github.com/cline/cline/issues/10307
## 20. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: CLI v3.0.14
- User impact: Upgrade or migration may change expected behavior: CLI v3.0.14
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: CLI v3.0.14. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_181eada2a9a95163185cbcdbc5a47806 | https://github.com/cline/cline/releases/tag/cli-v3.0.14
## 21. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x
- User impact: Developers may misconfigure credentials, environment, or host setup: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_57686ab9dad083e9954799704bf50191 | https://github.com/cline/cline/issues/10596
## 22. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Impossible to scroll in JetBrains Plugin
- User impact: Developers may misconfigure credentials, environment, or host setup: Impossible to scroll in JetBrains Plugin
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Impossible to scroll in JetBrains Plugin. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_6ef867741fe2d3345a1c5467be125a51 | https://github.com/cline/cline/issues/11155
## 23. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Improve Context Window Management and Large File Handling
- User impact: Developers may misconfigure credentials, environment, or host setup: Improve Context Window Management and Large File Handling
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Improve Context Window Management and Large File Handling. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_c936cab419cb3037e1df613bd0c97bcd | https://github.com/cline/cline/issues/4389
## 24. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:824874689 | https://github.com/cline/cline
## 25. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_157e6dc53c3148fca716c7b3ada09b60 | https://github.com/cline/cline/issues/11016
## 26. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:824874689 | https://github.com/cline/cline
## 27. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:824874689 | https://github.com/cline/cline
## 28. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:824874689 | https://github.com/cline/cline
## 29. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Add HVTracker badge to README?
- User impact: Developers may hit a documented source-backed failure mode: Add HVTracker badge to README?
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Add HVTracker badge to README?. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_c8c4e917c948a42b250ca448b2c229c8 | https://github.com/cline/cline/issues/11157
## 30. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Large files can cause conversations to break
- User impact: Developers may hit a documented source-backed failure mode: Large files can cause conversations to break
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Large files can cause conversations to break. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_653d8452f6a5c6525969e8aeb1216f1b | https://github.com/cline/cline/issues/5251
## 31. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: lm studio issues
- User impact: Developers may hit a documented source-backed failure mode: lm studio issues
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: lm studio issues. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_4e45923ce0454787fbe338d5fe53f0e3 | https://github.com/cline/cline/issues/11158
## 32. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: Clarvia AEO Score: Quality validation for MCP servers used in Cline
- User impact: Developers may hit a documented source-backed failure mode: Clarvia AEO Score: Quality validation for MCP servers used in Cline
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_543ddc6639f5043c5242d99bc0611c69 | https://github.com/cline/cline/issues/10076
## 33. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: keeps engaging in endless self-reasoning without asking any questions
- User impact: Developers may hit a documented source-backed failure mode: keeps engaging in endless self-reasoning without asking any questions
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_b0ae7b74b9b2456e9444709e2a1d1453 | https://github.com/cline/cline/issues/11154
## 34. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:824874689 | https://github.com/cline/cline
## 35. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:824874689 | https://github.com/cline/cline