wehub-resource-sync
161 lines
5.3 KiB
Plaintext
161 lines
5.3 KiB
Plaintext
---
|
|
title: "Plugins Overview"
|
|
sidebarTitle: "Plugins"
|
|
description: "Learn what plugins are, their benefits, and how they extend agent behavior."
|
|
---
|
|
|
|
Plugins are packages of reusable agent capabilities. They let you bundle tools, lifecycle hooks, commands, and configuration into a single module that can be shared across projects or published for others to use.
|
|
|
|
## Benefits of Plugins
|
|
|
|
| Benefit | Description |
|
|
|---------|-------------|
|
|
| **Modularity** | Encapsulate related tools and hooks in a single unit. No more scattered logic. |
|
|
| **Reusability** | Share plugins across agents, projects, or teams. Publish to npm or distribute via git. |
|
|
| **Packaging** | Bundle tools, hooks, commands, message builders, and providers together. |
|
|
| **Observability** | Hook into every stage of the agent lifecycle — run start/end, model calls, tool calls, errors. |
|
|
| **Composability** | Combine multiple plugins in a single agent. Each plugin handles its own domain. |
|
|
|
|
## Extension Glossary
|
|
|
|
| Extension point | What it does |
|
|
|-----------------|--------------|
|
|
| **Tool** | Lets the model call an action (query a DB, call an API, etc.) |
|
|
| **Command** | Register slash commands to allow actions to be manually triggered |
|
|
| **Hook** | Runs lifecycle logic or policy checks at specific stages |
|
|
| **Rules** | Prompts that steer the agent and will be included in every session |
|
|
| **Events** | Register external events that will trigger agent actions |
|
|
| **Plugin** | Packages tools, hooks, commands, rules, and automation events together |
|
|
|
|
| If you need to... | Use a... |
|
|
|-------------------|----------|
|
|
| Allow the model to query a database, call an API, run a domain action | **Tool** |
|
|
| Register a user triggered action (slash command) | **Command** |
|
|
| Log runs, collect metrics, enforce policy | **Hook** handler |
|
|
| Block dangerous tool calls | **Hook** or approval policy |
|
|
| Provide consistent guidance to the model via prompts | **Rule** |
|
|
| Trigger agent action on an external event (new PR, Slack message, etc) | **Event** |
|
|
| Bundle several tools into a reusable module | **Plugin** |
|
|
|
|
## What is a Plugin?
|
|
|
|
A plugin is an `AgentPlugin` — an object that implements the SDK's extension interface. It can register tools, hook into agent lifecycle events, and provide configuration defaults.
|
|
|
|
```typescript
|
|
import { type AgentPlugin } from "@cline/sdk"
|
|
|
|
const myPlugin: AgentPlugin = {
|
|
name: "my-plugin",
|
|
manifest: {
|
|
capabilities: ["tools", "hooks"],
|
|
},
|
|
setup(api, ctx) {
|
|
// Register tools, commands, providers via api.registerTool(), etc.
|
|
},
|
|
hooks: {
|
|
beforeTool(context) {
|
|
// Observe or audit tool calls before they execute
|
|
},
|
|
afterRun(context) {
|
|
// Log metrics, cleanup, notify after a run completes
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
Hooks are defined inside the `hooks` object, not directly on the extension. The available lifecycle hooks are `beforeRun`, `afterRun`, `beforeModel`, `afterModel`, `beforeTool`, `afterTool`, and `onEvent`.
|
|
|
|
|
|
## Next Steps
|
|
|
|
Register with `ClineCore`:
|
|
|
|
```typescript
|
|
await cline.start({
|
|
prompt: "Analyze customer records",
|
|
config: {
|
|
// ...model/runtime config
|
|
extensions: [databasePlugin],
|
|
},
|
|
})
|
|
```
|
|
|
|
## File-Based Plugins
|
|
|
|
`ClineCore` supports plugin module paths via `pluginPaths` in session config:
|
|
|
|
```typescript
|
|
await cline.start({
|
|
prompt: "Analyze this project",
|
|
config: {
|
|
// ...model/runtime config
|
|
pluginPaths: ["/absolute/path/to/plugin.ts"],
|
|
},
|
|
})
|
|
```
|
|
|
|
Plugin files export an `AgentPlugin`.
|
|
|
|
## Installing Plugins via CLI
|
|
|
|
Plugins can also be installed from file URLs, npm, git, or local paths using `cline plugin install`. See [Plugins](/customization/plugins) for install commands, the manifest format, and directory layout.
|
|
|
|
## Hook Stages
|
|
|
|
Hook stages include:
|
|
|
|
```txt
|
|
input
|
|
runtime_event
|
|
session_start
|
|
run_start
|
|
iteration_start
|
|
turn_start
|
|
before_agent_start
|
|
tool_call_before
|
|
tool_call_after
|
|
turn_end
|
|
stop_error
|
|
iteration_end
|
|
run_end
|
|
session_shutdown
|
|
error
|
|
```
|
|
|
|
Common stages:
|
|
|
|
| Stage | Use for |
|
|
|-------|---------|
|
|
| `before_agent_start` | Inject context or modify prompt/messages |
|
|
| `run_start` | Logging, timers, rate limits |
|
|
| `tool_call_before` | Audit or block tool calls |
|
|
| `tool_call_after` | Log results, trigger side effects |
|
|
| `run_end` | Metrics, notifications, cleanup |
|
|
| `error` | Error reporting |
|
|
|
|
## Hook Policies
|
|
|
|
Hook policies control execution behavior:
|
|
|
|
| Field | Meaning |
|
|
|-------|---------|
|
|
| `mode` | `"blocking"` or `"async"` |
|
|
| `timeoutMs` | Hook timeout |
|
|
| `retries` | Retry count |
|
|
| `retryDelayMs` | Delay between retries |
|
|
| `failureMode` | `"fail_open"` or `"fail_closed"` |
|
|
| `maxConcurrency` | Concurrent hook executions |
|
|
| `queueLimit` | Queue size before dropping |
|
|
|
|
Use `fail_closed` for policy-enforcement hooks where bypassing the hook is unsafe.
|
|
|
|
## Build a Plugin
|
|
|
|
For a step-by-step plugin tutorial, see [Writing Plugins](/sdk/guides/writing-plugins).
|
|
|
|
## SDK Examples
|
|
|
|
The [SDK repository](https://github.com/cline/cline/tree/main/sdk) includes ready-to-run plugin examples under [`examples/plugins/`](https://github.com/cline/cline/tree/main/sdk/examples/plugins), including tool registration, lifecycle metrics, notifications, custom compaction, policy guards, web search, background jobs, TypeScript LSP tools, and multi-agent teams.
|
|
|
|
See [Plugin Examples](/sdk/plugin-examples) for the full list and usage commands.
|