Related Pages

Related topics: Lib

Overview

Cline is an autonomous coding agent that runs as a desktop, terminal, and IDE-integrated assistant. The repository distributes a shared engine across multiple product surfaces — an SDK, a CLI, a VS Code extension, and a JetBrains plugin — all backed by the same core runtime, model catalog, and plugin system.

Purpose and Product Surfaces

The repository is organized as a monorepo with a top-level product matrix. According to README.md, Cline is described as a coding agent that can run terminal commands, edit files, use a browser, and connect to MCP servers, with the same engine powering every surface. The product index lists four deliverables:

This matrix is reflected in the README.md product index, which links to per-product changelogs and source directories. The repository's package.json pins the toolchain to [email protected] and node>=22, signaling a TypeScript-first, ESM build that targets modern runtimes Source: [package.json].

SDK Architecture

The SDK is the programmatic entry point. It is composed of four internal packages, each with a single responsibility Source: [sdk/packages/README.md]:

• @cline/shared — cross-package primitives (path resolution, session types, indexing helpers)
• @cline/llms — model catalog, provider settings schema, handler creation
• @cline/agents — stateless agent runtime loop (tools, hooks, extensions, teams, streaming)
• @cline/core — stateful runtime orchestration (session lifecycle, storage, local and hub runtime services)

The dependency direction flows from llms → agents → core, with core consumed by the CLI and desktop apps. Hub services in @cline/core orchestrate scheduled execution, execution history, and schedule command handling Source: [sdk/packages/README.md].

The model catalog inside @cline/llms is generated from models.dev via catalog-live.ts and written to catalog.generated.ts by scripts/generate-models.ts. It normalizes provider limit.context, limit.input, and limit.output into ModelInfo fields (contextWindow, maxInputTokens, maxTokens). These are not additive — maxInputTokens + maxTokens is allowed to exceed contextWindow because the request still has to fit the provider's own rules Source: [sdk/packages/llms/src/catalog/README.md].

flowchart LR
  shared["@cline/shared"] --> llms["@cline/llms"]
  llms --> agents["@cline/agents"]
  shared --> agents
  agents --> core["@cline/core"]
  shared --> core
  llms --> core
  core --> CLI["apps/cli"]
  core --> VSCode["VS Code Extension"]
  core --> JetBrains["JetBrains Plugin"]
  core --> SDK["@cline/sdk consumers"]

The @cline/core package declares dependencies on ws and zod, with Node ≥ 22 as the runtime engine Source: [sdk/packages/core/package.json].

Plugins, Hooks, and Automation

The SDK exposes a plugin model where each plugin declares capabilities in its manifest and receives a typed api in setup(). According to sdk/examples/plugins/README.md, declaring a capability unlocks part of that API:

The CLI auto-discovers plugins from .cline/plugins in the workspace, ~/.cline/plugins, and the system Plugins folder. Plugins can be installed from local files, GitHub URLs, package directories, git repos, or npm packages with cline plugin install Source: [sdk/examples/plugins/README.md].

