Usage

OpenCode usage documentation.

Go

Low cost subscription for open coding models.

OpenCode Go is a low cost subscription -- $5 for your first month, then $10/month -- that gives you reliable access to popular open coding models.

Go works like any other provider in OpenCode. You subscribe to OpenCode Go and get your API key. It's completely optional and you don't need to use it to use OpenCode.

It is designed primarily for international users, with models hosted in the US, EU, and Singapore for stable global access.

Background

Open models have gotten really good. They now reach performance close to proprietary models for coding tasks. And because many providers can serve them competitively, they are usually far cheaper.

However, getting reliable, low latency access to them can be difficult. Providers vary in quality and availability.

To fix this, we did a couple of things:

1. We tested a select group of open models and talked to their teams about how to best run them.
2. We then worked with a few providers to make sure these were being served correctly.
3. Finally, we benchmarked the combination of the model/provider and came up with a list that we feel good recommending.

OpenCode Go gives you access to these models for $5 for your first month, then $10/month.

How it works

OpenCode Go works like any other provider in OpenCode.

1. You sign in to OpenCode Zen, subscribe to Go, and copy your API key.
2. You run the /connect command in the TUI, select OpenCode Go, and paste your API key.
3. Run /models in the TUI to see the list of models available through Go.

The current list of models includes:

• GLM-5.2
• GLM-5.1
• Kimi K2.7 Code
• Kimi K2.6
• MiMo-V2.5
• MiMo-V2.5-Pro
• MiniMax M3
• MiniMax M2.7
• Qwen3.7 Max
• Qwen3.7 Plus
• Qwen3.6 Plus
• DeepSeek V4 Pro
• DeepSeek V4 Flash

The list of models may change as we test and add new ones.

Usage limits

OpenCode Go includes the following limits:

• 5 hour limit -- $12 of usage
• Weekly limit -- $30 of usage
• Monthly limit -- $60 of usage

Limits are defined in dollar value. This means your actual request count depends on the model you use. Cheaper models like DeepSeek V4 Flash allow for more requests, while higher-cost models like GLM-5.2 allow for fewer.

Model Request Estimates

The estimates are based on observed average request patterns:

Token Usage Patterns

The estimates are also based on the following prices per 1M tokens:

Pricing (per 1M tokens)

You can track your current usage in the console.

Usage limits may change as we learn from early usage and feedback.

Usage beyond limits

If you also have credits on your Zen balance, you can enable the Use balance option in the console. When enabled, Go will fall back to your Zen balance after you've reached your usage limits instead of blocking requests.

Endpoints

You can also access Go models through the following API endpoints.

The model id in your OpenCode config uses the format opencode-go/<model-id>. For example, for Kimi K2.7 Code, you would use opencode-go/kimi-k2.7-code in your config.

Models

You can fetch the full list of available models and their metadata from:

https://opencode.ai/zen/go/v1/models

Privacy

The plan is designed primarily for international users, with models hosted in the US, EU, and Singapore for stable global access. Our providers follow a zero-retention policy and do not use your data for model training.

Goals

We created OpenCode Go to:

1. Make AI coding accessible to more people with a low cost subscription.
2. Provide reliable access to the best open coding models.
3. Curate models that are tested and benchmarked for coding agent use.
4. Have no lock-in by allowing you to use any other provider with OpenCode as well.

TUI

Using the OpenCode terminal user interface.

OpenCode provides an interactive terminal interface or TUI for working on your projects with an LLM. Running OpenCode starts the TUI for the current directory.

opencode

opencode /path/to/project

File references

You can reference files in your messages using @. This does a fuzzy file search in the current working directory.

Give me a quick summary of the codebase.

How is auth handled in @packages/functions/src/api/index.ts?

Compare our setup with @docs/README.md

The content of the file is added to the conversation automatically. Configured references also appear in @ autocomplete. Type @alias to add the reference root as context, or type @alias/ to autocomplete files inside that reference.

Bash commands

Start a message with ! to run a shell command. The output of the command is added to the conversation as a tool result.

!ls -la

Commands

When using the OpenCode TUI, you can type / followed by a command name to quickly execute actions. For example:

/help

Most commands also have keyboard shortcuts using ctrl+x as the default leader key. Learn more about keybinds.

connect

