> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cline.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> 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 theme={"system"}
    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 theme={"system"}
    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 theme={"system"}
    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 theme={"system"}
    cline plugin install npm:@scope/my-plugin
    cline plugin install --npm my-plugin
    ```
  </Tab>

  <Tab title="Local Path">
    ```bash theme={"system"}
    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 theme={"system"}
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 theme={"system"}
{
  "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 theme={"system"}
{
  "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](/sdk/guides/writing-plugins). For the plugin API reference, see [SDK Plugins](/sdk/plugins).