---
title: "Plugins"
sidebarTitle: "Plugins"
description: "Install and manage plugins that extend Cline with custom tools, hooks, and capabilities."
---
<Warning>
  This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
</Warning>

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:

<Tabs>
  <Tab title="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://`.
  </Tab>
  <Tab title="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
    ```
  </Tab>
  <Tab title="npm Package">
    ```bash
    cline plugin install npm:@scope/my-plugin
    cline plugin install --npm my-plugin
    ```
  </Tab>
  <Tab title="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.
  </Tab>
</Tabs>

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.

## 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 tools` lists failed plugins under "Failed plugins". With `--json`, each one is an entry with `"type": "plugin_failure"` and an `error` object holding its `phase` and `message`.
- `cline hub plugins` shows the status of every plugin the hub loaded, its last error, and the sessions using it.

After fixing a plugin, reload it without restarting the hub:

```bash
cline hub plugins --reload my-plugin
```

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.

## Writing Plugins

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