OpenCode

https://opencode.ai/v2/docs
Admin
OpenCode is an AI-powered interactive command-line interface (CLI) and coding agent designed to...
Tokens:245,840
Snippets:2,755
Trust Score:8.4
Update:2 days ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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" }
      }
    }
  }
}
```

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

### Install OpenCode CLI with Yarn

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

Installs the OpenCode CLI globally with Yarn.

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

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

### 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
```

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

### 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)
  },
})
```

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

### 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
}
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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)
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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()
```

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

### 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
```

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

### 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'
```

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

### 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.
```

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

### Root model selection example

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

Example of setting the root model using the string selector form. Note that the V2 catalog default does not retain variants; select variants for a session, run, agent, or command instead.

```json
{
  "model": "openai/gpt-5.2"
}
```

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

### 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
  }
}
```

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

### 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
```

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

### 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")
      },
    }
  },
}
```

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

### Log file location

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

Installed builds write logs to this path.

```text
~/.local/share/opencode/log/opencode.log
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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"
  ]
}
```

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

### 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)
```

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

### V2 plugin definition with Plugin.define

Source: https://opencode.ai/v2/docs/build/plugins/migrate-v1

Port entrypoint to V2 by default-exporting `Plugin.define` with a stable `id` and initialization logic inside `setup`.

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

export default Plugin.define({
  id: "example",
  async setup(ctx) {
    await ctx.storage.set("last-project", ctx.location.project.id)
    console.log(`Loaded for ${ctx.location.directory}`)
  },
})
```

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

### Code Mode Tool Grouping Example

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

Demonstrates how tools are grouped by normalized server name under the default Code Mode.

```javascript
tools.context_7.resolve_library_id(...)
```

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

### 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")
  }),
```

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

### Access the OpenCode web interface with opencode pair

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

Runs `opencode pair` to start the web interface and prints the local URL, username, and password.

```bash
$ opencode pair

  URLs      http://127.0.0.1:49374
  Username  opencode
  Password  ********
```

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

### 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
```

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

### 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
```

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

### 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",
}
```

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

### 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]
})
```
```

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

### 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.
```

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

### Use positional arguments for comparison

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

Example showing how the highest-numbered placeholder consumes the remaining input string.

```markdown
Compare $1 with $2.
```

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

### Invoke an agent

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

Example prompt to trigger the reviewer subagent.

```text
Use the reviewer subagent to review my current changes.
```

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

### 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
```

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

### ,Print the database path with opencode debug paths

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

,Prints only the path and a newline; the database path respects the release channel and OPENCODE_DB. Does not start a server or open the database.

```,shell
,opencode debug paths db
sqlite3 "$(opencode debug paths db)"
```

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

### Configure plugins in opencode.jsonc

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

Add published packages, local directories, or object entries with options to the plugins array. This example shows various forms including scoped packages, versioned packages, relative paths, absolute paths, file URLs, and an object with options.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-acme-plugin",
    "opencode-acme-plugin@1.2.0",
    "@acme/opencode-plugin",
    "./plugins/local",
    "../shared/plugin",
    "/absolute/path/plugin",
    "file:///home/me/plugins/local",
    {
      "package": "@acme/opencode-plugin",
      "options": {
        "agent": "reviewer",
        "strict": true,
      },
    },
  ],
}
```

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

### Add Local MCP Server with Command

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

Use the `opencode mcp add` command with `--` to specify the server command. This starts a local server over the MCP stdio transport.

```bash
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything
```

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

### 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`)
```

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

### Ask OpenCode to search the web for the latest Bun release

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

Example prompt that triggers a web search. The first search asks you to allow web search and select a provider, and OpenCode remembers your choice for later sessions.

```text
Find the latest Bun release and summarize the changes.
```

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

### context.data.project

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

Manages projects: sync, list, get, and invalidate.

```APIDOC
## context.data.project

### Description
Manage projects.

### Methods
- **sync** () - Synchronizes projects.
- **list** () - Returns a list of projects.
- **get** (projectID) - Returns a project by ID.
- **invalidate** () - Invalidates cached projects.

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

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

### opencode.plugin(plugin)

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

Registers an additional plugin after the OpenCode host has started.

```APIDOC
## opencode.plugin(plugin)

### Description
Registers another plugin dynamically after startup.

### Signature
`opencode.plugin(plugin: Plugin): Promise<void>`

### Parameters
- **plugin** (Plugin) - Required - The plugin instance to register.

### Usage Example
```typescript
await opencode.plugin(plugin)
```
```

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

### Read a setting with opencode service get

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

Reads the hostname setting from the service configuration.

```shell
$ opencode service get hostname
```

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

