# Plugins

> Install and manage plugins that extend Cline with custom tools, hooks, and capabilities.

- 网址：https://funcoding.ai/agents/cline/customization/plugins/
- 来源：Cline 官方文档原文（英文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://docs.cline.bot/customization/plugins

---
<div class="callout callout-warning">

This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.

</div>

Plugins extend Cline with custom tools, lifecycle hooks, slash commands, and more. They can be installed globally (available in all sessions) or per-project.

## Installing Plugins via CLI

The `cline plugin install` command installs plugins from four source types:

**File URL**

```bash
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
```

File URLs install a single `.ts` or `.js` plugin file directly. GitHub `blob` and raw URLs are supported, and remote plugin file URLs must use `https://`.

**Git Repository**

```bash
cline plugin install https://github.com/owner/repo.git
cline plugin install git@github.com:owner/repo.git
```

The installer clones the repository, installs production dependencies, and registers the plugin entry files.

To install a specific branch or tag, append `@ref`:

```bash
cline plugin install https://github.com/owner/repo.git@v1.2.0
cline plugin install https://github.com/owner/repo.git@main
```

**npm Package**

```bash
cline plugin install npm:@scope/my-plugin
cline plugin install --npm my-plugin
```

**Local Path**

```bash
cline plugin install ./my-plugin
cline plugin install ~/plugins/my-tool
cline plugin install /absolute/path/to/plugin.ts
```

Local installs copy the file or directory into the plugin store. Both single `.ts`/`.js` files and directories with a `package.json` are supported.

Additional flags:

| 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 |

After installation, confirm the plugin is loaded by running `cline config` and checking the plugin tab.

### Example: TypeScript Navigation Plugin

The [typescript-lsp-plugin](https://github.com/cline/typescript-lsp-plugin) is a good reference for how plugins work. It adds a `goto_definition` tool that uses the TypeScript Language Service API to resolve symbol definitions through imports, re-exports, and type aliases.

Install it with:

```bash
cline plugin install https://github.com/cline/typescript-lsp-plugin.git
```

Once installed, Cline can call `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, its `package.json` should include a `cline` field that declares plugin entry points:

```json
{
  "name": "my-cline-plugin",
  "version": "1.0.0",
  "cline": {
    "plugins": [
      {
        "paths": ["./index.ts"],
        "capabilities": ["tools", "hooks"]
      }
    ]
  }
}
```

The `cline.plugins` array accepts:

| Format | Example |
|--------|---------|
| Object with `paths` array | `{ "paths": ["./src/plugin.ts"], "capabilities": ["tools"] }` |
| Plain string | `"./index.ts"` |

Each path should point to a `.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`.

```json
{
  "peerDependencies": {
    "@cline/sdk": "*"
  },
  "peerDependenciesMeta": {
    "@cline/sdk": {
      "optional": true
    }
  }
}
```

## Plugin Directory Structure

Plugins are stored in the `plugins` 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
```

Global plugins (`~/.cline/plugins/`) are available across all sessions. Project plugins (`.cline/plugins/` in your repo) are available only when working in that project.

## Writing Plugins

For a guide on building plugins with the SDK, see [Writing Plugins](https://funcoding.ai/agents/cline/sdk/guides/writing-plugins/). For the plugin API reference, see [SDK Plugins](https://funcoding.ai/agents/cline/sdk/plugins/).