Documentation Index
Fetch the complete documentation index at: https://docs.cline.bot/llms.txt
Use this file to discover all available pages before exploring further.
The SDK repository includes ready-to-run 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
| Example | What it shows |
|---|
weather-metrics.ts | Tool registration plus lifecycle metrics hooks. Best starting point. |
mac-notify.ts | macOS Notification Center alert from an afterRun hook. |
custom-compaction.ts | Provider-message compaction with registerMessageBuilder. |
background-terminal.ts | Detached shell jobs with persisted logs and optional session steering. |
automation-events.ts | Plugin-emitted automation events. |
gitignore-read-files-guard.ts | Runtime hook policy that blocks file access outside workspace .gitignore boundaries. |
web-search.ts | web_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.
mkdir -p .cline/plugins
cp examples/plugins/weather-metrics.ts .cline/plugins/
cline -i "What's the weather like in Tokyo and Paris?"
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:
mkdir -p .cline/plugins
cp examples/plugins/gitignore-read-files-guard.ts .cline/plugins/
cline -i "Read the ignored .env file"
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
Add Web Search
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.
mkdir -p .cline/plugins
cp examples/plugins/web-search.ts .cline/plugins/web-search.ts
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.
| Example | Extension point | Best for |
|---|
custom-compaction.ts | api.registerMessageBuilder() | Reusable, plugin-owned compaction policies. |
custom-compaction-hook.example.ts | hooks.beforeModel | Runtime hook logic that needs runtime hook context or direct request mutation. |
Background Terminal Plugin
background-terminal.ts registers three tools for long-running shell jobs:
| Tool | Purpose |
|---|
start_background_command | Starts a detached shell command, returns a job ID immediately, and captures stdout/stderr under Cline’s data directory. |
get_background_command | Reads job status plus recent stdout/stderr tails. |
delete_background_command | Deletes saved job metadata and optionally deletes captured logs. |
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.
