OpenCode V2 migration guide: config, plugins and SDK

  OpenCode V1                             OpenCode V2
  ───────────────────────────             ──────────────────────────────────────
  opencode.json (permission, agent) ───>  same file works, native shape optional
  .opencode/ agents, skills, commands ─>  works unchanged
  tui.json                          ───>  ~/.config/opencode/cli.json (automatic)
  plugin: fn returning hooks        ───>  Plugin.define({ id, setup })   REWRITE
  @opencode-ai/sdk (and its /v2)    ───>  @opencode/client               REWRITE
  one server per client             ───>  one shared background service

12curl -fsSL https://opencode.ai/v2/install | bash
opencode --version

12Migrate my OpenCode configuration, including file-based definitions, from the V1 format
to the native V2 format. Preserve its behavior and all unrelated settings.

1234567891011121314// V1
{
  "permission": { "bash": { "git push *": "ask" }, "edit": "allow" },
  "tools": { "websearch": false }
}

// V2
{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

import { Plugin } from '@opencode/plugin'

export default Plugin.define({
  id: 'company.guard',
  async setup(ctx) {
    await ctx.tool.hook('execute.before', (event) => {
      const input = event.input as { filePath?: string }
      if (event.tool === 'read' && input.filePath?.includes('.env')) {
        throw new Error('Do not read .env files')
      }
    })

    await ctx.shell.hook('create.before', (event) => {
      event.env.COMPANY_ENV = 'development'
    })
  },
})

import { Plugin } from '@opencode/plugin'

export default Plugin.define({
  id: 'greeting',
  async setup(ctx) {
    await ctx.tool.transform((editor) => {
      editor.add({
        name: 'greeting',
        description: 'Create a greeting',
        input: {
          type: 'object',
          properties: { name: { type: 'string' } },
          required: ['name'],
          additionalProperties: false,
        },
        async execute(input) {
          return { content: `Hello ${(input as { name: string }).name}!` }
        },
      })
    })
  },
})

1await client.session.instructions.entry.put({ sessionID, key: 'my-integration', value: systemPrompt })

123456789import { OpenCode } from '@opencode/client'
import { Service } from '@opencode/client/service'

const endpoint =
  (await Service.discover({ file })) ??
  (await Service.ensure({ file, command: ['opencode', 'serve', '--service', '--hostname', '127.0.0.1'] }))

const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) })
const info = await client.server.info()

12345678910const session = await client.session.create({
  location: { directory },
  permissions: [{ action: 'edit', resource: `${directory}/**`, effect: 'allow' }],
})

await client.session.prompt({
  sessionID: session.id,
  text: 'Fix the failing test',
  delivery: 'steer',
})

  session.prompt({ delivery: 'steer' | 'queue' })
        │
        ├──> session.inbox.enqueued
        ├──> session.execution.started          start typing, start timer
        ├──> session.inbox.delivered            prompt is now visible history
        │
        ├──> session.text.delta ... session.text.ended          full text on ended
        ├──> session.tool.input.* ... session.tool.success | failed
        │
        └──> session.execution.succeeded | failed | interrupted