OpenCode

https://github.com/anomalyco/opencode
Admin
OpenCode is an open-source, provider-agnostic AI coding agent that offers LSP support, focuses on a...
Tokens:1,834,125
Snippets:10,697
Trust Score:9.6
License:MIT
Update:4 hours ago
Show doc for...
Tokens:
Raw
### Guided setup for AGENTS.md with /init

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/tui.mdx

Guided setup for creating or updating AGENTS.md.

```text
/init
```

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

### Start development environment

Source: https://github.com/anomalyco/opencode/blob/dev/packages/desktop/README.md

Install project dependencies and launch the OpenCode Desktop app in development mode.

```bash
bun install
bun dev
```

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

### Install dependencies and start development CLI/TUI

Source: https://github.com/anomalyco/opencode/blob/dev/CONTRIBUTING.md

Installs dependencies and runs the V2 CLI and TUI. Pass a directory path to target another project or . for the current repository.

```bash
bun install
bun dev [directory]
```

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

### Install the GitHub agent in your repository

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/cli.mdx

Sets up the necessary GitHub Actions workflow and guides you through the configuration process.

```bash
opencode github install
```

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

### Example directory tree for config discovery

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/config.mdx

OpenCode searches from the current directory to the filesystem root. This example shows the directory structure when starting from /home/user/projects/acme/packages/web.

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

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

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

### Start development server with npm run dev

Source: https://github.com/anomalyco/opencode/blob/dev/packages/console/app/README.md

Start the local development server after installing dependencies, with an optional flag to automatically open the application in a new browser tab.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

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

### Install @opencode/client and effect

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/client/effect.mdx

Install the Effect-native client and the Effect library using bun.

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

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

### Install a plugin and add to global configuration

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/cli/commands.mdx

Install a plugin and add it to the global configuration.

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

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

### Start mini with model and prompt

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/cli/commands.mdx

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

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

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

### Return a cleanup function from setup

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/cli.mdx

Return a cleanup function to release resources owned by the plugin. The example subscribes to session.execution.succeeded and returns a function that stops the subscription.

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

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

### Install @opencode/sdk

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/sdk/cloudflare.mdx

Installs the OpenCode SDK package via Bun.

```sh
bun add @opencode/sdk
```

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

### Start a new session with /new

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/tui.mdx

Start a new session. Alias: /clear. Keybind: ctrl+x n.

```text
/new
```

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

### Start the API and web server

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/cli/commands.mdx

Runs the `opencode serve` command to start the API and web server.

```bash
$ opencode serve
```

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

### Install the Effect SDK

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/sdk/effect.mdx

Install `@opencode/sdk` and `effect` dependencies using Bun.

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

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

### Start background server

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/cli/web.mdx

After changing a setting, start the background server again to apply the new config.

```bash
$ opencode service start
```

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

### Install OpenCode globally using Bun

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/index.mdx

Install the OpenCode package globally using Bun.

```bash
bun install -g opencode-ai
```

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

### Set custom installation directory with OPENCODE_INSTALL_DIR or XDG_BIN_DIR

Source: https://github.com/anomalyco/opencode/blob/dev/README.md

The install script respects $OPENCODE_INSTALL_DIR first, then $XDG_BIN_DIR, then $HOME/bin, and falls back to $HOME/.opencode/bin. Use these examples to override the installation path.

```bash
# Examples
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/v2/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/v2/install | bash
```

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

### Initial load and background plugin boot flow

Source: https://github.com/anomalyco/opencode/blob/dev/specs/v2/catalog-config-plugin-lifecycle.md

Illustrates building a baseline catalog from immediate sources while background fibers activate slower plugins asynchronously.

```ts
LocationServiceMap.get(ref)
  → build location layer
    → Catalog.layer creates empty catalog state
    → PluginBoot.layer activates immediately available plugins
      → ConfigProviderPlugin installs Catalog.transform()
      → ModelsDevPlugin installs Catalog.transform()
      → AuthPlugin installs Catalog.transform()
    → Catalog.layer applies active transforms during boot
    → apply policy
    → materialize baseline provider/model catalog
  → PluginBoot baseline ready
    → Frontend.fetchCatalog()

PluginBoot background fiber
  → install/update plugin packages concurrently
  → activate completed plugins
    → Catalog.transform()
      → transform(updateCatalog)
        → Catalog internally rebuilds
          → Catalog.Event.Updated
            → Frontend.refetchCatalog()
```

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

### Initialize project using /init

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/index.mdx

Analyzes the project and generates an AGENTS.md file in the project root.

```bash
/init
```

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

### Run Hermes model setup

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/console/harnesses/hermes.mdx

Run the model setup and select OpenCode Zen for pay-as-you-go or OpenCode Go for Go.

```bash
hermes model
```

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

### Build and run desktop startup benchmarks

Source: https://github.com/anomalyco/opencode/blob/dev/packages/desktop/README.md

Builds the desktop application with electron-builder and executes startup benchmark commands under various configurations, such as warm/cold services, A/B comparisons, and profiling flags.

