### Configuration discovery example from a subdirectory

Source: https://opencode.ai/v2/docs/config

Example directory tree when starting OpenCode from /home/user/projects/acme/packages/web. Shows direct and .opencode config files that are discovered.

```plaintext
/etc/opencode/opencode.json
~/.config/opencode/opencode.json

/home/user/projects/acme/
├── opencode.json
└── packages/
    └── web/
        ├── opencode.json
        └── src/
```

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

### Define keymap layer in async setup

Source: https://opencode.ai/v2/docs/build/plugins/cli

Call layer from setup, including after an await, or from a component. This example shows an async setup function that loads settings and then defines a keymap layer.

```javascript
async setup(context) {
  const settings = await loadSettings()
  context.keymap.layer(() => ({
    mode: "global",
    commands: [{ id: "acme.sync", title: "Sync Acme", palette: true, run: () => sync(settings) }],
  }))
}
```

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

### Plugin lifecycle with cleanup function

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

The setup function runs when the plugin loads. It may return a cleanup function that runs when the plugin unloads. This example logs the OpenCode version on load and a message on unload.

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

export default Plugin.define({
  id: "example",
  setup(ctx) {
    console.log(`loaded in OpenCode ${ctx.app.version}`)
    return () => console.log("unloaded")
  },
})
```

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

### Install @opencode/client with Bun

Source: https://opencode.ai/v2/docs/build/client

Install the @opencode/client package into your project using Bun.

```bash
bun add @opencode/client
```

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

### Return a cleanup function from setup

Source: https://opencode.ai/v2/docs/build/plugins/cli

Return a function from setup to clean up resources owned by the plugin, such as event listeners. The example unsubscribes from a session execution event.

```typescript
setup(context) {
  const stop = context.data.on("session.execution.succeeded", () => {})
  return () => stop()
}
```

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

### Start the API and web server with opencode serve

Source: https://opencode.ai/v2/docs/cli/commands

Starts the API and web server. See Web.

```shell
$ opencode serve
```

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

### Start mini with model and initial prompt

Source: https://opencode.ai/v2/docs/cli/commands

Starts the minimal interface with a specified model and an initial prompt.

```shell
$ opencode mini --model anthropic/claude-sonnet-4-5 --prompt "Summarize this repository"
```

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

### Install a plugin to global configuration

Source: https://opencode.ai/v2/docs/cli/commands

Installs a plugin and adds it to the global configuration.

```shell
$ opencode plugin add @example/opencode-tui
```

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

### Example storage path on Linux

Source: https://opencode.ai/v2/docs/references

Example storage path on a typical Linux installation for the Effect-TS/effect repository.

```text
~/.local/share/opencode/repos/github.com/Effect-TS/effect
```

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

### Start the background server with opencode service start

Source: https://opencode.ai/v2/docs/cli/commands

Manages the background server. See Web.

```shell
$ opencode service start
```

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

### Install @opencode/sdk

Source: https://opencode.ai/v2/docs/build/sdk

Install the SDK package into your project using the Bun package manager.

```shell
bun add @opencode/sdk
```

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

### Example prompt for authentication explanation

Source: https://opencode.ai/v2/docs/cli/tui

Type a natural language request in the OpenCode prompt and press Enter to get an explanation.

```text
Explain how authentication works in this project
```

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

### Install OpenCode CLI with AUR

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

Installs the OpenCode beta package from the AUR using paru.

```bash
paru -S opencode-beta
```

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

### Install @opencode/client and effect

Source: https://opencode.ai/v2/docs/build/client/effect

Installs the Effect-native client package along with the effect dependency.

```bash
bun add @opencode/client effect
```

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

### Timing example: warming starts after normal request

Source: https://opencode.ai/v2/docs/warming

Shows the timing of warming requests after a normal model request. Warming starts after a non-warming request, and the active window is not extended by warming requests.

```text
00:00  normal model request
00:04  warming request
00:08  warming request
00:30  warming stops
```

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

### Read plugin options from ctx.options

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

During setup, access the options passed in opencode.json(c) via ctx.options. This example checks if the strict option is true.

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

export default Plugin.define({
  id: "company",
  setup(ctx) {
    const strict = ctx.options.strict === true
  },
})
```

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

