Skip to main content
The SDK repository includes installable plugin examples under examples/plugins/. Use them as starting points for tools, lifecycle hooks, message rewriting, policy enforcement, background jobs, and multi-agent workflows.

​
Examples

ExampleWhat it shows
weather-metrics.tsTool registration plus lifecycle metrics hooks. Best starting point.
mac-notify.tsmacOS Notification Center alert from an afterRun hook.
custom-compaction.tsProvider-message compaction with registerMessageBuilder.
background-terminal.tsDetached shell jobs with persisted logs and optional session steering.
automation-events.tsPlugin-emitted automation events.
gitignore-read-files-guard.tsRuntime hook policy that blocks file access outside workspace .gitignore boundaries.
web-search.tsweb_search tool backed by an Exa API key.
typescript-lsp/goto_definition tool powered by the TypeScript Language Service.
agents-squad/Multi-agent team with subagents that have their own models and personalities.

​
Try a File Plugin with the CLI

The CLI auto-discovers plugins from .cline/plugins in the workspace, ~/.cline/plugins, and the system plugins folder. 
cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/weather-metrics.ts --cwd .
cline -i "What's the weather like in Tokyo and Paris?"
Swap weather-metrics.ts for any other single-file plugin example.

​
Block Ignored File Access

Use gitignore-read-files-guard.ts to block tools from reading or editing files ignored by workspace .gitignore files: 
cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/gitignore-read-files-guard.ts --cwd .
cline -i "Read the ignored .env file"
The guard uses the beforeTool runtime hook. When a read_files, editor, or apply_patch call targets an ignored workspace file, the hook returns { skip: true }, so the tool records a policy error and does not access the file.

​
Install a Directory Plugin

For a plugin that lives in a directory with its own package.json, use cline plugin install: 
cline plugin install ./examples/plugins/agents-squad
See Installing Plugins for more install options. The web-search.ts plugin registers a web_search tool backed by Exa. Use web_search to discover relevant URLs, then use fetch_web_content when the agent needs to inspect a specific page. 
cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/web-search.ts --cwd .

export EXA_API_KEY=...
export OPENROUTER_API_KEY=...

cline auth --provider openrouter --apikey "$OPENROUTER_API_KEY" --modelid anthropic/claude-sonnet-4.6
cline -P openrouter -m anthropic/claude-sonnet-4.6 "Search the web for recent Bun release notes, then fetch the most relevant page"
EXA_API_KEY authenticates the search backend. The CLI still needs a normal model provider key or saved provider auth for inference.

​
Custom Message Compaction

Use registerMessageBuilder when a plugin needs to rewrite the provider-bound message list before the model call.
ExampleExtension pointBest for
custom-compaction.tsapi.registerMessageBuilder()Reusable, plugin-owned compaction policies.
custom-compaction-hook.example.tshooks.beforeModelRuntime hook logic that needs runtime hook context or direct request mutation.
Prefer the message-builder version for normal compaction. It runs in the core message pipeline before the built-in safety builder, multiple builders run in registration order, and the final pass enforces provider-safe truncation.

​
Background Terminal Plugin

background-terminal.ts registers three tools for long-running shell jobs:
ToolPurpose
start_background_commandStarts a detached shell command, returns a job ID immediately, and captures stdout/stderr under Cline’s data directory.
get_background_commandReads job status plus recent stdout/stderr tails.
delete_background_commandDeletes saved job metadata and optionally deletes captured logs.
When notifyParent is true, the plugin emits a steer_message after the command exits, pushing a completion summary back into the active session so the agent can react to long-running commands without blocking the original tool call.