```bash
OPENCODE_CHANNEL=dev bun run build && bunx electron-builder --win --dir --config electron-builder.config.ts
bun run bench:startup -- --runs 5                                  # warm service (started once, reused by every launch)
bun run bench:startup -- --runs 5 --compare dist/other/OpenCode\ Dev.exe   # A/B: alternate launches of two builds
bun run bench:startup -- --service cold                            # each launch spawns the service
bun run bench:startup -- --fresh                                   # first launch after an install (profile wiped each time)
bun run bench:startup -- --profile-main --profile-renderer --trace # CPU profiles and a Chromium startup trace
bun run bench:startup -- --seed "%APPDATA%\ai.opencode.desktop.dev"   # restore tabs and drafts from an existing profile
```

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

### Run desktop development startup benchmark

Source: https://github.com/anomalyco/opencode/blob/dev/packages/app/e2e/performance/README.md

Runs five serial samples of the bun dev:desktop startup sequence from the repository root.

```sh
bun run bench:devex
```

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

### Define a basic plugin with setup

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/index.mdx

Plugins under `.opencode/plugins/` are loaded automatically. The `setup` function runs when the plugin loads and can perform initialization tasks.

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

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

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

### TextNode Range Methods

Source: https://github.com/anomalyco/opencode/blob/dev/packages/plugins/figma/skills/figma-use-figjam/references/edit-text.md

SDK methods on TextNode for getting and setting properties across a specific character range (start to end indices).

```APIDOC
## TextNode Range Methods

### Description
Methods available on `TextNode` instances to apply mixed styling, fonts, fills, hyperlinks, and list options to specific character ranges.

### Methods
- `textNode.setRangeFontName(start, end, fontName)`
- `textNode.setRangeFontSize(start, end, size)`
- `textNode.setRangeFills(start, end, fills)`
- `textNode.setRangeTextDecoration(start, end, decoration)`
- `textNode.setRangeTextCase(start, end, textCase)`
- `textNode.setRangeLetterSpacing(start, end, spacing)`
- `textNode.setRangeLineHeight(start, end, lineHeight)`
- `textNode.setRangeHyperlink(start, end, hyperlink)`
- `textNode.setRangeListOptions(start, end, listOptions)`
- `textNode.setRangeIndentation(start, end, indentation)`
- `textNode.getRangeFontName(start, end)`
- `textNode.getRangeFontSize(start, end)`

### Usage Examples
```javascript
// Make "Hello" bold (characters 0-5)
textNode.setRangeFontName(0, 5, { family: 'Inter', style: 'Bold' });

// Make "World" red (characters 6-11)
textNode.setRangeFills(6, 11, [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]);

// Change size of "World"
textNode.setRangeFontSize(6, 11, 24);

// Get properties for a range
const fontAtStart = textNode.getRangeFontName(0, 1);
const sizeAtEnd = textNode.getRangeFontSize(10, 11);
```
```

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

### Configure Virtual Framebuffer for Headless Environments

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/bs/troubleshooting.mdx

Installs and initializes Xvfb and sets the DISPLAY environment variable to support clipboard functionality in headless Linux setups.

```bash
apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0
```

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

### Start OpenCode CLI Session

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/cli/tui.mdx

Navigate to the target project directory and launch OpenCode.

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

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

### Manage command-based connection attempts

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/index.mdx

Use this to start, check status, or cancel a command-based connection attempt for an integration. The example uses the 'acme' integration with the 'cli' method.

```typescript
const attempt = await ctx.integration.command.connect({ integrationID: "acme", methodID: "cli" })
const status = await ctx.integration.command.status({ integrationID: "acme", attemptID: attempt.data.attemptID })
await ctx.integration.command.cancel({ integrationID: "acme", attemptID: attempt.data.attemptID })
```

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

### Initialize client with createOpencode

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/sdk.mdx

Create an instance of opencode to start both a server and a client.

```javascript
import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()
```

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

### List and get agents using Effect

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/effect.mdx

Use this to read all agents or fetch a specific agent by ID. The example logs the count of agents and the name of the 'build' agent.

```typescript
effect: (ctx) =>
  Effect.gen(function* () {
    const agent = ctx.agent
    const agents = yield* agent.list().pipe(Effect.orDie)
    const build = yield* agent.get({ agentID: Agent.ID.make("build") }).pipe(Effect.orDie)
    yield* Effect.logInfo("agents", { count: agents.data.length, build: build.data.name })
  }),
```

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

### Wildcard pattern matching on resource in opencode.json

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/policies.mdx

Applies a wildcard pattern using * to match zero or more characters in the resource ID. This example denies any provider starting with company-.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "company-*"
      }
    ]
  }
}
```

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

### Configure MCP servers with the mcp option

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/config.mdx

Use the `mcp` option in opencode.json to configure MCP servers. The example shows an empty `mcp` object as a starting point.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}
```

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

### Manage OAuth connection attempts

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/index.mdx

Use this to start, check status, complete, or cancel an OAuth connection attempt for an integration. The example demonstrates the full flow for the GitHub integration.

