OpenCode Plugin Starter Kit

A minimal bootstrap for creating OpenCode plugins. Zero code to delete — just install, name, build, and start developing.

Quick Start

1. Copy the repo

Clone or copy this repo into a new directory for your plugin:

git clone https://github.com/<your-org>/opencode-plugin-starter.git my-plugin
cd my-plugin

Or use degit for a clean copy without git history:

bunx degit <repo-url> my-plugin
cd my-plugin

2. Bootstrap

Follow the steps in INSTRUCTIONS.md to set up your plugin. You can follow them manually or paste this into an OpenCode agent and let it do the work for you:

"Read INSTRUCTIONS.md and follow each step."

3. Start developing

Once bootstrapped, edit src/index.ts to add hooks, tools, or config modifications. See the Opencode plugin docs and the create-opencode-plugin skill's references/ directory for API guides, hook patterns, and examples.

What's Included

File	Purpose
package.json	Pre-configured with @opencode-ai/plugin, typescript, @types/bun, and a build script
tsconfig.json	Bun + ESNext + bundler module resolution
src/index.ts	Bare skeleton plugin — compiles and loads, does nothing
src/utils/config.ts	JSON config loader with two-tier path resolution
src/utils/env.ts	Environment variable parsing and coercion
src/utils/fs.ts	Filesystem helpers (atomic writes, project root detection)
src/utils/format.ts	Human-readable formatters (bytes, dates, costs, numbers)
tsup.config.ts	Build config — bundles src/index.ts into dist/index.js + dist/index.d.ts, externals @opencode-ai/plugin
.gitignore	node_modules/, dist/, .opencode/
INSTRUCTIONS.md	Step-by-step bootstrap guide (deleted after setup)
.opencode/skills/create-opencode-plugin/	Plugin development skill with API references, hook patterns, examples, and testing guides

Utilities

The src/utils/ directory contains zero-dependency helpers for common plugin operations: config loading (loadJsonConfig), env-var parsing (coerceValue, loadFromEnv), filesystem operations (atomicWriteFile, findProjectRoot), and human-readable formatters (formatBytes, formatRelative, etc.). Each module is documented inline — open the file to see usage examples.

Build & Publish

bun run build          # tsup -> dist/index.js + dist/index.d.ts

tsup traces imports from src/index.ts — only reachable code lands in the bundle. @opencode-ai/plugin is marked external, so consumers resolve it from their own install.

To publish to npm, remove "private": true from package.json and set "version", "description", "author", and "license". Only dist/ ships (controlled by "files").

bun publish --access public

Requirements

• Bun >= 1.0.0
• OpenCode

License

Mozilla Public License 2.0