Add a provider to OpenCode. Allows you to select from available providers and add their API keys.

compact

Compact the current session. Alias: /summarize. Keybind: ctrl+x c

details

Toggle tool execution details.

editor

Open external editor for composing messages. Uses the editor set in your EDITOR environment variable. Keybind: ctrl+x e

exit

Exit OpenCode. Aliases: /quit, /q. Keybind: ctrl+x q

export

Export current conversation to Markdown and open in your default editor. Uses the editor set in your EDITOR environment variable. Keybind: ctrl+x x

help

Show the help dialog.

init

Guided setup for creating or updating AGENTS.md. Learn more about rules.

models

List available models. Keybind: ctrl+x m

new

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

redo

Redo a previously undone message. Only available after using /undo.

Keybind: ctrl+x r

sessions

List and switch between sessions. Aliases: /resume, /continue. Keybind: ctrl+x l

share

Share current session. Learn more about sharing.

themes

List available themes. Keybind: ctrl+x t

thinking

Toggle the visibility of thinking/reasoning blocks in the conversation. When enabled, you can see the model's reasoning process for models that support extended thinking.

undo

Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes.

Keybind: ctrl+x u

unshare

Unshare current session. Learn more about un-sharing.

Editor setup

Both the /editor and /export commands use the editor specified in your EDITOR environment variable.

Linux/macOS

# Example for nano or vim
export EDITOR=nano
export EDITOR=vim
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
export EDITOR="code --wait"

To make it permanent, add this to your shell profile; ~/.bashrc, ~/.zshrc, etc.

Windows (CMD)

set EDITOR=notepad
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
set EDITOR=code --wait

To make it permanent, use System Properties > Environment Variables.

Windows (PowerShell)

$env:EDITOR = "notepad"
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
$env:EDITOR = "code --wait"

To make it permanent, add this to your PowerShell profile.

Popular editors

• code - Visual Studio Code
• cursor - Cursor
• windsurf - Windsurf
• nvim - Neovim editor
• vim - Vim editor
• nano - Nano editor
• notepad - Windows Notepad
• subl - Sublime Text

Configure

You can customize TUI behavior through tui.json (or tui.jsonc). This is separate from opencode.json, which configures server/runtime behavior. keybinds is merged with built-in defaults, so you only need to configure the shortcuts you want to change.

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

Options

• theme - Sets your UI theme. Learn more about themes.
• keybinds - Customizes keyboard shortcuts. Learn more about keybinds.
• leader_timeout - Controls how long OpenCode waits after the leader key. Defaults to 2000.
• scroll_acceleration.enabled - Enable macOS-style scroll acceleration for smooth, natural scrolling. When enabled, scroll speed increases with rapid scrolling gestures and stays precise for slower movements. This setting takes precedence over scroll_speed and overrides it when enabled.
• scroll_speed - Controls how fast the TUI scrolls when using scroll commands (minimum: 0.001, supports decimal values). Defaults to 3. Note: This is ignored if scroll_acceleration.enabled is set to true.
• diff_style - Controls diff rendering. "auto" adapts to terminal width, "stacked" always shows a single-column layout.
• mouse - Enable or disable mouse capture in the TUI (default: true). When disabled, the terminal's native mouse selection/scrolling behavior is preserved.
• attention - Configures TUI desktop notifications and sounds. Disabled by default.

Use OPENCODE_TUI_CONFIG to load a custom TUI config path.

Attention

The TUI can request attention for questions, permissions, session errors, and completed sessions. Enable it with attention.enabled; built-in events play sounds when triggered, and non-subagent events request desktop notifications only when the terminal is blurred.

• enabled - Enable all attention notifications and sounds. Defaults to false.
• notifications - Allow terminal-mediated desktop notifications when attention is enabled. Defaults to true.
• sound - Allow attention sounds when attention is enabled. Defaults to true.
• volume - Default sound volume from 0 to 1. Defaults to 0.4.
• sound_pack - Sound pack ID to use. Defaults to opencode.default.
• sounds - Override sound files for default, question, permission, error, done, or subagent_done. Paths can be absolute, file:// URLs, or relative to tui.json.

Customization

You can customize various aspects of the TUI view using the command palette (ctrl+p). These settings persist across restarts.

Username display