### Plugin.define

Source: https://opencode.ai/v2/docs/build/plugins/cli

Defines a CLI plugin with an id and a setup function. The setup function receives a context object and can return a cleanup function.

```APIDOC
## Plugin.define

### Description
Creates a CLI plugin definition. The setup function is called when the plugin is loaded and receives a context object. It can return a cleanup function to release resources.

### Method
Plugin.define

### Parameters
- **id** (string) - Required - Unique identifier for the plugin.
- **setup** (function) - Required - Function that receives the context and optionally returns a cleanup function.

### Setup Context
- **options** (object) - Plugin configuration options.
- **app** (object) - App metadata including version and channel.
- **location** (object) - Current location.
- **client** (object) - OpenCode client for calling the server.
- **data** (object) - Cached data and event APIs.
- **theme** (object) - Theme tokens.
- **renderer** (object) - OpenTUI renderer.
- **ui** (object) - UI APIs such as toast notifications.

### Example
```typescript
import { Plugin } from "@opencode/plugin/tui"

export default Plugin.define({
  id: "acme.cli",
  setup(context) {
    context.ui.toast.show({ message: "CLI plugin loaded", variant: "success" })
  },
})
```
```

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

### Install @effect/platform-node for the local background service

Source: https://opencode.ai/v2/docs/build/client/effect

The Node-only @opencode/client/effect/service entrypoint requires @effect/platform-node.

```bash
bun add @effect/platform-node
```

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

### Install Effect SDK dependencies

Source: https://opencode.ai/v2/docs/build/sdk/effect

Install the Effect SDK and the Effect library using bun.

```bash
bun add @opencode/sdk effect
```

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

### Install OpenCode CLI with Bun

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

Installs the OpenCode CLI globally with Bun. The `--trust` flag explicitly allows the required postinstall script.

```bash
bun install -g --trust @opencode/cli
```

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

### Install OpenCode CLI with Yarn

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

Installs the OpenCode CLI globally with Yarn.

```bash
yarn global add @opencode/cli
```

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

### List plugins with opencode plugin list

Source: https://opencode.ai/v2/docs/cli/commands

Lists installed plugins.

```shell
$ opencode plugin list
```

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

### Install OpenCode CLI with Vite+

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

Installs the OpenCode CLI globally with Vite+. Vite+ requires no additional flag.

```bash
vp install -g @opencode/cli
```

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

### Access context properties in setup

Source: https://opencode.ai/v2/docs/build/plugins/cli

The setup function receives configuration, app metadata, location, client, cached data, theme tokens, renderer, and UI APIs. Use these properties to read options, resolve location, and access the client and renderer.

```typescript
setup(context) {
  const compact = context.options.compact === true
  const location = context.location ?? context.data.location.default()
  const version = context.app.version
  const channel = context.app.channel
  const client = context.client
  const renderer = context.renderer
  const theme = context.theme
}
```

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

### Pack and install the plugin tarball with bun

Source: https://opencode.ai/v2/docs/build/plugins/effect

Test the installed package rather than only a workspace-linked copy. Use versions compatible with the OpenCode release you target.

```shell
bun pm pack
bun add ./opencode-acme-effect-plugin-1.0.0.tgz
```

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

### Install OpenCode CLI with npm

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

Installs the OpenCode CLI globally with npm. The npm package uses a postinstall script to select the native `opencode` binary for your platform.

```bash
npm install -g @opencode/cli
```

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

### Start an Agent Client Protocol server

Source: https://opencode.ai/v2/docs/cli/commands

Starts an Agent Client Protocol server over stdin and stdout for editor integrations. It runs until the client closes the connection.

```shell
$ opencode acp
```

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