### 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
```

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

### Place worktrees under each project's .lane/trees directory

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

A global configuration example that places new worktrees under each project's own `.lane/trees/` directory. Relative paths resolve against the project's saved canonical checkout.

```json
{
  "worktree": {
    "directory": ".lane/trees",
  },
}
```

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

### ctx.integration.command.connect

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

Starts a command-based connection attempt for an integration. Returns a promise that resolves to an attempt object containing an attemptID.

```APIDOC
## ctx.integration.command.connect

### Description
Start a command-based connection attempt.

### Method
`connect({ integrationID: string, methodID: string }): Promise<{ data: { attemptID: string } }>`

### Parameters
- **integrationID** (string) - Required - The ID of the integration.
- **methodID** (string) - Required - The ID of the command method.

### Returns
A promise that resolves to an object containing the attempt ID.

### Example
```javascript
const attempt = await ctx.integration.command.connect({ integrationID: "acme", methodID: "cli" })
```
```

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

### 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)
```

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

### Persist proxy settings for background service using opencode service set env

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

Saves proxy environment variables into the managed service configuration and starts the service. Changing managed environment variables stops the running service until service start is executed.

```bash
opencode service set env HTTP_PROXY http://proxy.example.com:8080
opencode service set env HTTPS_PROXY http://proxy.example.com:8080
opencode service set env NO_PROXY localhost,127.0.0.1,::1
opencode service start
```

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

### 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
```

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

### Make a GET request to the running server

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

Makes a request to the running server using the api command.

```shell
$ opencode api GET /api/session
```

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

### 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 })
  }),
```

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

### Set EDITOR and start OpenCode

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

Set the VISUAL or EDITOR environment variable, then press Ctrl+X, then E, or run /editor, to edit the current prompt in that editor.

```shell
export EDITOR="nvim"
opencode
```

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

### 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)
```

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

### List Models and Get Default

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

Read available models and the default selection.

```typescript
const models = await ctx.model.list()
const selected = await ctx.model.default()
```

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

### MCP Prompt Command Name Example

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

Illustrates the command name generated from an MCP prompt using the normalized server name and prompt name.

```text
/context_7:find_docs
```

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

### Authenticate with an OAuth-capable MCP server

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

Starts authentication with an OAuth-capable remote MCP server.

```shell
$ opencode mcp auth sentry
```

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

### Connected MCP server status output

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

Example output from `opencode mcp list` showing a connected server ready for an agent to use.

```text
✓ context7  connected
```

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

### 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
```

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

### Define command fields in opencode.jsonc

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

Example of a JSON command configuration setting optional fields including template, description, agent, model, and subagent.

```json
{
  "commands": {
    "audit": {
      "template": "Audit $ARGUMENTS.",
      "description": "Audit a package",
      "agent": "general",
      "model": "anthropic/claude-sonnet-4-5#high",
      "subagent": true,
    },
  },
}
```

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

### List all available models with opencode models

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

Lists every available model.

```shell
$ opencode models
```

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

### Create an authenticated client for the ensured local service

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

Uses Service.ensure() to start the local background service, then builds a client with Service.headers(endpoint) and calls server.info(). Requires both FetchHttpClient.layer and NodeFileSystem.layer.

```typescript
import { NodeFileSystem } from "@effect/platform-node"
import { OpenCode } from "@opencode/client/effect"
import { Service } from "@opencode/client/effect/service"
import { Effect } from "effect"
import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http"

const program = Effect.gen(function* () {
  const endpoint = yield* Service.ensure()
  const httpClient = yield* HttpClient.HttpClient
  const client = yield* OpenCode.make({ baseUrl: endpoint.url }).pipe(
    Effect.provideService(
      HttpClient.HttpClient,
      HttpClient.mapRequest(httpClient, (request) => HttpClientRequest.setHeaders(request, Service.headers(endpoint))),
    ),
  )
  return yield* client.server.info()
})

const health = await Effect.runPromise(
  program.pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(NodeFileSystem.layer)),
)
```

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

### Configure Agent Mode

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

Example of setting an agent's mode to subagent within the configuration file.

```json
{
  "agents": {
    "reviewer": { "mode": "subagent" },
  },
}
```

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

### Define a Git-based reference entry

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

Example of a complete Git reference configuration using repository, branch, description, and hidden fields.

```json
{
  "references": {
    "sdk": {
      "repository": "example/sdk",
      "branch": "main",
      "description": "Use for SDK implementation details",
      "hidden": false,
    },
  },
}
```

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

### GET /api/config/shell

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

List shells available to terminal and agent execution.