Toggle whether your username appears in chat messages. Access this through: Command palette: Search for "username" or "hide username". The setting persists automatically and will be remembered across TUI sessions.

CLI

OpenCode CLI options and commands.

The OpenCode CLI by default starts the TUI when run without any arguments. But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically.

opencode

opencode run "Explain how closures work in JavaScript"

Commands

The OpenCode CLI also has the following commands.

tui

Start the OpenCode terminal user interface.

opencode [project]

Flags

agent

Manage agents for OpenCode. This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don't allow is denied in the generated agent's frontmatter.

opencode agent [command]

create

opencode agent create

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.

Flags

list

opencode agent list

attach

Attach a terminal to an already running OpenCode backend server started via serve or web commands. This allows using the TUI with a remote OpenCode backend. For example:

opencode attach [url]

# Start the backend server for web/mobile access
opencode web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backend
opencode attach http://10.20.30.40:4096

Flags

auth

Command to manage credentials and login for providers. OpenCode is powered by the provider list at Models.dev, so you can use opencode auth login to configure API keys for any provider you'd like to use. This is stored in ~/.local/share/opencode/auth.json. When OpenCode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.

opencode auth [command]

login

opencode auth login

Flags

list

opencode auth list

opencode auth ls

Lists all the authenticated providers as stored in the credentials file.

logout

opencode auth logout

Logs you out of a provider by clearing it from the credentials file.

github

Manage the GitHub agent for repository automation.

opencode github [command]

install

Install the GitHub agent in your repository. This sets up the necessary GitHub Actions workflow and guides you through the configuration process.

opencode github install

run

Run the GitHub agent. This is typically used in GitHub Actions.

opencode github run

Flags

mcp

Manage Model Context Protocol servers.

opencode mcp [command]

add

Add an MCP server to your configuration. This command will guide you through adding either a local or remote MCP server.

opencode mcp add

list

List all configured MCP servers and their connection status.

opencode mcp list

opencode mcp ls

auth

Authenticate with an OAuth-enabled MCP server. If you don't provide a server name, you'll be prompted to select from available OAuth-capable servers. You can also list OAuth-capable servers and their authentication status.

opencode mcp auth [name]

opencode mcp auth list

opencode mcp auth ls

logout

Remove OAuth credentials for an MCP server.

opencode mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

opencode mcp debug <name>

models

List all available models from configured providers. This command displays all models available across your configured providers in the format provider/model. This is useful for figuring out the exact model name to use in your config. You can optionally pass a provider ID to filter models by that provider. Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in OpenCode.

opencode models [provider]

opencode models anthropic

opencode models --refresh

Flags

run

Run opencode in non-interactive mode by passing a prompt directly. This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example:

opencode run [message..]

opencode run Explain the use of context in Go

You can also attach to a running opencode serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
opencode serve
# In another terminal, run commands that attach to it
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

serve

Start a headless OpenCode server for API access. Check out the server docs for the full HTTP interface. This starts an HTTP server that provides API access to opencode functionality without the TUI interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode).

opencode serve

Flags

session

Manage OpenCode sessions.

opencode session [command]

list

opencode session list

Flags

delete

opencode session delete <sessionID>

stats

Show token usage and cost statistics for your OpenCode sessions.

opencode stats

Flags

export

Export session data as JSON. If you don't provide a session ID, you'll be prompted to select from available sessions.

opencode export [sessionID]

Flags

import

Import session data from a JSON file or OpenCode share URL. You can import from a local file or an OpenCode share URL.

opencode import <file>

opencode import session.json
opencode import https://opncd.ai/s/abc123

web

Start a headless OpenCode server with a web interface. This starts an HTTP server and opens a web browser to access OpenCode through a web interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode).

opencode web

Flags

acp

Start an ACP (Agent Client Protocol) server. This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

opencode acp

Flags

plugin

Install a plugin and update your config. Or use the alias.

opencode plugin <module>

opencode plug <module>

Flags

pr

Fetch and checkout a GitHub PR branch, then run OpenCode.

opencode pr <number>

db

Database tools.

opencode db [query]

path

opencode db path

Flags

debug

Debugging and troubleshooting tools.

opencode debug [command]

uninstall

Uninstall OpenCode and remove all related files.

opencode uninstall

Flags

upgrade

Updates opencode to the latest version or a specific version.

