AGENTS.md

1---
2description: Development reference for the Cline SDK workspace.
3globs: "*.ts,*.tsx,*.js,*.jsx,*.json,*.md"
4alwaysApply: true
5---
6 
7# Cline SDK — Development Reference
8 
9Quick-reference for active development. For onboarding, workspace setup, publishing, and detailed workflow see [CONTRIBUTING.md](./CONTRIBUTING.md). For architecture and runtime flows see [ARCHITECTURE.md](./ARCHITECTURE.md). For API details see [DOC.md](./DOC.md).
10 
11## Repository Scope
12 
13This file applies to the SDK workspace rooted at this directory (`sdk/`). In this repo, "root" means the SDK workspace root unless explicitly stated otherwise. Ignore the legacy repository root for SDK development except for Git operations or repo-wide searches that are explicitly needed.
14 
15Run SDK commands from `sdk/`, not from the legacy repository root. Do not run direct root-level commands such as `bun test sdk/...`; they bypass the SDK workspace setup and can fail to resolve `workspace:*` packages correctly.
16 
17## Package Boundaries
18 
19### Published SDK Packages
20 
21- `@cline/shared`: shared contracts, schemas, path helpers, hook engine, extension registry, low-level utilities
22- `@cline/llms`: provider settings/config, model catalogs, provider manifests, gateway contracts, handler creation
23- `@cline/agents`: stateless agent loop, tool orchestration, hook/extension runtime, event streaming
24- `@cline/core`: stateful orchestration, session lifecycle, storage, config watching, plugin loading, default tools, telemetry. Exposes `@cline/core/hub` for discovery, the detached daemon entry, WebSocket clients, and session/UI client adapters, plus `@cline/core/hub/daemon-entry` for launching the shared daemon
25 
26### Dependency Direction
27 
28```mermaid
29flowchart TD
30  shared["@cline/shared"] --> llms["@cline/llms"] & agents["@cline/agents"] & core["@cline/core"]
31  llms --> agents & core
32  agents --> core
33  core --> apps["CLI / VS Code / Code App"]
34```
35 
36Rules:
37- `shared` stays low-level and reusable
38- `agents` stays stateless — no session/storage/config concerns
39- `core` owns stateful orchestration, including the shared-hub daemon, server, and client adapters under `src/hub/`
40 
41## Change Routing
42 
43Route changes to the package that owns the concern:
44 
45- model/provider schemas or handler behavior: `@cline/llms`
46- stateless loop, tool orchestration, streaming, hook/extension runtime: `@cline/agents`
47- session lifecycle, storage, config watching, default tools, plugin loading, telemetry, hub runtime services, hub discovery, hub daemon spawn, and session-oriented client helpers (`HubSessionClient`, `HubUIClient`, `connectToHub`): `@cline/core` (hub pieces live under `src/hub/`)
48- remote-config schemas, managed instruction materialization, blob upload metadata, and OpenTelemetry config normalization: `@cline/shared/src/remote-config`
49- host-specific UX or shell behavior: app package
50 
51## Verifying Changes
52 
53Before testing in a fresh worktree, install SDK dependencies from the SDK workspace root:
54 
55```sh
56cd sdk
57bun install --frozen-lockfile
58```
59 
60SDK package exports resolve sibling packages through compiled `dist/` files. If `dist/` is missing, build the SDK packages before running package tests:
61 
62```sh
63bun run build:sdk
64```
65 
66SDK-root commands for cross-package confidence:
67 
68```sh
69bun run types       # typecheck all packages
70bun run test        # run all tests
71bun run check       # lint + build + typecheck + check-publish
72```
73 
74For focused verification, prefer workspace package scripts from the SDK root:
75 
76```sh
77bun -F @cline/shared test
78bun -F @cline/llms test
79bun -F @cline/agents test
80bun -F @cline/core test:unit
81bun -F @cline/cli test:unit
82```
83 
84If a focused test command fails with a missing `@cline/*` export or missing `dist/` file, build the relevant dependency package or run `bun run build:sdk`, then rerun the same test command. Treat that as a workspace setup issue, not as evidence of a source-code bug.
85 
86If you touch hub/bootstrap/session flows, please update `ARCHITECTURE.md`.
87 
88## Practical Guidance
89 
90### Keep Boundaries Clean
91 
92- Don't move stateful logic down into `agents`
93- For `@cline/llms` provider/model routing rules, follow [packages/llms/AGENTS.md](./packages/llms/AGENTS.md).
94- Don't put app-specific behavior into `core` unless it is truly shared host behavior
95- Keep remote-config primitives generic in `shared`; host-facing session integration belongs in `core`
96 
97### Refactor Standard
98 
99- Prefer direct architectural cleanup over compatibility shims
100- Move code to the layer that owns the concern and update all call sites
101- If a helper just projects watcher state, keep it with the config layer instead of creating thin runtime wrappers
102 
103## Documentation Responsibilities
104 
105- `README.md`: visitor-facing overview. Update when the repo story or package inventory changes.
106- `CONTRIBUTING.md`: onboarding, workflow, publishing. Update when contributor setup or release process changes.
107- `AGENTS.md` (this file): development reference. Update when package boundaries, dependency rules, or change routing changes.
108- `ARCHITECTURE.md`: design, boundaries, runtime flows. Update when system design or architectural constraints change.
109- `DOC.md`: API and behavior reference. Update when exported surfaces, lifecycle semantics, or runtime behavior changes.
110