OpenCode Plugins

https://opencode.ai/docs/plugins/
Admin
OpenCode Plugins enable developers to extend OpenCode by hooking into events and customizing...
Tokens:2,566
Snippets:41
Trust Score:8.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Import npm package and use tool.execute.before hook

Source: https://opencode.ai/docs/plugins

Example plugin that imports the `shescape` package and uses the `tool.execute.before` hook to escape bash commands before execution. Place it in `.opencode/plugins/my-plugin.ts`.

```ts
import { escape } from "shescape"

export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}
```

--------------------------------

### Declare plugin dependencies in .opencode/package.json

Source: https://opencode.ai/docs/plugins

Add this package.json to your config directory to declare external npm dependencies for local plugins and custom tools. OpenCode runs `bun install` at startup to install these dependencies.

```json
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}
```

--------------------------------

### Configure npm plugins in opencode.json

Source: https://opencode.ai/docs/plugins

Specify npm packages to load as plugins in the OpenCode configuration file. Both regular and scoped npm packages are supported. The packages are installed automatically using Bun at startup and cached in ~/.cache/opencode/node_modules/.

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

--------------------------------

### TypeScript plugin with Plugin type from @opencode-ai/plugin

Source: https://opencode.ai/docs/plugins

TypeScript plugin example that imports the `Plugin` type from `@opencode-ai/plugin` for type-safe hook implementations. The `{1}` in the title highlights the import line.

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

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

--------------------------------

### Basic plugin structure in .opencode/plugins/example.js

Source: https://opencode.ai/docs/plugins

Basic plugin structure showing the exported plugin function and the context object it receives. The context includes `project`, `directory`, `worktree`, `client`, and `$` (Bun's shell API).

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

  return {
    // Hook implementations go here
  }
}
```

--------------------------------

### Replace compaction prompt entirely

Source: https://opencode.ai/docs/plugins

Replaces the entire compaction prompt by setting `output.prompt` in the `experimental.session.compacting` hook. When set, the default prompt is completely replaced and `output.context` is ignored.

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

export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Replace the entire compaction prompt
      output.prompt = `
You are generating a continuation prompt for a multi-agent swarm session.

Summarize:
1. The current task and its status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work

Format as a structured prompt that a new agent can use to resume work.
`
    },
  }
}

```

--------------------------------

### Create custom tool with @opencode-ai/plugin

Source: https://opencode.ai/docs/plugins

Adds a custom tool named `mytool` using the `tool` helper from `@opencode-ai/plugin`. The tool takes a string argument `foo` and returns a greeting with the directory and worktree. Plugin tools override built-in tools with the same name.

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

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

```

--------------------------------

### Add context to compaction prompt

Source: https://opencode.ai/docs/plugins

Injects additional context into the compaction prompt via the `experimental.session.compacting` hook. The hook fires before the LLM generates a continuation summary. Use to add domain-specific context that the default prompt would miss.

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

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`
## Custom Context

Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

```

--------------------------------

### Block .env file reads with tool.execute.before

Source: https://opencode.ai/docs/plugins

Prevents the `read` tool from accessing any file path containing `.env` by throwing an error in the `tool.execute.before` hook.

```javascript
export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

```

--------------------------------

### Structured logging with client.app.log

Source: https://opencode.ai/docs/plugins

Logs structured messages using `client.app.log()` instead of `console.log`. Supports levels `debug`, `info`, `warn`, and `error`. See the SDK documentation for details.

```typescript
export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

```

--------------------------------

### Send notifications on session idle with osascript

Source: https://opencode.ai/docs/plugins

Sends a macOS notification via osascript when a session becomes idle. Requires macOS and the `osascript` command. The OpenCode desktop app can send notifications automatically instead.

```javascript
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
      }
    },
  }
}

```

--------------------------------

### Inject environment variables into shell execution

Source: https://opencode.ai/docs/plugins

Injects environment variables into all shell executions (AI tools and user terminals) via the `shell.env` hook. Sets `MY_API_KEY` and `PROJECT_ROOT` from the current working directory.

```javascript
export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

```
Tokens:
Raw