To upgrade to the latest version:

opencode upgrade

To upgrade to a specific version:

opencode upgrade v0.1.48

Flags

Global Flags

The opencode CLI takes the following global flags.

Environment variables

OpenCode can be configured using environment variables.

Experimental

These environment variables enable experimental features that may change or be removed.

Web

Using OpenCode in your browser.

OpenCode can run as a web application in your browser, providing the same powerful AI coding experience without needing a terminal.

Getting Started

Start the web interface by running:

opencode web

This starts a local server on 127.0.0.1 with a random available port and automatically opens OpenCode in your default browser.

Configuration

You can configure the web server using command line flags or in your config file.

Port

By default, OpenCode picks an available port. You can specify a port:

opencode web --port 4096

Hostname

By default, the server binds to 127.0.0.1 (localhost only). To make OpenCode accessible on your network:

opencode web --hostname 0.0.0.0

When using 0.0.0.0, OpenCode will display both local and network addresses.

mDNS Discovery

Enable mDNS to make your server discoverable on the local network:

opencode web --mdns

This automatically sets the hostname to 0.0.0.0 and advertises the server as opencode.local.

You can customize the mDNS domain name to run multiple instances on the same network:

opencode web --mdns --mdns-domain myproject.local

CORS

To allow additional domains for CORS (useful for custom frontends):

opencode web --cors https://example.com

Authentication

To protect access, set a password using the OPENCODE_SERVER_PASSWORD environment variable:

OPENCODE_SERVER_PASSWORD=secret opencode web

The username defaults to opencode but can be changed with OPENCODE_SERVER_USERNAME.

Using the Web Interface

Once started, the web interface provides access to your OpenCode sessions.

Sessions

View and manage your sessions from the homepage. You can see active sessions and start new ones.

Server Status

Click "See Servers" to view connected servers and their status.

Attaching a Terminal

You can attach a terminal TUI to a running web server:

# Start the web server
opencode web --port 4096
# In another terminal, attach the TUI
opencode attach http://localhost:4096

This allows you to use both the web interface and terminal simultaneously, sharing the same sessions and state.

Config File

You can also configure server settings in your opencode.json config file:

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["https://example.com"]
  }
}

Command line flags take precedence over config file settings.

IDE

The OpenCode extension for VS Code, Cursor, and other IDEs.

OpenCode integrates with VS Code, Cursor, or any IDE that supports a terminal. Just run opencode in the terminal to get started.

Usage

• Quick Launch: Use Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux) to open OpenCode in a split terminal view, or focus an existing terminal session if one is already running.
• New Session: Use Cmd+Shift+Esc (Mac) or Ctrl+Shift+Esc (Windows/Linux) to start a new OpenCode terminal session, even if one is already open. You can also click the OpenCode button in the UI.
• Context Awareness: Automatically share your current selection or tab with OpenCode.
• File Reference Shortcuts: Use Cmd+Option+K (Mac) or Alt+Ctrl+K (Linux/Windows) to insert file references. For example, @File#L37-42.

Installation

To install OpenCode on VS Code and popular forks like Cursor, Windsurf, VSCodium:

1. Open VS Code
2. Open the integrated terminal
3. Run opencode - the extension installs automatically.

If on the other hand you want to use your own IDE when you run /editor or /export from the TUI, you'll need to set export EDITOR="code --wait".

Manual Install

Search for OpenCode in the Extension Marketplace and click Install.

Troubleshooting

If the extension fails to install automatically:

• Ensure you're running opencode in the integrated terminal.
• Confirm the CLI for your IDE is installed:
  • For VS Code: code command
  • For Cursor: cursor command
  • For Windsurf: windsurf command
  • For VSCodium: codium command
• If not, run Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and search for 'Shell Command: Install 'code' command in PATH'.
• Ensure VS Code has permission to install extensions.

Zen

A list of tested and verified models provided by the OpenCode team.

OpenCode Zen is a list of tested and verified models provided by the OpenCode team. Zen works like any other provider in OpenCode. You login to OpenCode Zen and get your API key. It's completely optional and you don't need to use it to use OpenCode.

Background

There are a large number of models out there but only a few of these models work well as coding agents. Additionally, most providers are configured very differently; so you get very different performance and quality.