### Create a basic OpenCode plugin in .opencode/plugins/example/index.ts

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

Place this file under .opencode/plugins/ to have it loaded automatically. The setup function runs when the plugin loads and can use ctx.storage.

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

export default Plugin.define({
  id: "example",
  async setup(ctx) {
    await ctx.storage.set("loaded", true)
  },
})
```

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

### Start OpenCode from a project directory

Source: https://opencode.ai/v2/docs/cli/tui

Run OpenCode from your project directory to begin a session. Then type a request and press Enter.

```shell
cd ~/code/my-project
opencode
```

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

### Connect OpenCode Go subscription and select a model

Source: https://opencode.ai/v2/docs/providers

Subscribe in the console and copy your API key first. Select OpenCode Go in /connect, paste the API key, then run /models.

```shell
/connect
# Select OpenCode Go, then paste your API key.
/models
```

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

### Example workspace config response

Source: https://opencode.ai/v2/docs/console/api

This JSON shows the structure of a successful response from GET /api/v2/config, including providers, settings, headers, and models.

```json
{
  "providers": {
    "opencode": {
      "name": "OpenCode",
      "env": ["OPENCODE_CONSOLE_TOKEN"],
      "package": "aisdk:@ai-sdk/openai-compatible",
      "settings": {
        "baseURL": "https://opencode.ai/inference/openai/v1",
        "apiKey": "{env:OPENCODE_CONSOLE_TOKEN}"
      },
      "headers": { "x-opencode-org-id": "org_..." },
      "models": {
        "kimi-k2.6": { "name": "Kimi K2.6" }
      }
    }
  }
}
```

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

### Manage projects and saved permissions

Source: https://opencode.ai/v2/docs/build/plugins/cli

Projects and saved permissions support list, lookup, sync, and invalidate operations. The example syncs, lists, gets, and invalidates projects.

```typescript
await context.data.project.sync()
const projects = context.data.project.list()
const project = context.data.project.get(projectID)
context.data.project.invalidate()
```

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

### Store, read, and remove JSON values with Effect storage

Source: https://opencode.ai/v2/docs/build/plugins/effect

Use ctx.storage to set, get, and remove a JSON value scoped to the plugin ID. The example logs the retrieved settings after setting and before removing.

```typescript
effect: (ctx) =>
  Effect.gen(function* () {
    const storage = ctx.storage
    yield* storage.set("settings", { strict: true })
    const settings = yield* storage.get("settings")
    yield* Effect.logInfo("settings", { settings })
    yield* storage.remove("settings")
  }),
```

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

### Install OpenCode CLI with curl

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

Installs the OpenCode CLI using the official install script. Windows package managers are not supported.

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

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

### Install OpenCode CLI with mise

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

Installs OpenCode globally with mise. Requires mise 2026.10.9 or later; older versions install OpenCode 1.

```bash
mise use -g opencode
```

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

### POST /api/worktree

Source: https://opencode.ai/v2/docs/api

Load the project's canonical configuration, create a local worktree using its selected strategy, then run the project's setup script.

```APIDOC
## POST /api/worktree

### Description
Load the project's canonical configuration, create a local worktree using its selected strategy, then run the project's setup script.

### Method
POST

### Endpoint
`/api/worktree`

### Operation ID
`worktree.create`

### Request Body
Required. Content type: `application/json`. Schema: `Worktree.CreateInput`.

### Response

#### Success Response (200)
- **Worktree.Info** (application/json) - Information about the created worktree.

#### Error Responses
- **400** WorktreeError | InvalidRequestError (application/json)
- **401** UnauthorizedError (application/json)
- **404** ProjectNotFoundError (application/json)
```

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

### OpenCode.create(options?)

Source: https://opencode.ai/v2/docs/build/sdk

Initializes and returns an explicitly owned in-memory OpenCode host instance. Accepts configuration options such as initial plugins.

```APIDOC
## OpenCode.create(options?)

