# opencode-install-plugin

> Manage and create OpenCode plugins for extending OpenCode capabilities. Use when users need to install plugins from local files or npm packages, create custom plugins with hooks and events, add custom tools to OpenCode, configure plugin dependencies, or understand plugin load order and lifecycle.

- Author: ONG YI SHEN
- Repository: ongyishen/agent-skills
- Version: 20260126210821
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ongyishen/agent-skills
- Web: https://mule.run/skillshub/@@ongyishen/agent-skills~opencode-install-plugin:20260126210821

---

---
name: opencode-install-plugin
description: Manage and create OpenCode plugins for extending OpenCode capabilities. Use when users need to install plugins from local files or npm packages, create custom plugins with hooks and events, add custom tools to OpenCode, configure plugin dependencies, or understand plugin load order and lifecycle.
---

# OpenCode Plugin Management

## Quick Start

OpenCode plugins extend functionality by hooking into events and customizing behavior. Choose your task:

- **Install plugin**: See [Install from Local Files](#install-from-local-files) or [Install from npm](#install-from-npm)
- **Create plugin**: See [Create a Plugin](#create-a-plugin)
- **Add custom tools**: See [Add Custom Tools](#add-custom-tools)
- **Use hooks/events**: See [events.md](references/events.md) for complete event list
- **View examples**: See [examples.md](references/examples.md) for common patterns

## Plugin Context Object

Plugins receive `{ project, client, $, directory, worktree }`:
- `project`: Current project information
- `client`: OpenCode SDK client for AI interaction
- `$`: Bun's shell API for command execution
- `directory`: Current working directory
- `worktree`: Git worktree path

## Install from Local Files

Place plugin files in plugin directories:

1. **Project-level**: `.opencode/plugins/`
2. **Global**: `~/.config/opencode/plugins/`

Files are auto-loaded at startup.

### Add Dependencies

Create `package.json` in config directory with dependencies:

```json
{
  "dependencies": {
    "package-name": "^1.0.0"
  }
}
```

OpenCode runs `bun install` at startup. See [package.json template](assets/templates/package.json).

## Install from npm

Add plugins to `opencode.json` config:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}
```

Both regular and scoped packages supported. Browse available plugins at [OpenCode ecosystem](https://opencode.ai/docs/ecosystem#plugins).

### Installation Process

- **npm plugins**: Auto-installed via Bun at startup, cached in `~/.cache/opencode/node_modules/`
- **Local plugins**: Loaded directly, require `package.json` for external dependencies

## Load Order

Plugins load in sequence:
1. Global config (`~/.config/opencode/opencode.json`)
2. Project config (`opencode.json`)
3. Global plugin directory (`~/.config/opencode/plugins/`)
4. Project plugin directory (`.opencode/plugins/`)

Duplicate npm packages (same name/version) load once. Local + npm plugins with similar names load separately.

## Create a Plugin

### Basic Structure

```typescript
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
  return {
    // Hook implementations
  }
}
```

### TypeScript Support

Import types for type safety:

```typescript
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hooks
  }
}
```

### Use Templates

Copy from [assets/templates/basic-plugin.ts](assets/templates/basic-plugin.ts) to start.

## Add Custom Tools

Plugins can register custom tools using the `tool` helper:

```typescript
import { type Plugin, tool } from "@opencode-ai/plugin"

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      myTool: tool({
        description: "What the tool does",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, ctx) {
          return `Result: ${args.foo}`
        },
      }),
    },
  }
}
```

See [custom-tools-plugin.ts template](assets/templates/custom-tools-plugin.ts) and [examples.md](references/examples.md).

## Common Hook Patterns

### Tool Interception

```typescript
"tool.execute.before": async (input, output) => {
  if (input.tool === "read" && output.args.filePath.includes(".env")) {
    throw new Error("Do not read .env files")
  }
}
```

### Event Monitoring

```typescript
event: async ({ event }) => {
  if (event.type === "session.idle") {
    await $`osascript -e 'display notification "Session completed!"'`
  }
}
```

### Logging

```typescript
await client.app.log({
  service: "my-plugin",
  level: "info",
  message: "Plugin initialized",
  extra: { key: "value" },
})
```

Levels: `debug`, `info`, `warn`, `error`.

## Resources

### [events.md](references/events.md)
Complete list of all plugin events organized by category (Command, File, LSP, Message, Session, Tool, TUI).

### [examples.md](references/examples.md)
Common plugin patterns including:
- Basic plugin structure
- Tool interception (env protection, shell escaping)
- Custom tools (simple and complex)
- Notifications
- Session compaction
- Logging
- Event monitoring

### [assets/templates/](assets/templates/)
- `basic-plugin.ts` - Minimal plugin template
- `custom-tools-plugin.ts` - Custom tools template
- `package.json` - Dependencies template