So if you are using a model through something like OpenRouter, you can never be sure if you are getting the best version of the model you want. To fix this, we did a couple of things:

1. We tested a select group of models and talked to their teams about how to best run them.
2. We then worked with a few providers to make sure these were being served correctly.
3. Finally, we benchmarked the combination of the model/provider and came up with a list that we feel good recommending.

OpenCode Zen is an AI gateway that gives you access to these models.

How it works

OpenCode Zen works like any other provider in OpenCode.

1. You sign in to OpenCode Zen, add your billing details, and copy your API key.
2. You run the /connect command in the TUI, select OpenCode Zen, and paste your API key.
3. Run /models in the TUI to see the list of models we recommend.

You are charged per request and you can add credits to your account.

Endpoints

You can also access our models through the following API endpoints.

The model id in your OpenCode config uses the format opencode/<model-id>. For example, for GPT 5.5, you would use opencode/gpt-5.5 in your config.

Models

You can fetch the full list of available models and their metadata from:

https://opencode.ai/zen/v1/models

The endpoints table includes 50+ models across providers including:

• GPT 5.5 through GPT 5 Nano (various tiers)
• Claude models (Fable 5, Opus 4.1-4.8, Sonnet 4-4.6, Haiku variants)
• Gemini models (3.5 Flash, 3.1 Pro, 3 Flash)
• Qwen, DeepSeek, MiniMax, GLM, Kimi, Grok, and others

Endpoints use URLs under:

• https://opencode.ai/zen/v1/chat/completions (for @ai-sdk/openai-compatible)
• https://opencode.ai/zen/v1/messages (for @ai-sdk/anthropic)
• https://opencode.ai/zen/v1/models/gemini-*:streamGenerateContent (for @ai-sdk/google)

Pricing

We support a pay-as-you-go model. Below are the prices per 1M tokens.

You might notice Claude Haiku 3.5 in your usage history. This is a low cost model that's used to generate the titles of your sessions.

The free models:

• DeepSeek V4 Flash Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
• MiMo-V2.5 Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
• North Mini Code Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
• Nemotron 3 Ultra Free is available on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
• Big Pickle is a stealth model that's free on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.

Contact us if you have any questions.

Auto-reload

If your balance goes below $5, Zen will automatically reload $20. You can change the auto-reload amount. You can also disable auto-reload entirely.

Monthly limits

You can also set a monthly usage limit for the entire workspace and for each member of your team. For example, let's say you set a monthly usage limit to $20, Zen will not use more than $20 in a month. But if you have auto-reload enabled, Zen might end up charging you more than $20 if your balance goes below $5.

Deprecated models

A deprecation table lists 14 models with deprecation dates ranging from February 2026 to July 2026.

Privacy

All our models are hosted in the US. Our providers follow a zero-retention policy and do not use your data for model training, with the following exceptions:

• Big Pickle: During its free period, collected data may be used to improve the model.
• DeepSeek V4 Flash Free: During its free period, collected data may be used to improve the model.
• MiMo-V2.5 Free: During its free period, collected data may be used to improve the model.
• North Mini Code Free: During its free period, collected data may be retained and used to improve the model. Do not submit personal or confidential data. See our Terms of Use and Privacy Policy.
• Nemotron 3 Ultra Free (NVIDIA free endpoints): Trial use only -- do not submit personal or confidential data. Your use is logged for security purposes and to improve NVIDIA products and services. The logged session data for improvement purposes is not linked to your identity or any persistent identifier. For more information about our data processing practices, see our Privacy Policy. By interacting with this endpoint, you consent to our collection, recording, and use of such information and the NVIDIA API Trial Terms of Service.
• OpenAI APIs: Requests are retained for 30 days in accordance with OpenAI's Data Policies.
• Anthropic APIs: Requests are retained for 30 days in accordance with Anthropic's Data Policies.

For Teams

Zen also works great for teams. You can invite teammates, assign roles, curate the models your team uses, and more.

Managing your workspace is currently free for teams as a part of the beta. We'll be sharing more details on the pricing soon.

Roles

You can invite teammates to your workspace and assign roles:

• Admin: Manage models, members, API keys, and billing
• Member: Manage only their own API keys

Admins can also set monthly spending limits for each member to keep costs under control.

Model access

Admins can enable or disable specific models for the workspace. Requests made to a disabled model will return an error. This is useful for cases where you want to disable the use of a model that collects data.

