- Updated the documentation to indicate the total number of middleware hooks has increased from 18 to 19. - Adjusted references in the getting-started-plugin guide to ensure consistency with the updated middleware hook count. - Corrected the middleware hooks section in the plugin template to reflect the accurate total.
12 KiB
Getting Started: Your First Plugin
This is a hands-on tutorial that walks you through creating, developing, testing, and publishing an OpenACP plugin from scratch. No prior knowledge of OpenACP internals is required.
Looking for the full API reference? See Writing Plugins — Full API Reference for every API surface including services, middleware, events, settings, storage, and overrides.
Prerequisites
- Node.js 18+ installed
- npm or pnpm installed
- OpenACP installed globally (
npm install -g @openacp/cli) - A working OpenACP setup (run
openacp onboardif you haven't yet)
Step 1: Scaffold a New Plugin
Run the scaffold command:
openacp plugin create
You will be prompted for:
◆ Create a new OpenACP plugin
│
◇ Plugin name (e.g., @myorg/adapter-matrix)
│ @myorg/hello-world
│
◇ Description
│ A greeting plugin for OpenACP
│
◇ Author
│ Your Name <you@example.com>
│
◇ License
│ MIT
│
◆ Plugin scaffolded!
│
│ Next steps
│
│ cd hello-world
│ npm install
│ npm run build
│ npm test
│
│ # Start development with hot-reload:
│ openacp dev .
│
└ Plugin @myorg/hello-world created in ./hello-world
The scaffold creates a directory named after your plugin (without the scope prefix):
hello-world/
src/
index.ts # Plugin entry point
__tests__/
index.test.ts # Test file
package.json
tsconfig.json
.gitignore
.npmignore
.editorconfig
README.md
CLAUDE.md # AI agent context (for Claude, Cursor, etc.)
PLUGIN_GUIDE.md # Human-readable developer guide
Step 2: Explore the Template
The scaffold generates two documentation files to help you (and your tools) work with the plugin:
- CLAUDE.md — A comprehensive technical reference for AI coding agents. Contains the full plugin API, all 19 middleware hooks, permissions, testing utilities, and code patterns. An agent with zero prior context can read this file and write a complete plugin.
- PLUGIN_GUIDE.md — A shorter, practical guide for human developers. Covers the development workflow, code examples for common tasks (commands, services, middleware, settings), testing, and publishing.
package.json
Key fields in the generated package.json:
{
"name": "@myorg/hello-world",
"version": "0.1.0",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
"test": "vitest",
"prepublishOnly": "npm run build"
},
"engines": {
"openacp": ">=2026.0327.1"
},
"peerDependencies": {
"@openacp/cli": ">=2026.0327.1"
},
"devDependencies": {
"@openacp/plugin-sdk": "^1.0.0",
"typescript": "^5.4.0",
"vitest": "^3.0.0"
}
}
The engines.openacp field declares the minimum OpenACP CLI version required by your plugin. When users install your plugin, OpenACP checks this field and warns if their CLI version is too old. The peerDependencies on @openacp/cli serves the same purpose for npm's dependency resolver.
The @openacp/plugin-sdk package provides all types, base classes, and testing utilities you need.
src/index.ts
The generated entry point contains every lifecycle hook with inline documentation:
import type { OpenACPPlugin, PluginContext, InstallContext, MigrateContext } from '@openacp/plugin-sdk'
const plugin: OpenACPPlugin = {
name: '@myorg/hello-world',
version: '0.1.0',
description: 'A greeting plugin for OpenACP',
permissions: ['events:read', 'services:register'],
async setup(ctx: PluginContext): Promise<void> {
// Called during server startup. Register services, commands, middleware here.
},
async teardown(): Promise<void> {
// Called during server shutdown. Clean up resources.
},
async install(ctx: InstallContext): Promise<void> {
// Called on `openacp plugin add`. Gather configuration interactively.
},
async configure(ctx: InstallContext): Promise<void> {
// Called on `openacp plugin configure`. Update settings.
},
async migrate(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown> {
// Called on boot when version changes. Migrate settings.
return oldSettings
},
async uninstall(ctx: InstallContext, opts: { purge: boolean }): Promise<void> {
// Called on `openacp plugin remove`. Clean up external resources.
},
}
export default plugin
Lifecycle hooks summary:
| Hook | When it runs | Purpose |
|---|---|---|
setup(ctx) |
Server startup (dependency order) | Register services, commands, middleware, event listeners |
teardown() |
Server shutdown (reverse order) | Clean up timers, connections, resources |
install(ctx) |
openacp plugin add |
Interactive first-time configuration |
configure(ctx) |
openacp plugin configure |
Re-configure settings |
migrate(ctx, old, ver) |
Boot, when version changed | Migrate settings between versions |
uninstall(ctx, opts) |
openacp plugin remove |
Clean up external resources |
Step 3: Development Workflow
Install dependencies and build:
cd hello-world
npm install
npm run build
Hot-reload development
Start OpenACP in dev mode, pointing to your plugin directory:
openacp dev .
This will:
- Compile your TypeScript
- Start
tsc --watchin the background - Boot OpenACP with your plugin loaded
- Reload your plugin automatically when files change
See Dev Mode for the full guide.
Run tests
npm test
Tests use Vitest and the @openacp/plugin-sdk/testing utilities.
Step 4: Implement Your Plugin
Let's turn the template into a greeting plugin that responds to a /hello command and logs session events.
Replace the contents of src/index.ts:
import type { OpenACPPlugin, PluginContext, InstallContext } from '@openacp/plugin-sdk'
const plugin: OpenACPPlugin = {
name: '@myorg/hello-world',
version: '0.1.0',
description: 'A greeting plugin for OpenACP',
permissions: ['events:read', 'commands:register'],
async setup(ctx: PluginContext): Promise<void> {
// Register a /hello command
ctx.registerCommand({
name: 'hello',
description: 'Send a greeting',
usage: '[name]',
category: 'plugin',
async handler(args) {
const name = args.raw.trim() || 'World'
return { type: 'text', text: `Hello, ${name}! 👋` }
},
})
// Listen to session events
ctx.on('session:created', (event) => {
ctx.log.info(`New session started: ${event.sessionId}`)
})
ctx.on('session:afterDestroy', (event) => {
ctx.log.info(`Session ended: ${event.sessionId} (${event.durationMs}ms)`)
})
ctx.log.info('Hello World plugin ready')
},
async teardown(): Promise<void> {
// Nothing to clean up
},
async install(ctx: InstallContext): Promise<void> {
ctx.terminal.log.success('Hello World plugin installed!')
},
}
export default plugin
Build and test:
npm run build
openacp dev .
Now in your messaging platform, type /hello or /hello Alice to see the plugin respond.
Step 5: Test Your Plugin
The scaffold includes a basic test. Let's expand it using the SDK testing utilities.
Replace src/__tests__/index.test.ts:
import { describe, it, expect } from 'vitest'
import { createTestContext, createTestInstallContext } from '@openacp/plugin-sdk/testing'
import plugin from '../index.js'
describe('@myorg/hello-world', () => {
it('has correct metadata', () => {
expect(plugin.name).toBe('@myorg/hello-world')
expect(plugin.version).toBe('0.1.0')
expect(plugin.permissions).toContain('commands:register')
})
it('registers the /hello command on setup', async () => {
const ctx = createTestContext({ pluginName: '@myorg/hello-world' })
await plugin.setup(ctx)
expect(ctx.registeredCommands.has('hello')).toBe(true)
expect(ctx.registeredCommands.get('hello')!.description).toBe('Send a greeting')
})
it('/hello with no args returns default greeting', async () => {
const ctx = createTestContext({ pluginName: '@myorg/hello-world' })
await plugin.setup(ctx)
const response = await ctx.executeCommand('hello', { raw: '' })
expect(response).toEqual({ type: 'text', text: 'Hello, World! 👋' })
})
it('/hello with a name returns personalized greeting', async () => {
const ctx = createTestContext({ pluginName: '@myorg/hello-world' })
await plugin.setup(ctx)
const response = await ctx.executeCommand('hello', { raw: 'Alice' })
expect(response).toEqual({ type: 'text', text: 'Hello, Alice! 👋' })
})
it('emits log on session events', async () => {
const ctx = createTestContext({ pluginName: '@myorg/hello-world' })
await plugin.setup(ctx)
// Simulate a session:created event
ctx.emit('session:created', { sessionId: 'test-123' })
// No error thrown = event handler works
})
it('installs without errors', async () => {
const ctx = createTestInstallContext({
pluginName: '@myorg/hello-world',
})
await plugin.install!(ctx)
// Verify the install function ran
expect(ctx.terminalCalls).toHaveLength(0) // no prompts needed
})
it('tears down without errors', async () => {
await expect(plugin.teardown!()).resolves.not.toThrow()
})
})
Run:
npm test
See Plugin SDK Reference for the full testing API including createTestContext, createTestInstallContext, and mockServices.
Step 6: Configure and Install
Install your plugin locally
For testing with a real OpenACP instance (not dev mode):
# From the plugin directory, build first
npm run build
# Install from local path
openacp plugin add ./hello-world
Plugin settings
If your plugin needs configuration (API keys, preferences), define a settingsSchema with Zod and use the install() hook:
import { z } from 'zod'
const settingsSchema = z.object({
defaultName: z.string().default('World'),
})
const plugin: OpenACPPlugin = {
// ...
settingsSchema,
async install(ctx: InstallContext) {
const name = await ctx.terminal.text({
message: 'Default greeting name:',
placeholder: 'World',
})
await ctx.settings.set('defaultName', name || 'World')
ctx.terminal.log.success('Configured!')
},
async setup(ctx: PluginContext) {
const defaultName = ctx.pluginConfig.defaultName ?? 'World'
// Use defaultName in your command handler...
},
}
Enable / disable
openacp plugin enable @myorg/hello-world
openacp plugin disable @myorg/hello-world
Reconfigure
openacp plugin configure @myorg/hello-world
Step 7: Publish
Prepare for publishing
- Update
versionin bothpackage.jsonandsrc/index.ts - Make sure
mainpoints todist/index.js - Ensure
keywordsincludesopenacpandopenacp-plugin
Build and publish
npm run build
npm test
npm publish --access public
How users install your plugin
openacp plugin install @myorg/hello-world
This downloads from npm into ~/.openacp/plugins/, validates the plugin interface, and runs install() if defined.
List your plugin in the registry
After publishing to npm, add your plugin to the OpenACP Plugin Registry so users can discover it via openacp plugin search:
- Fork Open-ACP/plugin-registry
- Create
plugins/myorg--hello-world.jsonwith your plugin metadata - Submit a PR — CI auto-validates and auto-merges
See Contributing > Publishing a Plugin to the Registry for the full guide.
Next Steps
- Writing Plugins -- full reference for all plugin APIs (services, middleware, events, storage)
- Plugin SDK Reference -- complete API reference for types, base classes, and testing utilities
- Dev Mode -- detailed guide for the development workflow
- Plugin System -- how the plugin infrastructure works under the hood