Plugins

In the Tools lesson, you added an MCP server to give OpenCode access to an external tool. MCP is great for connecting to services — but what if you want to go deeper? What if you want to hook into OpenCode’s lifecycle, modify how tools behave, inject environment variables, or register entirely new tools written in TypeScript?

That’s what plugins are for. A plugin is a JavaScript or TypeScript module that OpenCode loads at startup. It can subscribe to events, add custom tools, and change how OpenCode works — not just what tools it has access to, but how it uses them.

Where plugins live

Plugins can be installed at two levels:

Project-level plugins go in .opencode/plugins/ inside your project. These are only available when you’re working in that project.

Global plugins go in ~/.config/opencode/plugins/. These are available in every project.

You can also install plugins from npm by adding them to your opencode.json config:

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

If your plugin needs external packages, add a package.json to the same directory (.opencode/package.json for project-level, or ~/.config/opencode/package.json for global). OpenCode runs bun install automatically at startup to resolve dependencies.

What plugins can do

At its simplest, a plugin is a function that returns an object of hooks:

export const MyPlugin = async ({ project, client, $ }) => {
  return {
    "session.idle": async ({ event }) => {
      // Do something when a session finishes
    },
  }
}

Plugins can subscribe to dozens of events — session.idle, tool.execute.before, file.edited, and many more. They can also register custom tools that the AI can call, using the tool() helper from the @opencode-ai/plugin package:

import { tool } from "@opencode-ai/plugin"

export const MyPlugin = async () => {
  return {
    tool: {
      greet: tool({
        description: "Say hello",
        args: { name: tool.schema.string() },
        async execute(args) {
          return `Hello, ${args.name}!`
        },
      }),
    },
  }
}

Tools defined this way show up alongside OpenCode’s built-in tools. The AI can call them whenever it decides they’re relevant — just like the MCP tools you set up in the Tools lesson.

Some plugins also ship with a companion skill — a markdown file in .opencode/skills/ that injects workflow guidance into the agent’s system prompt, teaching it how to use the plugin’s tools effectively.

For the full list of events and hook types, see the OpenCode plugin docs.

Install the Replicate plugin

Let’s install a real plugin. The Replicate plugin gives OpenCode the ability to search for, explore, and run machine learning models on Replicate — directly from the terminal. It registers four tools (replicate_search, replicate_schema, replicate_run, and replicate_whoami) and includes a companion skill that teaches the agent a search-then-run workflow.

Get a Replicate API token

Go to replicate.com/account/api-tokens and create a token. Then add it to your shell profile so it’s available every time you open a terminal:

# Add this line to your ~/.bashrc or ~/.zshrc
export REPLICATE_API_TOKEN=r8_your_token_here

After saving the file, either open a new terminal or run source ~/.bashrc (or source ~/.zshrc) to load it.

Run the install script

From your project root, run:

curl -sSL https://raw.githubusercontent.com/lucataco/replicate-opencode-plugin/main/install.sh | bash

This downloads three things into your .opencode/ directory:

• plugins/replicate.ts — the plugin itself, registering four Replicate tools
• skills/replicate/SKILL.md — a companion skill with workflow guidance for the agent
• package.json — declares the @opencode-ai/plugin dependency (won’t overwrite an existing one)

The plugin is installed at the project level. You can also install it globally by copying the files to ~/.config/opencode/ — see the plugin’s README for details.

Restart OpenCode

Plugins are loaded at startup. Quit and reopen OpenCode Desktop, then use the prompt below to continue.

Try it

Once you’re back, ask OpenCode something like:

What’s my Replicate username?

The agent should call the replicate_whoami tool and return your account info. That confirms the plugin is loaded and your API token is working.

Now try something more interesting:

Generate a video of a cat in a spacesuit

Watch as the agent searches for an image generation model, checks its input schema, runs a prediction, and presents the result — all through the plugin’s tools, guided by the companion skill.

Find more plugins

The OpenCode ecosystem page lists community-built plugins for logging, notifications, analytics, and more. Anyone can create and share a plugin — if you’ve built something useful, consider publishing it for others to use.