Bring your own key

You can use your own OpenAI or Anthropic API keys while still accessing other models in Zen. When you use your own keys, tokens are billed directly by the provider, not by Zen. For example, your organization might already have a key for OpenAI or Anthropic and you want to use that instead of the one that Zen provides.

Goals

We created OpenCode Zen to:

1. Benchmark the best models/providers for coding agents.
2. Have access to the highest quality options and not downgrade performance or route to cheaper providers.
3. Pass along any price drops by selling at cost; so the only markup is to cover our processing fees.
4. Have no lock-in by allowing you to use it with any other coding agent. And always let you use any other provider with OpenCode as well.

Share

Share your OpenCode conversations.

OpenCode's share feature allows you to create public links to your OpenCode conversations, so you can collaborate with teammates or get help from others.

How it works

When you share a conversation, OpenCode:

1. Creates a unique public URL for your session
2. Syncs your conversation history to our servers
3. Makes the conversation accessible via the shareable link -- opncd.ai/s/<share-id>

Sharing

Manual (default)

By default, OpenCode uses manual sharing mode. Sessions are not shared automatically, but you can manually share them using the /share command:

/share

This will generate a unique URL that'll be copied to your clipboard.

To explicitly set manual mode in your config file:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

Auto-share

You can enable automatic sharing for all new conversations by setting the share option to "auto" in your config file:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "auto"
}

With auto-share enabled, every new conversation will automatically be shared and a link will be generated.

Disabled

You can disable sharing entirely by setting the share option to "disabled" in your config file:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled"
}

To enforce this across your team for a given project, add it to the opencode.json in your project and check into Git.

Un-sharing

To stop sharing a conversation and remove it from public access:

/unshare

This will remove the share link and delete the data related to the conversation.

Privacy

There are a few things to keep in mind when sharing a conversation.

Data retention

Shared conversations remain accessible until you explicitly unshare them. This includes:

• Full conversation history
• All messages and responses
• Session metadata

Recommendations

• Only share conversations that don't contain sensitive information.
• Review conversation content before sharing.
• Unshare conversations when collaboration is complete.
• Avoid sharing conversations with proprietary code or confidential data.
• For sensitive projects, disable sharing entirely.

For enterprises

For enterprise deployments, the share feature can be:

• Disabled entirely for security compliance
• Restricted to users authenticated through SSO only
• Self-hosted on your own infrastructure

Learn more about using opencode in your organization at Enterprise.

GitHub

Use OpenCode in GitHub issues and pull-requests.

OpenCode integrates with your GitHub workflow. Mention /opencode or /oc in your comment, and OpenCode will execute tasks within your GitHub Actions runner.

Features

• Triage issues: Ask OpenCode to look into an issue and explain it to you.
• Fix and implement: Ask OpenCode to fix an issue or implement a feature. And it will work in a new branch and submits a PR with all the changes.
• Secure: OpenCode runs inside your GitHub's runners.

Installation

Run the following command in a project that is in a GitHub repo:

opencode github install

This will walk you through installing the GitHub app, creating the workflow, and setting up secrets.

Manual Setup

1. Install the GitHub app

Head over to github.com/apps/opencode-agent. Make sure it's installed on the target repository.

2. Add the workflow

Add the following workflow file to .github/workflows/opencode.yml in your repo. Make sure to set the appropriate model and required API keys in env.

