Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
After installation, confirm the plugin is loaded by running
Once installed, Cline can call
The
Each path should point to a
Global plugins (
A plugin that keeps failing in hooks or tools is turned off for the rest of the hub’s life until you reload it or change its file. One broken plugin doesn’t stop other plugins or sessions.
Plugins
Install and manage plugins that extend Cline with custom tools, hooks, and capabilities.
This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
Installing Plugins via CLI
Thecline plugin install command installs plugins from four source types:
- File URL
- Git Repository
- npm Package
- Local Path
cline plugin install https://github.com/owner/repo/blob/main/plugins/my-plugin.ts
cline plugin install https://raw.githubusercontent.com/owner/repo/main/plugins/my-plugin.ts
.ts or .js plugin file directly. GitHub blob and raw URLs are supported, and remote plugin file URLs must use https://.cline plugin install https://github.com/owner/repo.git
cline plugin install git@github.com:owner/repo.git
@ref:cline plugin install https://github.com/owner/repo.git@v1.2.0
cline plugin install https://github.com/owner/repo.git@main
cline plugin install npm:@scope/my-plugin
cline plugin install --npm my-plugin
cline plugin install ./my-plugin
cline plugin install ~/plugins/my-tool
cline plugin install /absolute/path/to/plugin.ts
.ts/.js files and directories with a package.json are supported.| Flag | Description |
|---|---|
--force | Replace an existing install for the same source |
--json | Output the result as JSON (useful for scripting) |
--cwd <path> | Install to <path>/.cline/plugins instead of the global directory |
cline config and checking the plugin tab.
Example: TypeScript Navigation Plugin
The typescript-lsp-plugin is a good reference for how plugins work. It adds agoto_definition tool that uses the TypeScript Language Service API to resolve symbol definitions through imports, re-exports, and type aliases.
Install it with:
cline plugin install https://github.com/cline/typescript-lsp-plugin.git
goto_definition with a file path and line number to find where symbols are defined, which is much more precise than text search.
Plugin Manifest Format
For a repository or npm package to be installable as a Cline plugin, itspackage.json should include a cline field that declares plugin entry points:
{
"name": "my-cline-plugin",
"version": "1.0.0",
"cline": {
"plugins": [
{
"paths": ["./index.ts"],
"capabilities": ["tools", "hooks"]
}
]
}
}
cline.plugins array accepts:
| Format | Example |
|---|---|
Object with paths array | { "paths": ["./src/plugin.ts"], "capabilities": ["tools"] } |
| Plain string | "./index.ts" |
.ts or .js file that exports an AgentPlugin (either as the default export or a named export).
If no cline.plugins field is present, the installer falls back to auto-discovery: it looks for standard entry points, then recursively scans for .ts and .js files (skipping node_modules and .git).
Host-Provided Dependencies
Dependencies under the@cline/ scope are provided by the host runtime. The installer automatically strips these from the plugin’s dependency list before running npm install, so declare any @cline/* package your plugin imports as an optional peer dependency. The host currently provides @cline/sdk, @cline/core, @cline/agents, @cline/llms, and @cline/shared.
{
"peerDependencies": {
"@cline/sdk": "*"
},
"peerDependenciesMeta": {
"@cline/sdk": {
"optional": true
}
}
}
Plugin Directory Structure
Plugins are stored in theplugins directory at two levels:
~/.cline/
plugins/ # Global plugins
_installed/ # Managed by `cline plugin install`
npm/ # npm-sourced plugins
git/ # git-sourced plugins
remote/ # file URL-sourced plugins
local/ # local-sourced plugins
.cline/ # Project root
plugins/ # Project-scoped plugins
~/.cline/plugins/) are available across all sessions. Project plugins (.cline/plugins/ in your repo) are available only when working in that project.
Troubleshooting Plugins
When a plugin fails to load, Cline tells you which plugin failed and why instead of quietly dropping its tools:- Starting a session prints a warning that names the plugin, the step that failed (import, setup, a hook, or a tool), and the error.
cline config toolslists failed plugins under “Failed plugins”. With--json, each one is an entry with"type": "plugin_failure"and anerrorobject holding itsphaseandmessage.cline hub pluginsshows the status of every plugin the hub loaded, its last error, and the sessions using it.
cline hub plugins --reload my-plugin
Writing Plugins
For a guide on building plugins with the SDK, see Writing Plugins. For the plugin API reference, see SDK Plugins.Was this page helpful?