cline/sdk/examples

Cline SDK Examples

Learn how to build with the Cline SDK through practical, runnable examples.

📁 Plugin, Hook, and Automation Examples

Plugins extend the CLI and SDK with custom capabilities. Install local files, GitHub file URLs, package directories, git repos, and npm packages with cline plugin install:

./plugins/

Plugin module examples showing how to extend the CLI and SDK with custom capabilities:

• Register custom tools
• Hook into agent lifecycle events
• Export a reusable plugin module for .cline/plugins

Examples include:

• 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 setup and job logging

cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/weather-metrics.ts
cline -i "What's the weather like in Tokyo and Paris?"

Plugin setup receives a host logger through the second setup argument. Use ctx.logger for setup-time diagnostics and logs emitted during tool calls:

setup(api, ctx) {
  ctx.logger?.log("my-plugin setup", {
    sessionId: ctx.session?.sessionId,
    workspaceRoot: ctx.workspaceInfo?.rootPath,
  });

  try {
    // Register tools or perform plugin setup work.
  } catch (error) {
    if (ctx.logger?.error) {
      ctx.logger.error("my-plugin setup failed", { error });
    } else {
      ctx.logger?.log("my-plugin setup failed", { error, severity: "error" });
    }
    throw error;
  }
}

ctx.logger is session-scoped. For detached work that can outlive the session, such as background processes, persist status to plugin-owned storage or report completion through the host event channel instead of calling the captured logger from long-lived callbacks.

./plugins/typescript-lsp/

TypeScript LSP plugin that gives the agent a goto_definition tool powered by the TypeScript Language Service API. Resolves through imports, re-exports, and type aliases -- much more precise than text search.

• Register a tool via createTool() and AgentExtension
• Use the TypeScript Language Service to resolve symbol definitions
• Cache the language service for efficient repeated lookups
• Zero extra dependencies -- resolves typescript from the target project

cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/index.ts
cline -i "Find where createTool is defined"

./plugins/agents-squad/

Portable subagent plugin that adds background agent orchestration tools to the CLI and SDK:

• Export a reusable plugin module for .cline/plugins
• Start background subagents from the main session
• Load bundled or custom agent presets and skills
• Log setup, subagent starts, and follow-ups through ctx.logger

Includes pre-configured agents:

• Anvil - Build and compile
• Inquisitor - Investigation and discovery
• Oracle - Planning and architecture
• Phantom - Stealth and optimization

Skills available:

• API design, code review, debugging, documentation, migration, refactoring, test generation

cline plugin install ./examples/plugins/agents-squad
cline -i "Use subagents to inspect this repository and report back."

Once loaded, the agent can call tools like start_subagent, message_subagent, get_subagent, list_agent_presets, list_skills, and the handoff tools.

📁 Cron & hooks Examples

./cron/

Example file-based and event-driven automation specs for global ~/.cline/cron/:

Recurring jobs for continuous quality:

• changelog-generator — Auto-generate CHANGELOG from commits
• dependency-check — Weekly security and update audits
• test-coverage-report — Daily coverage metrics
• performance-baseline — Build time and bundle size tracking
• type-check-strict — TypeScript type safety audits
• code-style-audit — Linting and formatting checks
• dead-code-finder — Identify unused code
• documentation-check — API documentation coverage
• weekly-metrics-summary — Fun team metrics report 🎉

Event-driven jobs for PR workflows:

• pr-changelog-check — Verify CHANGELOG is updated in PRs
• pr-test-coverage — Analyze coverage impact of changes

mkdir -p ~/.cline/cron
cp examples/cron/changelog-generator.cron.md ~/.cline/cron/
mkdir -p ~/.cline/cron/events
cp examples/cron/events/pr-changelog-check.event.md ~/.cline/cron/events/

See cron/README.md for full descriptions and usage patterns.

./hooks/

Lifecycle hooks written in bash, Python, or TypeScript that intercept agent actions at key points:

• Log all tool calls (PreToolUse) and results (PostToolUse)
• Block destructive operations
• Require review for critical files
• Inject contextual information
• Track lifecycle events (TaskStart, TaskComplete, SessionShutdown)

Hooks live in .cline/hooks/ and are named after the event they handle (PreToolUse, PostToolUse, TaskStart, etc.):

mkdir -p ~/.cline/hooks

# Bash hook
cp examples/hooks/PreToolUse.sh ~/.cline/hooks/
chmod +x ~/.cline/hooks/PreToolUse.sh

# Or Python
cp examples/hooks/PreToolUse.py ~/.cline/hooks/PreToolUse.py
chmod +x ~/.cline/hooks/PreToolUse.py

# Or TypeScript (runs via bun)
cp examples/hooks/PreToolUse.ts ~/.cline/hooks/PreToolUse.ts
chmod +x ~/.cline/hooks/PreToolUse.ts

cline -i "do something"  # Hooks will execute automatically

🚀 Quick Start

To use the SDK in your own Node app (outside this monorepo), start with:

npm add @cline/core

Add @cline/agents or @cline/llms only if you intentionally want lower-level control. For RPC client helpers, prefer importing from @cline/core when you want the app-facing SDK surface.

Current SDK layering:

• @cline/core owns config discovery/watchers, runtime plugin loading, and the context pipeline
• context compaction is core-owned and runs through turn preparation before model calls
• most app integrations should stay on the @cline/core surface unless they intentionally need lower-level agent or model control

📚 Learning Path

Building plugins?

• Start with ./plugins/ for basic tool and event patterns
• Explore ./plugins/typescript-lsp/ for integration with language services
• See ./plugins/agents-squad/ for advanced agent orchestration

Building integrations?

• Review ./cron/ for automation and event-driven workflows
• Explore desktop-app/, vscode/, and menubar/ for app integration patterns

Controlling agent behavior?

• Explore ./hooks/ to intercept and modify tool execution, log actions, or enforce policies

📖 Documentation

• Cline SDK README
• Architecture Guide
• Individual Package Docs

🛠️ Requirements

• Node.js 22+ - For package compatibility
• API Key - Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or provider-specific key (for SDK examples)
• Bun - Optional, install from bun.sh for running examples