name: opencode
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  opencode:
    if: |
      contains(github.event.comment.body, '/oc') ||
      contains(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false
      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          # share: true
          # github_token: xxxx

3. Store the API keys in secrets

In your organization or project settings, expand Secrets and variables on the left and select Actions. And add the required API keys.

Configuration

Configuration parameters:

• model -- The model to use with OpenCode. Takes the format of provider/model. This is required.
• agent -- The agent to use. Must be a primary agent. Falls back to default_agent from config or build if not found.
• share -- Whether to share the OpenCode session. Defaults to true for public repositories.
• prompt -- Optional custom prompt to override the default behavior. Use this to customize how OpenCode processes requests.
• token -- Optional GitHub access token for performing operations such as creating comments, committing changes, and opening pull requests. By default, OpenCode uses the installation access token from the OpenCode GitHub App, so commits, comments, and pull requests appear as coming from the app. Alternatively, you can use the GitHub Action runner's built-in GITHUB_TOKEN without installing the OpenCode GitHub App. Just make sure to grant the required permissions in your workflow.

Required permissions:

permissions:
  id-token: write
  contents: write
  pull-requests: write
  issues: write

Supported Events

Schedule Example

Run OpenCode on a schedule to perform automated tasks:

name: Scheduled OpenCode Task
on:
  schedule:
    - cron: "0 9 * * 1" # Every Monday at 9am UTC
jobs:
  opencode:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          persist-credentials: false
      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            Review the codebase for any TODO comments and create a summary.
            If you find issues worth addressing, open an issue to track them.

For scheduled events, the prompt input is required since there's no comment to extract instructions from. Scheduled workflows run without a user context to permission-check, so the workflow must grant contents: write and pull-requests: write if you expect OpenCode to create branches or PRs.

Pull Request Example

Automatically review PRs when they are opened or updated:

name: opencode-review
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: read
      issues: read
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
      - uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          use_github_token: true
          prompt: |
            Review this pull request:
            - Check for code quality issues
            - Look for potential bugs
            - Suggest improvements

For pull_request events, if no prompt is provided, OpenCode defaults to reviewing the pull request.

Issues Triage Example

Automatically triage new issues. This example filters to accounts older than 30 days to reduce spam:

name: Issue Triage
on:
  issues:
    types: [opened]
jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: Check account age
        id: check
        uses: actions/github-script@v7
        with:
          script: |
            const user = await github.rest.users.getByUsername({
              username: context.payload.issue.user.login
            });
            const created = new Date(user.data.created_at);
            const days = (Date.now() - created) / (1000 * 60 * 60 * 24);
            return days >= 30;
          result-encoding: string
      - uses: actions/checkout@v6
        if: steps.check.outputs.result == 'true'
        with:
          persist-credentials: false
      - uses: anomalyco/opencode/github@latest
        if: steps.check.outputs.result == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            Review this issue. If there's a clear fix or relevant docs:
            - Provide documentation links
            - Add error handling guidance for code examples
            Otherwise, do not comment.

Custom prompts

Override the default prompt to customize OpenCode's behavior for your workflow.

- uses: anomalyco/opencode/github@latest
  with:
    model: anthropic/claude-sonnet-4-5
    prompt: |
      Review this pull request:
      - Check for code quality issues
      - Look for potential bugs
      - Suggest improvements

This is useful for enforcing specific review criteria, coding standards, or focus areas relevant to your project.

Examples

Explain an issue

Add this comment in a GitHub issue:

/opencode explain this issue

OpenCode will read the entire thread, including all comments, and reply with a clear explanation.

Fix an issue

In a GitHub issue, say:

/opencode fix this

And OpenCode will create a new branch, implement the changes, and open a PR with the changes.

Review PRs and make changes

Leave the following comment on a GitHub PR:

Delete the attachment from S3 when the note is removed /oc

OpenCode will implement the requested change and commit it to the same PR.

Review specific code lines

Leave a comment directly on code lines in the PR's Files tab. OpenCode automatically detects the file, line numbers, and diff context to provide precise responses.

When commenting on specific lines, OpenCode receives:

• The exact file being reviewed
• The specific lines of code
• The surrounding diff context
• Line number information

This allows for more targeted requests without needing to specify file paths or line numbers manually.

GitLab

Use OpenCode in GitLab issues and merge requests.

OpenCode integrates with your GitLab workflow through your GitLab CI/CD pipeline or with GitLab Duo.

In both cases, OpenCode will run on your GitLab runners.

GitLab CI

OpenCode works in a regular GitLab pipeline. You can build it into a pipeline as a CI component.

Here we are using a community-created CI/CD component for OpenCode -- nagyv/gitlab-opencode.

Features

• Use custom configuration per job: Configure OpenCode with a custom configuration directory, for example ./config/#custom-directory to enable or disable functionality per OpenCode invocation.
• Minimal setup: The CI component sets up OpenCode in the background, you only need to create the OpenCode configuration and the initial prompt.
• Flexible: The CI component supports several inputs for customizing its behavior.

Setup

Store your OpenCode authentication JSON as a File type CI environment variables under Settings > CI/CD > Variables. Make sure to mark them as 'Masked and hidden'.

Add the following to your .gitlab-ci.yml file:

include:
  - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@2
    inputs:
      config_dir: ${CI_PROJECT_DIR}/opencode-config
      auth_json: $OPENCODE_AUTH_JSON
      command: optional-custom-command
      message: "Your prompt here"

For more inputs and use cases check out the docs for this component.

GitLab Duo

OpenCode integrates with your GitLab workflow. Mention @opencode in a comment, and OpenCode will execute tasks within your GitLab CI pipeline.

Features

• Triage issues: Ask OpenCode to look into an issue and explain it to you.
• Fix and implement: Ask OpenCode to fix an issue or implement a feature. It will create a new branch and raise a merge request with the changes.
• Secure: OpenCode runs on your GitLab runners.

Setup

OpenCode runs in your GitLab CI/CD pipeline, here's what you'll need to set it up:

1. Configure your GitLab environment
2. Set up CI/CD
3. Get an AI model provider API key
4. Create a service account
5. Configure CI/CD variables
6. Create a flow config file

You can refer to the GitLab CLI agents docs for detailed instructions.

Flow configuration

image: node:22-slim
commands:
  - echo "Installing opencode"
  - npm install --global opencode-ai
  - echo "Installing glab"
  - export GITLAB_TOKEN=$GITLAB_TOKEN_OPENCODE
  - apt-get update --quiet && apt-get install --yes curl wget gpg git && rm --recursive --force /var/lib/apt/lists/*
  - curl --silent --show-error --location "https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository" | bash
  - apt-get install --yes glab
  - echo "Configuring glab"
  - echo $GITLAB_HOST
  - echo "Creating OpenCode auth configuration"
  - mkdir --parents ~/.local/share/opencode
  - |
    cat > ~/.local/share/opencode/auth.json << EOF
    {
      "anthropic": {
        "type": "api",
        "key": "$ANTHROPIC_API_KEY"
      }
    }
    EOF
  - echo "Configuring git"
  - git config --global user.email "opencode@gitlab.com"
  - git config --global user.name "OpenCode"
  - echo "Testing glab"
  - glab issue list
  - echo "Running OpenCode"
  - |
    opencode run "
    You are an AI assistant helping with GitLab operations.
    Context: $AI_FLOW_CONTEXT
    Task: $AI_FLOW_INPUT
    Event: $AI_FLOW_EVENT
    Please execute the requested task using the available GitLab tools.
    Be thorough in your analysis and provide clear explanations.
    <important>
    Please use the glab CLI to access data from GitLab. The glab CLI has already been authenticated. You can run the corresponding commands.
    If you are asked to summarize an MR or issue or asked to provide more information then please post back a note to the MR/Issue so that the user can see it.
    You don't need to commit or push up changes, those will be done automatically based on the file changes you make.
    </important>
    "
  - git checkout --branch $CI_WORKLOAD_REF origin/$CI_WORKLOAD_REF
  - echo "Checking for git changes and pushing if any exist"
  - |
    if ! git diff --quiet || ! git diff --cached --quiet || [ --not --zero "$(git ls-files --others --exclude-standard)" ]; then
      echo "Git changes detected, adding and pushing..."
      git add .
      if git diff --cached --quiet; then
        echo "No staged changes to commit"
      else
        echo "Committing changes to branch: $CI_WORKLOAD_REF"
        git commit --message "Codex changes"
        echo "Pushing changes up to $CI_WORKLOAD_REF"
        git push https://gitlab-ci-token:$GITLAB_TOKEN@$GITLAB_HOST/gl-demo-ultimate-dev-ai-epic-17570/test-java-project.git $CI_WORKLOAD_REF
        echo "Changes successfully pushed"
      fi
    else
      echo "No git changes detected, skipping push"
    fi
variables:
  - ANTHROPIC_API_KEY
  - GITLAB_TOKEN_OPENCODE
  - GITLAB_HOST

Examples

Here are some examples of how you can use OpenCode in GitLab.

Explain an issue

@opencode explain this issue

OpenCode will read the issue and reply with a clear explanation.

Fix an issue

@opencode fix this

OpenCode will create a new branch, implement the changes, and open a merge request with the changes.

Review a merge request

@opencode review this MR

OpenCode will review the merge request and provide feedback.