Notable shipped examples include the TypeScript LSP plugin (resolves symbol definitions through the target project's own TypeScript Language Service) and the Agents Squad plugin, which spawns background subagents with shared agent presets (Anvil, Inquisitor, Oracle, Phantom) and a ~/.cline/data/plugins/subagents/handoffs/<conversationId>/ handoff store Source: [sdk/examples/plugins/typescript-lsp/README.md, sdk/examples/plugins/agents-squad/README.md].

Scheduled and event-driven automation is configured through file-based specs in ~/.cline/cron/. Recurring jobs use schedule (cron expression) and timezone; event-driven specs use event, filters, debounceSeconds, dedupeWindowSeconds, cooldownSeconds, and maxParallel Source: [sdk/examples/cron/README.md].

Applications and Common Failure Modes

The apps/examples/ directory contains runnable reference applications ordered from simple to complex — a quickstart (~15 lines), cli-agent (multi-turn terminal chat), multi-agent (four specialist agents streamed over SSE), and code-review-bot (real GitHub PR review with three custom tools) Source: [apps/examples/README.md, apps/examples/multi-agent/README.md, apps/examples/code-review-bot/README.md].

Community-reported issues cluster around a few recurring failure modes that an overview should call out:

• Hangs at "Thinking..." after terminal execution or when running interactive commands like git diff that open a pager (issues #10537, #10853, #10931).
• Auth and TLS problems in the CLI: corporate CA bundles failing TLS verification (#11175), AWS Bedrock credential_process profile auth (#10930), and Azure AI Foundry profile auth regression in 3.0.15 (#11237).
• Provider compatibility: reasoning: {exclude: true} being injected for GLM models on OpenAI-compatible endpoints that reject unknown fields (#11086), and Ollama returning HTTP 400/500 with an infinite JSON tool loop on non-tool models (#11263).
• IDE integration drift: Cline's Activity Bar icon disappearing in VS Code (#11292), and JetBrains PowerShell misinterpreting /d /s /c flags (#11290).
• Licensing clarity between the Apache 2.0 source and the service ToS (#3510), and long-standing requests for additional IDE support such as VS 2022 (#63).

These are tracked alongside an apiRequest hang pattern reported against Deepseek v3 (#1157) and a multi-directory workspace file-picker limitation (#653). The most recent CLI release (v3.0.20) renames installed plugin wrappers to their source identity — npm name, git repo, remote filename, official slug, or local directory — instead of an opaque hash, addressing one of the recurring usability complaints.

See Also

• Package responsibilities and runtime flows
• Model catalog semantics
• Plugin examples and capabilities
• Cron and event-driven automation
• Runnable SDK examples

Related Pages

Related topics: Overview, Lib

Lib

The lib/ directory inside apps/cline-hub/src/webview/src/ is the shared utility and integration layer for the Cline Hub webview (the Tauri desktop shell's frontend). It concentrates everything the UI components need to talk to the host runtime, resolve providers and models, and normalize data shapes for display. Because the webview is a thin React layer, all transport, validation, and selection logic lives here so that view components remain declarative. Source: apps/cline-hub/src/webview/src/lib/desktop-client.ts.

Purpose and Scope

The lib module exists to isolate three concerns that would otherwise leak into React components:

1. Host bridge — A typed wrapper around the Tauri/RPC boundary so the webview can call Cline Hub services without scattering invoke() calls across components.
2. Provider and model resolution — Helpers that normalize provider identifiers, look up model metadata, and validate user-entered configuration against a schema.
3. Presentation utilities — Small, pure helpers used by multiple components (formatting, type guards, ID parsing).

The Hub is a desktop-runtime variant of the Cline stack described in the top-level README.md, and the webview consumes the same provider catalog and runtime abstractions documented in the sdk/packages/README.md.

Module Breakdown

Desktop Client Bridge

desktop-client.ts exposes a thin client used by the webview to call into the Tauri host. It hides RPC details and returns strongly typed results, which lets components stay focused on rendering. The Hub webview follows the same separation of concerns described for the desktop app example in the SDK repo, where a Bun sidecar (or comparable runtime) is the single source of truth. Source: apps/cline-hub/src/webview/src/lib/desktop-client.ts.

Model Selection

model-selection.ts encapsulates the logic of resolving which providerId and modelId a user is currently configured with, including how selection propagates across the webview and which defaults apply when a field is missing. This module is the first line of defense against the "API request loading indefinitely" class of bugs reported in issues like cline/cline#1157, where the request hangs because the resolved model does not actually support the requested capability. Source: apps/cline-hub/src/webview/src/lib/model-selection.ts.

Provider Identity

provider-id.ts provides normalization for provider identifiers (case, alias mapping, and validation). Centralizing this avoids the kind of mismatches that surface in community reports where the GUI and CLI behave differently for the same provider (see cline/cline#11237 for Azure AI Foundry and cline/cline#10930 for AWS Bedrock profile authentication). Source: apps/cline-hub/src/webview/src/lib/provider-id.ts.

Provider Model Catalog and Schema

provider-model-catalog.ts and provider-schema.ts are the user-facing surface of the normalized catalog defined in sdk/packages/llms/src/catalog. The webview uses the schema to validate provider configuration forms before they are sent to the runtime, and the catalog to populate selectors. Together they prevent malformed configuration from reaching the agent loop — a class of failure that appears in issues such as the Ollama tool-loop bug (cline/cline#11263) and the GLM reasoning field injection (cline/cline#11086). Source: apps/cline-hub/src/webview/src/lib/provider-model-catalog.ts, apps/cline-hub/src/webview/src/lib/provider-schema.ts.

Utility Helpers

utils.ts collects generic, presentation- and UI-level helpers (formatters, guards, and small id/parsing routines) shared across webview components. It intentionally avoids business logic; that lives in the dedicated modules above so that the dependency direction is one-way (UI → utils → domain modules → desktop client → runtime). Source: apps/cline-hub/src/webview/src/lib/utils.ts.

Architecture and Data Flow

The webview's request path goes through lib/ in a predictable sequence: a UI event triggers a call into model-selection.ts and/or provider-schema.ts to validate the user's intent; the call is then dispatched through desktop-client.ts to the Tauri host, which delegates to the runtime packages described in sdk/packages/. Responses flow back to the same modules, which normalize data before components re-render.

flowchart LR
    UI[React UI Components] -->|user input| Lib
    Lib[lib/ modules] -->|validate| Schema[provider-schema.ts]
    Lib -->|resolve| Selection[model-selection.ts]
    Lib -->|dispatch| Desktop[desktop-client.ts]
    Desktop -->|RPC| Host[Tauri / Cline Hub runtime]
    Host -->|response| Desktop
    Desktop --> Lib
    Lib -->|normalized state| UI

This separation makes it straightforward to mock the runtime in tests and to swap the transport (for example, to a VS Code webview) without rewriting components. The same layered pattern is used by the example VS Code app, which "runs Cline sessions over the RPC runtime" (see the SDK examples index in sdk/README.md).

Failure Modes and Community Context

The lib layer exists in part to surface and contain errors before they become user-visible hangs or crashes. Several recurring community issues map directly onto responsibilities owned here:

Because all of these manifests at the webview layer first, the lib modules are the right place to add guard rails, validation messages, and observability. Any fix in this area should ideally ship with a test that exercises the relevant helper (for example, a test in provider-schema.ts that rejects the offending payload before it is sent to the runtime).

See Also

• Cline SDK overview
• SDK packages and architecture
• Model catalog semantics
• Plugin examples
• Cline Hub examples (multi-agent, code review)

Related Pages

Related topics: Lib

Src

The "Src" topic covers the source code organization of the Cline monorepo — specifically the src directories inside the SDK packages, the generated catalog source, and how the project tree relates to published artifacts, examples, and tooling. This page is bounded to what is explicitly documented in the repository and the top-level layout surfaces that drive it.

Repository Layout and Build Engine

The repository is an ESM-first monorepo pinned to [email protected] and requires Node.js >=22 (see package.json). It uses vitest for tests and @biomejs/biome for linting. The packageManager field is committed so that contributors and CI resolve the same toolchain.

At the top level, the monorepo is partitioned by product surface:

Source: README.md.

SDK `src` Tree by Package

The SDK is split into four packages, each with its own src/ implementation directory. Package responsibilities are explicitly enumerated in sdk/packages/README.md:

The interaction order is: @cline/llms defines model/provider capabilities and builds concrete handlers; @cline/agents runs the agent loop on top of those handlers; @cline/core composes runtime behavior with persistent sessions, storage, and local or hub-backed services; hub services orchestrate scheduled runtime execution, history, and schedule command handling. Source: sdk/packages/README.md.

The @cline/core package ships TypeScript build output and .d.ts types — its files manifest restricts the published tarball to dist, explicitly excluding *.d.ts.map artifacts (see sdk/packages/core/package.json). It declares node >=22 and depends on ws, yaml, and zod for its public surface.

The `src/catalog` Subtree

The most heavily documented source subtree in the repository is sdk/packages/llms/src/catalog/. The generated file catalog.generated.ts is the SDK's normalized copy of provider and model metadata, and most of its built-in data flows from models.dev through catalog-live.ts, which is then written to catalog.generated.ts by scripts/generate-models.ts. Source: sdk/packages/llms/src/catalog/README.md.

The catalog normalizes models.dev limit fields into ModelInfo fields:

limit.context  -> contextWindow   (provider-reported context budget)
limit.input    -> maxInputTokens  (prompt/input-token budget for compaction & diagnostics)
limit.output   -> maxTokens       (provider-reported output-token budget)

These are not additive guarantees. A valid record can read contextWindow: 200000, maxInputTokens: 200000, maxTokens: 128000, meaning the prompt may approach 200k tokens and the model may emit up to 128k tokens in a single request. The catalog's job is to preserve source metadata; runtime request policy should be conservative and observable. Related files in the subtree are listed as catalog-live.ts, catalog-live.test.ts, catalog.generated.ts, and the consumer providers ../providers/ai-sdk.ts and ../providers/gateway.ts.

Regeneration uses the per-package script:

bun -F @cline/llms generate:models

flowchart LR
  A[models.dev] --> B[src/catalog/catalog-live.ts]
  B --> C[scripts/generate-models.ts]
  C --> D[src/catalog/catalog.generated.ts]
  D --> E[@cline/agents and @cline/core]

Examples, Plugins, and Cron as `src` Neighbours

Runnable examples and plugins live in two trees that complement the SDK source. sdk/examples/ contains plugin, hook, automation, and cron examples; apps/examples/ contains end-to-end apps (Quickstart, CLI Agent, Code Review Bot, Multi-Agent War Room, Desktop App, VS Code extension example). Both trees have their own package.json and README, and they consume the SDK via the build artifact produced from the src/ trees. Source: sdk/examples/README.md, apps/examples/README.md.

Within sdk/examples/plugins/, the manifests declare capabilities that unlock parts of the api passed to setup(): tools, commands, rules, skills, providers, messageBuilders, automationEvents, and hooks. The setup ctx may include session, client, user, workspaceInfo, automation, logger, and telemetry depending on the host. Source: sdk/examples/plugins/README.md.

Notable example modules include typescript-lsp/index.ts (a goto_definition tool that wraps the TypeScript Language Service — see sdk/examples/plugins/typescript-lsp/README.md) and agents-squad/, which adds background subagent orchestration tools, bundled agent presets (Anvil, Inquisitor, Oracle, Phantom), and skills (code-review, test-generation, refactoring, debugging, api-design, migration, documentation) — see sdk/examples/plugins/agents-squad/README.md.

Working With `src` Locally

Most examples assume a built SDK and require a recent Node.js:

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

For plugin-style examples the CLI auto-discovers plugins from .cline/plugins in the workspace, ~/.cline/plugins, and the system Plugins folder, and cline plugin install accepts local files, GitHub file URLs, package directories, git repos, and npm packages. Source: sdk/examples/plugins/README.md, apps/examples/README.md.

Common Failure Modes Around `src` Artifacts

Several recurring community issues map onto the source/runtime boundary described in this page:

• Hangs at "Thinking..." after a terminal command (issue #10537, issue #10853) and on interactive pagers like git diff (issue #10931) — symptoms of a stuck agent loop in @cline/agents/src rather than the catalog source.
• CLI Bedrock credential_process auth failure (issue #10930) and Azure AI Foundry profile breakage in CLI 3.0.15 (issue #11237) — provider-handler regressions in @cline/llms/src/providers/.
• Ollama infinite JSON tool loop and HTTP 400/500 on non-tool/streamed models (issue #11263) — handler/schema mismatches in the AI SDK bridge, touched by the ai-sdk.ts consumer of catalog.generated.ts.
• PowerShell mis-parsing /d /s /c claude (issue #11290) — shell-construction logic in the CLI, not the SDK src trees.
• reasoning: {exclude: true} field leaked to OpenAI-compatible providers (issue #11086) — a normalization gap in the live catalog code path src/catalog/catalog-live.ts.

See Also

• SDK Overview — entry point for @cline/sdk consumers.
• Packages Overview — package-level responsibilities and internal dependencies.
• Model Catalog Semantics — src/catalog field mapping and generation script.
• Plugin Examples — capability table, runtime hooks, and CLI install flows.
• Cron & Event Examples — scheduled and event-driven spec formats.

Doramagic Pitfall Log

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

1. Installation risk: Installation risk requires verification

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

2. Installation risk: Installation risk requires verification

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

3. Configuration risk: Configuration risk requires verification

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

4. Configuration risk: Configuration risk requires verification

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

5. Configuration risk: Configuration risk requires verification

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

6. Maintenance risk: Maintenance risk requires verification

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

7. Maintenance risk: Maintenance risk requires verification

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

8. Maintenance risk: Maintenance risk requires verification

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

9. Maintenance risk: Maintenance risk requires verification

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

10. Maintenance risk: Maintenance risk requires verification

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

11. Maintenance risk: Maintenance risk requires verification

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

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

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: CLI Bedrock profile auth fails with AWS credential_process
• User impact: Developers may expose sensitive permissions or credentials: CLI Bedrock profile auth fails with AWS credential_process
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: CLI Bedrock profile auth fails with AWS credential_process. Context: Observed when using macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/cline/cline/issues/10930

Community Discussion Evidence

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

• Cline ask question but dont have any answer - github / github_issue
• Add API Key field to LM Studio provider for authenticated servers - github / github_issue
• Claude Code provider fails to connect with Claude Code CLI 2.1.163: comm - github / github_issue
• Deadlock on remote-SSH after terminal commands - github / github_issue
• Task command failed at http://127.0.0.1:3484: fetch failed - github / github_issue
• Cline hangs indefinitely - github / github_issue
• Cline v3.82.0 hangs indefinitely at "Thinking..." after executing termin - github / github_issue
• Cline hangs indefinitely when interactive CLI commands (like default "gi - github / github_issue
• Error: unable to get local issuer certificate with Internal CA - github / github_issue
• Installation risk requires verification - GitHub / issue
• Maintenance risk requires verification - GitHub / issue
• Maintenance risk requires verification - GitHub / issue