Learn how to build with the Cline SDK through practical, runnable 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:
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 toolmac-notify.ts- macOS Notification Center alertscustom-compaction.ts- Custom context compactionautomation-events.ts- Plugin event emissionbackground-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.
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()andAgentExtension - Use the TypeScript Language Service to resolve symbol definitions
- Cache the language service for efficient repeated lookups
- Zero extra dependencies -- resolves
typescriptfrom 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"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.
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.
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 automaticallyTo use the SDK in your own Node app (outside this monorepo), start with:
npm add @cline/coreAdd @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/coreowns 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/coresurface unless they intentionally need lower-level agent or model control
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/, andmenubar/for app integration patterns
Controlling agent behavior?
- Explore
./hooks/to intercept and modify tool execution, log actions, or enforce policies
- 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