mirror of
https://github.com/cline/cline.git
synced 2026-09-21 13:21:23 +08:00
Saoud RizwanandSaoud Rizwan
eef7958cad
* fix(core): keep hub session status truthful across queue-drained turns Queue-drained turns settle only through the event stream, but the hub runtime host mistranslated their lifecycle in two ways: - session.updated events carrying only a snapshot (persistence updates) defaulted the projected status to "running". When one trailed the final idle update after a turn, clients that track busy state from status events (the desktop sidecar's workspace restore gate) stayed busy forever. Use the snapshot's real status and emit nothing when neither source reports one. - the per-run agent.done dedup was only reset by run.started, which the daemon-side queue drain never publishes, so a drained turn's done was swallowed as a duplicate of the previous turn's. Reset the dedup on session.pending_prompt_submitted, and suppress stale run.completed events that land inside a drained turn's window so they can neither emit a phantom done nor consume the drained turn's dedup slot. Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com> * test(desktop): cover restore unlock after an event-settled queued turn Exports the sidecar's core-session event handler so the queued-turn lifecycle (busy via status events, cleared by the done agent event, restore allowed afterwards) is testable end-to-end. Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com> * fix(core): start interactive sessions without a prompt as idle The runtime host reported every new session as "running" until its first turn ended. Interactive hosts (the desktop app) start sessions with no prompt and dispatch turns through separate send calls, so a created-but-never-prompted session stayed "running" forever — wedging clients that gate workspace operations (checkpoint restore, message edit) on active turns. Interactive no-prompt starts now begin idle, start emits the session's actual status (resumed sessions no longer masquerade as running), and markTurn* transitions keep tracking in-memory status for lazily persisted sessions so the first turn still reports running -> idle. Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com> * style: format hub-runtime-host test filter Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com> * refactor: drop the drained-turn done bookkeeping, keep the minimal fix The stuck restore is fully explained by the two status defects (fabricated "running" from snapshot-only session.updated events, and never-prompted interactive sessions reporting "running"). The done-dedup machinery for queue-drained turns addressed a separate cosmetic gap (queued turns emit no chat_done, pre-existing) and required fragile run-window heuristics, so it is removed to keep this change reviewable. Sidecar test now settles the queued turn through the status event, matching the shipped mechanism. Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com> * docs(sdk): document the truthful session-status contract --------- Co-authored-by: Saoud Rizwan <saoudrizwan@users.noreply.github.com>
Cline SDK Examples
Learn how to build with the Cline SDK through working examples, ordered from simple to complex.
SDK Skill
If you use a coding agent (Claude Code, Codex, Cline, etc.), install the Cline SDK skill to give your agent context on the SDK's APIs and best practices to help you build with the Cline SDK.
npx skills add cline/sdk-skill
Prompt it to scaffold agents, create custom tools, wire up plugins, configure providers, and more.
Getting started
All examples live in this directory. Each is a standalone project with its own package.json and README. To run any example:
cd apps/examples/<example-name>
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
Requires Node.js 22+.
Examples
Beginner
| Example | Description | Concepts |
|---|---|---|
| quickstart | Send one prompt, stream the response. ~15 lines of code. | Agent, subscribe, run() |
| cli-agent | Interactive terminal chat with a shell tool. | createTool, multi-turn run()/continue(), streaming |
| cline-core-cli-agent | Interactive terminal chat powered by ClineCore. | ClineCore.create(), cline.start(), cline.send(), built-in tools, streaming |
Intermediate
| Example | Description | Concepts |
|---|---|---|
| code-review-bot | AI code reviewer that reads git diffs and produces structured comments. | Multiple tools, completesRun lifecycle, systemPrompt, zod schemas |
| multi-agent | Web app that fans out to three specialist agents in parallel, streams results via SSE, then synthesizes a unified answer. | Concurrent agents, Promise.all, per-agent subscribe(), SSE streaming, agent composition |
Advanced
| Example | Description | Concepts |
|---|---|---|
| desktop-app | Full Tauri + Next.js desktop app for running and inspecting chat sessions. | Sidecar runtime, websocket transport, session persistence |
| menubar | macOS menu bar app with Tauri. | Native app integration, compact UI |
| vscode | VS Code extension with chat panel. | Extension API, webview, workspace context |
SDK packages
When building your own app, install the public SDK package:
npm add @cline/sdk
@cline/sdk re-exports everything from @cline/core. You only need @cline/agents or @cline/llms if you want lower-level control over the agent runtime or model gateway directly.
Learn more
- SDK package docs
- Architecture guide
- Plugin examples - extend the Cline SDK and CLI with custom tools and event hooks
- Hook examples - lifecycle hooks for logging, blocking, and injection for Cline SDK and CLI