### Description
Creates an in-memory OpenCode host instance. Assembles the server and routes API calls directly through its in-memory router.

### Signature
`OpenCode.create(options?: { plugins?: Plugin[] }): Promise<OpenCodeInstance>`

### Parameters
- **options** (object) - Optional - Configuration options for initializing the host.
  - **plugins** (Plugin[]) - Optional - Array of plugins to register at startup.

### Usage Example
```typescript
import { OpenCode } from "@opencode/sdk"

await using opencode = await OpenCode.create({
  plugins: [plugin]
})
```
```

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

### Install plugins using Git and npm package specifications

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

Add plugins using npm tags or Git sources, including GitHub shortcuts, SSH urls, and npm subdirectory selectors.

```bash
opencode plugin add @acme/opencode-plugin@latest
opencode plugin add github:acme/opencode-plugin
opencode plugin add git+ssh://git@github.com/acme/opencode-plugin.git#main
opencode plugin add 'github:acme/plugins#main::path:packages/opencode-plugin'
```

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

### Create AGENTS.md project instructions

Source: https://opencode.ai/v2/docs/instructions

Add this file to give OpenCode persistent project guidance such as build commands, architecture notes, and conventions. Commit it so everyone in the repository receives the same guidance.

```markdown
# Project instructions

- Run `bun typecheck` after changing TypeScript.
- Keep database queries in `src/database`.
- Do not edit generated files directly.
```

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

### GET /api/vcs

Source: https://opencode.ai/v2/docs/api

Get current and default branch information for the requested location.

```APIDOC
## GET /api/vcs

### Description
Get current and default branch information for the requested location.

### Method
GET

### Endpoint
/api/vcs

### Operation ID
vcs.get

### Parameters
#### Query Parameters
- **location** (object | null) - Optional - Location object with a directory string, or null

### Responses
- **200** Success (application/json)
  - **location** (Location.PublicRef)
  - **data** (Vcs.Info)
- **400** InvalidRequestError (application/json InvalidRequestErrorEncoded)
- **401** UnauthorizedError (application/json UnauthorizedErrorEncoded)
- **404** LocationNotFoundError (application/json LocationNotFoundErrorEncoded)
```

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

### Attach a local file with a prompt

Source: https://opencode.ai/v2/docs/attachments

Use this prompt to ask OpenCode to summarize an attached file and list setup steps. The file is attached via the client's file picker or drag-and-drop.

```text
Summarize the attached README.md and list the required setup steps.
```

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

### Attach a file to the prompt using @

Source: https://opencode.ai/v2/docs/cli/tui

Type @ to search for a file, then select it to attach that file to the prompt. Keep typing after @ to narrow results.

```text
Review @src/auth.ts for error handling problems
```

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

### Explain command argument expansion

Source: https://opencode.ai/v2/docs/commands

Example of how the explain command prompt is expanded when invoked with a specific file path.

```text
Explain this code clearly.

src/cache.ts
```

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

### Install OpenCode CLI with Homebrew

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

Installs the OpenCode CLI from the anomalyco tap using Homebrew.

```bash
brew install anomalyco/tap/opencode-v2
```

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

### Configure keybinds and leader timeout in cli.json

Source: https://opencode.ai/v2/docs/cli/keybinds

Example cli.json showing keybinds for leader, command palette, app exit, and app debug, plus leader timeout.

```json
{
  "keybinds": {
    "leader": "ctrl+space",
    "command.palette.show": "ctrl+k",
    "app.exit": ["ctrl+c", "ctrl+d"],
    "app.debug": false
  },
  "leader": {
    "timeout": 1500
  }
}
```

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

### GET /api/pty/{ptyID}

Source: https://opencode.ai/v2/docs/api

Get one PTY session, including its exit code once exited.

```APIDOC
## GET /api/pty/{ptyID}

### Description
Get one PTY session, including its exit code once exited.

### Method
GET

### Endpoint
/api/pty/{ptyID}