```APIDOC
## GET /api/config/shell

### Description
Return shells available to terminal and agent execution.

### Method
GET

### Endpoint
/api/config/shell

### Response
#### Success Response (200)
- **ConfigShell.Option[]** - Array of shell options.

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

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

### 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)
```

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

### Read external file with permissions

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

Example of a read request for an external file, which is subject to active tool permissions.

```text
Read ../product-docs/api.md
```

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

### Google Generative AI endpoint example

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

Send a request to the /models/<model>:generateContent endpoint. Replace :generateContent with :streamGenerateContent to stream the response.

```bash
curl -X POST "https://opencode.ai/inference/custom/conn_.../models/gemini-3.1-pro:generateContent" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "Say hi" }] }]
  }'
```

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

### 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",
}
```

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

### Anthropic Compatible endpoint example

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

Send a request to the /messages endpoint. The max_tokens field is required.

```bash
curl -X POST "https://opencode.ai/inference/custom/conn_.../messages" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Say hi" }]
  }'
```

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

### Failure timing example

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

Shows that warming failures are logged without failing or changing the session, and the next attempt occurs at the next interval while the active window continues to count down.

```text
00:04  warming request fails; session is unchanged
00:08  next warming attempt
```

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

### 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
```

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

### Nested agent path resolution

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

Example of how a nested directory structure maps to an agent ID.

```text
.opencode/agents/team/reviewer.md  →  team/reviewer
```

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

### 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)
```

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

### 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
```

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

### GET /inference/v1/models

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

Fetch the live list of models available through the Console Inference API.

```APIDOC
## GET /inference/v1/models

### Description
Fetch the live list of models available through the Console Inference API.

### Method
GET

### Endpoint
`https://opencode.ai/inference/v1/models`

### Request Example
```
curl https://opencode.ai/inference/v1/models
```
```

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

### 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
```

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

### Configure service options

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

Use `opencode service set` to change hostname, port, password, CORS origins, or environment variables. Changing a setting stops the background server; run `opencode service start` to apply.

```shell
# Listen on every network interface
$ opencode service set hostname 0.0.0.0

# Use a fixed port instead of the channel default
$ opencode service set port 49374

# Replace the generated password
$ opencode service set password "a-long-secret"

# Allow a web client served from another origin
$ opencode service set cors https://app.example.com,https://other.example.com

# Pass an environment variable to the server process
$ opencode service set env OPENCODE_LOG_LEVEL DEBUG
```

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

### Combined AGENTS.md load order

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

All four files in the scope example are loaded and combined in this order. OpenCode combines the files and does not resolve conflicts between them.

```text
~/.config/opencode/AGENTS.md
packages/web/AGENTS.md
packages/AGENTS.md
AGENTS.md
```

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

### ctx.integration.oauth.connect

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

Starts an OAuth connection attempt for an integration. Returns a promise that resolves to an attempt object containing an attemptID.

```APIDOC
## ctx.integration.oauth.connect

### Description
Start an OAuth connection attempt.

### Method
`connect({ integrationID: string, methodID: string }): Promise<{ data: { attemptID: string } }>`

### Parameters
- **integrationID** (string) - Required - The ID of the integration.
- **methodID** (string) - Required - The ID of the OAuth method.

### Returns
A promise that resolves to an object containing the attempt ID.

### Example
```javascript
const attempt = await ctx.integration.oauth.connect({ integrationID: "github", methodID: "oauth" })
```
```

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

### Log in to OpenAI and list available methods

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

Method IDs are provider-specific. Run without --method to see the available methods when a provider has more than one.

```shell
opencode auth login openai
```

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

### GET /api/form

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

Retrieve pending forms for a location.

```APIDOC
## GET /api/form

### Description
Retrieve pending forms for a location.

### Method
GET

### Endpoint
/api/form

### Parameters
#### Query Parameters
- **location** (object) - Optional - Location filter. Can include a `directory` field (string or null).

### Response
#### Success Response (200)
- **location** (Location.PublicRef) - The location reference.
- **data** (Form.Info[]) - Array of pending form information.

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

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

### List and Inspect Integrations

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

Lists integrations, gets a specific integration, checks active connection, and resolves credentials.

```typescript
const integrations = await ctx.integration.list()
const github = await ctx.integration.get({ integrationID: "github" })
const connection = await ctx.integration.connection.active("github")
const credential = connection ? await ctx.integration.connection.resolve(connection) : undefined
```

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

### Authorization server metadata enabling CIMD

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

Example metadata showing an authorization server opting into CIMD with `client_id_metadata_document_supported` and `token_endpoint_auth_methods_supported`.

```json
{
  "issuer": "https://auth.example.com",
  "client_id_metadata_document_supported": true,
  "token_endpoint_auth_methods_supported": ["none"]
}
```