Plugins Overview

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.

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:

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:

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 for install commands, the manifest format, and directory layout.

Hook Stages

Hook stages include:

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 Examples

The SDK repository includes ready-to-run plugin examples under 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 for the full list and usage commands.