### Operation ID
`pty.get`

### Parameters

#### Path Parameters
- **ptyID** (`Pty.ID`) - Required

#### Query Parameters
- **location** (`object | null`) - Optional - Object with `directory` (`string | null`), or null

### Responses

#### Success Response (200)
Content type: `application/json`

- **location** (`Location.PublicRef`)
- **data** (`Pty`)

#### Error Response (400)
Content type: `application/json`

- `InvalidRequestError` (`InvalidRequestErrorEncoded`)

#### Error Response (401)
Content type: `application/json`

- `UnauthorizedError` (`UnauthorizedErrorEncoded`)

#### Error Response (404)
Content type: `application/json`

- `PtyNotFoundError` (`PtyNotFoundErrorEncoded`) or `LocationNotFoundError` (`LocationNotFoundErrorEncoded`)
```

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

### Stop and start service explicitly

Source: https://opencode.ai/v2/docs/troubleshooting

Use to stop and then start the background service in separate steps.

```shell
opencode service stop
opencode service start
```

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

### GET /api/shell/{id}

Source: https://opencode.ai/v2/docs/api

Get one shell command, including its status and exit code once exited.

```APIDOC
## GET /api/shell/{id}

### Description
Get one shell command, including its status and exit code once exited.

### Method
GET

### Endpoint
/api/shell/{id}

### Parameters
#### Path Parameters
- **id** (Shell.ID) - Required

#### Query Parameters
- **location** (object | null) - Optional - Location scope; object with `directory` (string | null) or null

### Response
#### Success Response (200)
- **location** (Location.PublicRef) - Location reference
- **data** (Shell.Info) - Shell command info

#### Error Responses
- **400** InvalidRequestError (application/json)
- **401** UnauthorizedError (application/json)
- **404** ShellNotFoundError | LocationNotFoundError (application/json)
```

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

### Run standalone server with opencode serve

Source: https://opencode.ai/v2/docs/cli/web

Use `opencode serve` to run the server in the foreground with custom hostname and port. The output shows the listening address and password.

```shell
$ opencode serve --hostname 0.0.0.0 --port 4096
server listening on http://0.0.0.0:4096
server password <password>
```

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

### Create an OpenCode client and prompt a session

Source: https://opencode.ai/v2/docs/build/client

Initialize an OpenCode client instance with a server URL, create a session tied to a directory, and send a prompt request.

```typescript
import { OpenCode } from "@opencode/client"

const client = OpenCode.make({
  baseUrl: "http://localhost:4096",
})

const session = await client.session.create({
  location: { directory: "/workspace" },
})

await client.session.prompt({
  sessionID: session.id,
  text: "Review the current changes",
})
```

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

### Run /connect in OpenCode to choose a workspace

Source: https://opencode.ai/v2/docs/console

Run this command in OpenCode after signing in to the Console and subscribing to Go, adding credits, or connecting a provider. It lets you choose the workspace to connect to.

```shell
/connect
```

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

### GET /api/config

Source: https://opencode.ai/v2/docs/api

Get configuration documents and discovery sources for the requested location, ordered from lowest to highest priority.

```APIDOC
## GET /api/config

### Description
Return configuration documents and discovery sources for the requested location, from lowest to highest priority.

### Method
GET

### Endpoint
/api/config

### Parameters
#### Query Parameters
- **location** (object | null) - Optional - Location object with a `directory` string field, or null.

### Response
#### Success Response (200)
- **Config.Entry[]** - Array of configuration entries.

#### Error Responses
- **400** - InvalidRequestError
- **401** - UnauthorizedError
- **404** - LocationNotFoundError
```

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

### Run foreground server with inline proxy variables

Source: https://opencode.ai/v2/docs/network

Applies proxy and loopback environment settings directly to an opencode serve foreground server process.

```bash
HTTPS_PROXY=http://proxy.example.com:8080 \
NO_PROXY=localhost,127.0.0.1,::1 \
opencode serve
```

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

### GET /api/agent/{agentID}

Source: https://opencode.ai/v2/docs/api

Get agent. Retrieves a single currently registered agent. Operation ID: agent.get.

```APIDOC
## GET /api/agent/{agentID}