```typescript
const attempt = await ctx.integration.oauth.connect({ integrationID: "github", methodID: "oauth" })
const status = await ctx.integration.oauth.status({ integrationID: "github", attemptID: attempt.data.attemptID })
await ctx.integration.oauth.complete({ integrationID: "github", attemptID: attempt.data.attemptID, code })
await ctx.integration.oauth.cancel({ integrationID: "github", attemptID: attempt.data.attemptID })
```

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

### Create an OpenCode client and start a session

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/client/index.mdx

Instantiate an OpenCode client with OpenCode.make and invoke resource methods like session.create and session.prompt.

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

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

### List and get providers using Effect

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/effect.mdx

Use this to read all available providers or fetch a specific provider by ID. The example logs the count of providers and the name of the 'anthropic' provider.

```typescript
effect: (ctx) =>
  Effect.gen(function* () {
    const provider = ctx.provider
    const providers = yield* provider.list().pipe(Effect.orDie)
    const anthropic = yield* provider.get({ providerID: Provider.ID.make("anthropic") }).pipe(Effect.orDie)
    yield* Effect.logInfo("providers", {
      providers: providers.data.length,
      anthropic: anthropic.data.name,
    })
  }),
```

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

### List available models and default selection

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/effect.mdx

Use ctx.model.list() to retrieve all available models and ctx.model.default() to get the currently selected model. The example logs the count and selected model name.

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

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

### Add a custom LSP server with command and extensions

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/lsp.mdx

Define a new LSP entry by specifying the startup `command` array and the file `extensions` the server should handle.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    }
  }
}
```

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

### List and inspect integrations and active credentials

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/index.mdx

Use this to retrieve a list of integrations, get details for a specific integration, check the active connection, and resolve the credential for that connection. The example shows how to access the integration context methods.

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

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

### Start OpenCode server for desktop app connection

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/windows-wsl.mdx

Starts the server in WSL listening on 0.0.0.0 at port 4096 to allow external desktop app connections.

```bash
opencode serve --hostname 0.0.0.0 --port 4096
```

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

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

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/effect.mdx

Use ctx.storage to set, get, and remove durable JSON values scoped to the plugin ID. The example sets a settings object, retrieves it, logs it, and removes it.

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

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

### Configure and start opencode server instance

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/sdk.mdx

Pass custom configuration options such as hostname, port, and model settings inline to override defaults or opencode.json.

```javascript
import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

console.log(`Server running at ${opencode.server.url}`)

opencode.server.close()
```

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

### Scan storage keys by prefix with cursor pagination

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/effect.mdx

Use storage.scan with a prefix and limit to retrieve entries. The example scans for keys starting with 'cache/', then uses the next cursor to fetch the next page, and logs the total count.

```ts
effect: (ctx) =>
  Effect.gen(function* () {
    const storage = ctx.storage
    const first = yield* storage.scan({ prefix: "cache/", limit: 100 })
    const second = first.next
      ? yield* storage.scan({ prefix: "cache/", after: first.next, limit: 100 })
      : { entries: [] }
    yield* Effect.logInfo("cache entries", { count: first.entries.length + second.entries.length })
  }),
```

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

### Read VCS repository information and status

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/effect.mdx

Use this to read repository information, working-copy status, branches, and file diffs. The example shows how to access the VCS service from the context and call methods like get, branches, status, and diff.

```typescript
effect: (ctx) =>
  Effect.gen(function* () {
    const vcs = ctx.vcs
    const info = yield* vcs.get().pipe(Effect.orDie)
    const branches = yield* vcs.branches({ search: "feature", limit: 10 }).pipe(Effect.orDie)
    const changes = yield* vcs.status().pipe(Effect.orDie)
    const diff = yield* vcs.diff({ mode: "working", context: 3 }).pipe(Effect.orDie)
    yield* Effect.logInfo("vcs", { branch: info.data.branch.current, files: changes.data.length })
  }),
```

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

### Launch Vite TUI live development session with bun

Source: https://github.com/anomalyco/opencode/blob/dev/packages/cli/dev/README.md

Starts the CLI and its TUI via Vite and solid-refresh from the repository root, connecting directly to the installed server. Component edits trigger hot updates while the backend remains active across syntax error retries and full reloads.

```sh
bun run dev:vite:live /path/to/project
```

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

### Access setup context properties

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/cli.mdx

The setup function receives configuration, app metadata, the current location, the OpenCode client, cached data, theme tokens, the OpenTUI renderer, and UI APIs. Use context.options for plugin options and context.data.location.default() as a fallback location.

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

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

### Plugin lifecycle with cleanup function

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/build/plugins/index.mdx

`setup` runs when the plugin loads. It may return a cleanup function that runs when the plugin unloads.

```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 using the shell script

Source: https://github.com/anomalyco/opencode/blob/dev/packages/web/src/content/docs/index.mdx

Quickly install OpenCode via the official install script. Note that this binary can conflict with or replace an OpenCode 2 installation.

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

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

### Install OpenCode CLI via AUR

Source: https://github.com/anomalyco/opencode/blob/dev/services/www/src/docs/content/index.mdx

Install the OpenCode CLI from the AUR using paru. This installs the opencode-beta package.

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