### Description
Retrieve a single currently registered agent.

### Method
GET

### Endpoint
/api/agent/{agentID}

### Parameters
#### Path Parameters
- **agentID** (Agent.ID) - Required - No description

#### Query Parameters
- **location** (object | null) - Optional - No description
  - **directory** (string | null) - No description

### Response
#### Success Response (200)
- **location** (Location.PublicRef)
- **data** (Agent.Info)

#### Error Responses
- **400** InvalidRequestError (application/json, InvalidRequestErrorEncoded)
- **401** UnauthorizedError (application/json, UnauthorizedErrorEncoded)
- **404** AgentNotFoundError | LocationNotFoundError (application/json, AgentNotFoundErrorEncoded | LocationNotFoundErrorEncoded)
```

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

### Start minimal interactive interface with opencode mini

Source: https://opencode.ai/v2/docs/cli/commands

Launches the minimal interactive interface instead of the full-screen TUI.

```shell
$ opencode mini
```

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

### Start MCP OAuth flow with opencode mcp auth

Source: https://opencode.ai/v2/docs/mcp-servers

CLI command to start the same OAuth flow as selecting the server in `/mcps`.

```bash
opencode mcp auth sentry
```

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

### View serve subcommands and flags with opencode serve --help

Source: https://opencode.ai/v2/docs/cli/commands

Lists all subcommands and flags for the serve command.

```shell
$ opencode serve --help
```

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

### Install Effect plugin dependencies

Source: https://opencode.ai/v2/docs/build/plugins/effect

Install @opencode/plugin and effect as peer dependencies for local type-checking and testing. OpenCode provides these at runtime, so do not bundle them.

```bash
bun add --peer @opencode/plugin effect
```

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

### Set TAVILY_API_KEY before starting OpenCode

Source: https://opencode.ai/v2/docs/websearch

Set the provider's environment variable before starting OpenCode to connect a provider without using /connect.

```shell
$ TAVILY_API_KEY=your-key opencode
```

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

### List all available models with opencode models

Source: https://opencode.ai/v2/docs/cli/commands

Lists every available model.

```shell
$ opencode models
```

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

### Refresh eligibility examples

Source: https://opencode.ai/v2/docs/references

Eligibility examples: a checkout is eligible when its last refresh attempt was at least 24 hours ago, or when no attempt has been recorded.

```text
Last attempt: 25 hours ago → eligible
Last attempt: 2 hours ago  → skipped
```

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

### Install OpenCode CLI with pnpm

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

Installs the OpenCode CLI globally with pnpm. The `--allow-build` flag explicitly allows the required postinstall script.

```bash
pnpm add -g --allow-build=@opencode/cli @opencode/cli
```

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

### Project configuration file paths

Source: https://opencode.ai/v2/docs/config

Put project settings in either of these files.

```plaintext
/home/user/projects/my-app/opencode.json(c)
/home/user/projects/my-app/.opencode/opencode.json(c)
```

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

### Global configuration file path

Source: https://opencode.ai/v2/docs/config

Put user settings for every project in the global configuration file.

```plaintext
~/.config/opencode/opencode.json(c)
```

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

### cli.json plugin list

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

Example of a cli.json file listing plugins by name, version, path, or file URL. Entries are processed in order.

```json
{
  "plugins": [
    "opencode.example",
    "opencode.example@1.0.0",
    "@example/opencode-tui",
    "@example/opencode-tui@1.0.0",
    "./plugins/status",
    "../plugins/status",
    "/home/user/plugins/status",
    "file:///home/user/plugins/status"
  ]
}
```

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

### Create opencode.jsonc with schema and model

Source: https://opencode.ai/v2/docs/config

Minimal project configuration file. Include the $schema for editor validation and set only the options you need.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
}
```

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

### Configure update checks with update

Source: https://opencode.ai/v2/docs/config

Set update to "disable" to skip checks, "notify" to show available updates before installing, or "auto" to install automatically. When omitted, update defaults to "notify"; automatic installation does not restart a running server, and project-level values are ignored.

```json
{
  "update": "notify",
}
```

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

### List Models and Get Default Selection

Source: https://opencode.ai/v2/docs/build/plugins/effect

Use ctx.model.list() to retrieve all available models and ctx.model.default() to get the currently selected default. Both effects are run with Effect.orDie to handle errors.

```typescript
effect: (ctx) =>
  Effect.gen(function* () {
    const model = ctx.model
    const models = yield* model.list().pipe(Effect.orDie)
    const selected = yield* model.default().pipe(Effect.orDie)
    yield* Effect.logInfo("models", { count: models.data.length, selected: selected.data?.name })
  }),
```

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

### Connect a provider and choose a model in the TUI

Source: https://opencode.ai/v2/docs/cli/providers

Run /connect to pick an integration, then /models to select one of its models. /connect lists integrations available from the current server and project.

```shell
/connect
/models
```

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

### Unset CORS configuration

Source: https://opencode.ai/v2/docs/troubleshooting

Remove the configured CORS list. Setting or unsetting service configuration stops the background service; use opencode service start to start it explicitly.

```shell
opencode service unset cors
```

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

### POST /api/vcs/init

Source: https://opencode.ai/v2/docs/api

Initialize a repository using the selected VCS provider in a markerless project's directory and refresh its location services. Omitting provider defaults to git; built-in git and hg providers support initialization. An unknown provider returns 400; a registered provider without init returns 501.

```APIDOC
## POST /api/vcs/init

### Description
Initialize a repository using the selected VCS provider in a markerless project's directory and refresh its location services. Omitting provider defaults to git; built-in git and hg providers support initialization. An unknown provider returns 400; a registered provider without init returns 501.

### Method
POST

### Endpoint
/api/vcs/init

### Operation ID
vcs.init

### Parameters
#### Query Parameters
- **location** (object | null) - Optional - Location object with a directory string, or null
- **provider** (string | null) - Optional - VCS provider; defaults to git

### Responses
- **204** No Content
- **400** InvalidRequestError (application/json InvalidRequestErrorEncoded)
- **401** UnauthorizedError (application/json UnauthorizedErrorEncoded)
- **404** LocationNotFoundError (application/json LocationNotFoundErrorEncoded)
- **409** ConflictError (application/json ConflictErrorEncoded)
- **501** VcsInitNotSupportedError (application/json VcsInitNotSupportedErrorEncoded)
- **503** ServiceUnavailableError (application/json ServiceUnavailableErrorEncoded)
```

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

### Connect client to standalone server

Source: https://opencode.ai/v2/docs/cli/web

Use `opencode --server <url>` to connect a client to a running standalone server.

```shell
$ opencode --server http://127.0.0.1:4096
```

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

### Export V1 server() and V2 setup() from src/index.ts

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

Default-export one object combining a V2 Plugin.define(...) definition (with id and setup()) and a V1 server() function returning hooks. V1 calls server(); V2 reads id and setup() and ignores server(). Spread Plugin.define(...) so the V2 definition type-checks separately from server().

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

export default {
  ...Plugin.define({
    id: "example",
    async setup(ctx) {
      await ctx.tool.hook("execute.before", () => {
        console.log("A tool is about to run")
      })
    },
  }),
  async server() {
    return {
      "tool.execute.before": async () => {
        console.log("A tool is about to run")
      },
    }
  },
}
```

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

### Start Ollama and pull a model

Source: https://opencode.ai/v2/docs/providers

Start the Ollama server and pull a model; OpenCode probes http://127.0.0.1:11434 and adds discovered completion models to /models without an account connection.

```shell
ollama serve
ollama pull qwen3:8b
```