merge: resolve conflicts from upstream dev
Merge upstream changes while preserving structured output feature: - Keep tools deprecation notice from upstream - Keep bypassAgentCheck parameter from upstream - Keep variant field on user messages from upstream - Preserve outputFormat and StructuredOutput tool injection Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Kyle Mistele
commit
4c7c65a054
598 changed files with 90910 additions and 11698 deletions
|
|
@ -36,7 +36,7 @@ export default defineConfig({
|
|||
expressiveCode: { themes: ["github-light", "github-dark"] },
|
||||
social: [
|
||||
{ icon: "github", label: "GitHub", href: config.github },
|
||||
{ icon: "discord", label: "Dscord", href: config.discord },
|
||||
{ icon: "discord", label: "Discord", href: config.discord },
|
||||
],
|
||||
editLink: {
|
||||
baseUrl: `${config.github}/edit/dev/packages/web/`,
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ export default {
|
|||
console: stage === "production" ? "https://opencode.ai/auth" : `https://${stage}.opencode.ai/auth`,
|
||||
email: "contact@anoma.ly",
|
||||
socialCard: "https://social-cards.sst.dev",
|
||||
github: "https://github.com/sst/opencode",
|
||||
github: "https://github.com/anomalyco/opencode",
|
||||
discord: "https://opencode.ai/discord",
|
||||
headerLinks: [
|
||||
{ name: "Home", url: "/" },
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
{
|
||||
"name": "@opencode-ai/web",
|
||||
"type": "module",
|
||||
"version": "1.0.193",
|
||||
"license": "MIT",
|
||||
"version": "1.1.15",
|
||||
"scripts": {
|
||||
"dev": "astro dev",
|
||||
"dev:remote": "VITE_API_URL=https://api.opencode.ai astro dev",
|
||||
|
|
@ -24,8 +25,8 @@
|
|||
"js-base64": "3.7.7",
|
||||
"lang-map": "0.4.0",
|
||||
"luxon": "catalog:",
|
||||
"marked": "15.0.12",
|
||||
"marked-shiki": "1.2.1",
|
||||
"marked": "catalog:",
|
||||
"marked-shiki": "catalog:",
|
||||
"rehype-autolink-headings": "7.1.0",
|
||||
"remeda": "catalog:",
|
||||
"shiki": "catalog:",
|
||||
|
|
|
|||
|
|
@ -78,6 +78,7 @@ if (image) {
|
|||
<li><b>Multi-session</b>: Start multiple agents in parallel on the same project.</li>
|
||||
<li><b>Shareable links</b>: Share a link to any sessions for reference or to debug.</li>
|
||||
<li><b>Claude Pro</b>: Log in with Anthropic to use your Claude Pro or Max account.</li>
|
||||
<li><b>ChatGPT Plus/Pro</b>: Log in with OpenAI to use your ChatGPT Plus or Pro account.</li>
|
||||
<li><b>Use any model</b>: Supports 75+ LLM providers through <a href="https://models.dev">Models.dev</a>, including local models.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
|
@ -133,9 +134,9 @@ if (image) {
|
|||
</div>
|
||||
<div class="col4">
|
||||
<h3>Mise</h3>
|
||||
<button class="command" data-command="mise use -g github:sst/opencode">
|
||||
<button class="command" data-command="mise use -g github:anomalyco/opencode">
|
||||
<code>
|
||||
<span>mise use -g</span> <span class="highlight">github:sst/opencode</span>
|
||||
<span>mise use -g</span> <span class="highlight">github:anomalyco/opencode</span>
|
||||
</code>
|
||||
<span class="copy">
|
||||
<CopyIcon />
|
||||
|
|
|
|||
|
|
@ -8,6 +8,14 @@ import { transformerNotationDiff } from "@shikijs/transformers"
|
|||
import style from "./content-markdown.module.css"
|
||||
|
||||
const markedWithShiki = marked.use(
|
||||
{
|
||||
renderer: {
|
||||
link({ href, title, text }) {
|
||||
const titleAttr = title ? ` title="${title}"` : ""
|
||||
return `<a href="${href}"${titleAttr} target="_blank" rel="noopener noreferrer">${text}</a>`
|
||||
},
|
||||
},
|
||||
},
|
||||
markedShiki({
|
||||
highlight(code, lang) {
|
||||
return codeToHtml(code, {
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ OpenCode comes with two built-in subagents, **General** and **Explore**. We'll l
|
|||
|
||||
## Built-in
|
||||
|
||||
OpenCode comes with two built-in primary agents and one built-in subagent.
|
||||
OpenCode comes with two built-in primary agents and two built-in subagents.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -426,9 +426,9 @@ mode: subagent
|
|||
permission:
|
||||
edit: deny
|
||||
bash:
|
||||
"*": ask
|
||||
"git diff": allow
|
||||
"git log*": allow
|
||||
"*": ask
|
||||
webfetch: deny
|
||||
---
|
||||
|
||||
|
|
@ -470,7 +470,7 @@ This can take a glob pattern.
|
|||
```
|
||||
|
||||
And you can also use the `*` wildcard to manage permissions for all commands.
|
||||
Where the specific rule can override the `*` wildcard.
|
||||
Since the last matching rule takes precedence, put the `*` wildcard first and specific rules after.
|
||||
|
||||
```json title="opencode.json" {8}
|
||||
{
|
||||
|
|
@ -479,8 +479,8 @@ Where the specific rule can override the `*` wildcard.
|
|||
"build": {
|
||||
"permission": {
|
||||
"bash": {
|
||||
"git status": "allow",
|
||||
"*": "ask"
|
||||
"*": "ask",
|
||||
"git status": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -510,6 +510,62 @@ The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is
|
|||
|
||||
---
|
||||
|
||||
### Hidden
|
||||
|
||||
Hide a subagent from the `@` autocomplete menu with `hidden: true`. Useful for internal subagents that should only be invoked programmatically by other agents via the Task tool.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"internal-helper": {
|
||||
"mode": "subagent",
|
||||
"hidden": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This only affects user visibility in the autocomplete menu. Hidden agents can still be invoked by the model via the Task tool if permissions allow.
|
||||
|
||||
:::note
|
||||
Only applies to `mode: subagent` agents.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### Task permissions
|
||||
|
||||
Control which subagents an agent can invoke via the Task tool with `permission.task`. Uses glob patterns for flexible matching.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"agent": {
|
||||
"orchestrator": {
|
||||
"mode": "primary",
|
||||
"permission": {
|
||||
"task": {
|
||||
"*": "deny",
|
||||
"orchestrator-*": "allow",
|
||||
"code-reviewer": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When set to `deny`, the subagent is removed from the Task tool description entirely, so the model won't attempt to invoke it.
|
||||
|
||||
:::tip
|
||||
Rules are evaluated in order, and the **last matching rule wins**. In the example above, `orchestrator-planner` matches both `*` (deny) and `orchestrator-*` (allow), but since `orchestrator-*` comes after `*`, the result is `allow`.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
Users can always invoke any subagent directly via the `@` autocomplete menu, even if the agent's task permissions would deny it.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### Additional
|
||||
|
||||
Any other options you specify in your agent configuration will be **passed through directly** to the provider as model options. This allows you to use provider-specific features and parameters.
|
||||
|
|
@ -572,7 +628,7 @@ Here are some common use cases for different agents.
|
|||
Here are some examples agents you might find useful.
|
||||
|
||||
:::tip
|
||||
Do you have an agent you'd like to share? [Submit a PR](https://github.com/sst/opencode).
|
||||
Do you have an agent you'd like to share? [Submit a PR](https://github.com/anomalyco/opencode).
|
||||
:::
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ opencode [project]
|
|||
| ------------ | ----- | ------------------------------------------ |
|
||||
| `--continue` | `-c` | Continue the last session |
|
||||
| `--session` | `-s` | Session ID to continue |
|
||||
| `--prompt` | `-p` | Prompt to use |
|
||||
| `--prompt` | | Prompt to use |
|
||||
| `--model` | `-m` | Model to use in the form of provider/model |
|
||||
| `--agent` | | Agent to use |
|
||||
| `--port` | | Port to listen on |
|
||||
|
|
@ -57,6 +57,33 @@ opencode agent [command]
|
|||
|
||||
---
|
||||
|
||||
### attach
|
||||
|
||||
Attach a terminal to an already running OpenCode backend server started via `serve` or `web` commands.
|
||||
|
||||
```bash
|
||||
opencode attach [url]
|
||||
```
|
||||
|
||||
This allows using the TUI with a remote OpenCode backend. For example:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
| Flag | Short | Description |
|
||||
| ----------- | ----- | --------------------------------- |
|
||||
| `--dir` | | Working directory to start TUI in |
|
||||
| `--session` | `-s` | Session ID to continue |
|
||||
|
||||
---
|
||||
|
||||
#### create
|
||||
|
||||
Create a new agent with custom configuration.
|
||||
|
|
@ -69,6 +96,16 @@ This command will guide you through creating a new agent with a custom system pr
|
|||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
List all available agents.
|
||||
|
||||
```bash
|
||||
opencode agent list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### auth
|
||||
|
||||
Command to manage credentials and login for providers.
|
||||
|
|
@ -156,6 +193,88 @@ opencode github run
|
|||
|
||||
---
|
||||
|
||||
### mcp
|
||||
|
||||
Manage Model Context Protocol servers.
|
||||
|
||||
```bash
|
||||
opencode mcp [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### add
|
||||
|
||||
Add an MCP server to your configuration.
|
||||
|
||||
```bash
|
||||
opencode mcp add
|
||||
```
|
||||
|
||||
This command will guide you through adding either a local or remote MCP server.
|
||||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
List all configured MCP servers and their connection status.
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
Or use the short version.
|
||||
|
||||
```bash
|
||||
opencode mcp ls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### auth
|
||||
|
||||
Authenticate with an OAuth-enabled MCP server.
|
||||
|
||||
```bash
|
||||
opencode mcp auth [name]
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
opencode mcp auth list
|
||||
```
|
||||
|
||||
Or use the short version.
|
||||
|
||||
```bash
|
||||
opencode mcp auth ls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### logout
|
||||
|
||||
Remove OAuth credentials for an MCP server.
|
||||
|
||||
```bash
|
||||
opencode mcp logout [name]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### debug
|
||||
|
||||
Debug OAuth connection issues for an MCP server.
|
||||
|
||||
```bash
|
||||
opencode mcp debug <name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### models
|
||||
|
||||
List all available models from configured providers.
|
||||
|
|
@ -233,20 +352,157 @@ opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
|
|||
|
||||
### serve
|
||||
|
||||
Start a headless opencode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
|
||||
Start a headless OpenCode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
|
||||
|
||||
```bash
|
||||
opencode serve
|
||||
```
|
||||
|
||||
This starts an HTTP server that provides API access to opencode functionality without the TUI 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`).
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Short | Description |
|
||||
| ------------ | ----- | --------------------- |
|
||||
| `--port` | `-p` | Port to listen on |
|
||||
| `--hostname` | | Hostname to listen on |
|
||||
| Flag | Description |
|
||||
| ------------ | ------------------------------------------ |
|
||||
| `--port` | Port to listen on |
|
||||
| `--hostname` | Hostname to listen on |
|
||||
| `--mdns` | Enable mDNS discovery |
|
||||
| `--cors` | Additional browser origin(s) to allow CORS |
|
||||
|
||||
---
|
||||
|
||||
### session
|
||||
|
||||
Manage OpenCode sessions.
|
||||
|
||||
```bash
|
||||
opencode session [command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### list
|
||||
|
||||
List all OpenCode sessions.
|
||||
|
||||
```bash
|
||||
opencode session list
|
||||
```
|
||||
|
||||
##### Flags
|
||||
|
||||
| Flag | Short | Description |
|
||||
| ------------- | ----- | ------------------------------------ |
|
||||
| `--max-count` | `-n` | Limit to N most recent sessions |
|
||||
| `--format` | | Output format: table or json (table) |
|
||||
|
||||
---
|
||||
|
||||
### stats
|
||||
|
||||
Show token usage and cost statistics for your OpenCode sessions.
|
||||
|
||||
```bash
|
||||
opencode stats
|
||||
```
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Description |
|
||||
| ----------- | --------------------------------------------------------------------------- |
|
||||
| `--days` | Show stats for the last N days (all time) |
|
||||
| `--tools` | Number of tools to show (all) |
|
||||
| `--models` | Show model usage breakdown (hidden by default). Pass a number to show top N |
|
||||
| `--project` | Filter by project (all projects, empty string: current project) |
|
||||
|
||||
---
|
||||
|
||||
### export
|
||||
|
||||
Export session data as JSON.
|
||||
|
||||
```bash
|
||||
opencode export [sessionID]
|
||||
```
|
||||
|
||||
If you don't provide a session ID, you'll be prompted to select from available sessions.
|
||||
|
||||
---
|
||||
|
||||
### import
|
||||
|
||||
Import session data from a JSON file or OpenCode share URL.
|
||||
|
||||
```bash
|
||||
opencode import <file>
|
||||
```
|
||||
|
||||
You can import from a local file or an OpenCode share URL.
|
||||
|
||||
```bash
|
||||
opencode import session.json
|
||||
opencode import https://opncd.ai/s/abc123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### web
|
||||
|
||||
Start a headless OpenCode server with a web interface.
|
||||
|
||||
```bash
|
||||
opencode web
|
||||
```
|
||||
|
||||
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`).
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Description |
|
||||
| ------------ | ------------------------------------------ |
|
||||
| `--port` | Port to listen on |
|
||||
| `--hostname` | Hostname to listen on |
|
||||
| `--mdns` | Enable mDNS discovery |
|
||||
| `--cors` | Additional browser origin(s) to allow CORS |
|
||||
|
||||
---
|
||||
|
||||
### acp
|
||||
|
||||
Start an ACP (Agent Client Protocol) server.
|
||||
|
||||
```bash
|
||||
opencode acp
|
||||
```
|
||||
|
||||
This command starts an ACP server that communicates via stdin/stdout using nd-JSON.
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Description |
|
||||
| ------------ | --------------------- |
|
||||
| `--cwd` | Working directory |
|
||||
| `--port` | Port to listen on |
|
||||
| `--hostname` | Hostname to listen on |
|
||||
|
||||
---
|
||||
|
||||
### uninstall
|
||||
|
||||
Uninstall OpenCode and remove all related files.
|
||||
|
||||
```bash
|
||||
opencode uninstall
|
||||
```
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Short | Description |
|
||||
| --------------- | ----- | ------------------------------------------- |
|
||||
| `--keep-config` | `-c` | Keep configuration files |
|
||||
| `--keep-data` | `-d` | Keep session data and snapshots |
|
||||
| `--dry-run` | | Show what would be removed without removing |
|
||||
| `--force` | `-f` | Skip confirmation prompts |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -295,23 +551,28 @@ The opencode CLI takes the following global flags.
|
|||
|
||||
OpenCode can be configured using environment variables.
|
||||
|
||||
| Variable | Type | Description |
|
||||
| ------------------------------------- | ------- | ---------------------------------------- |
|
||||
| `OPENCODE_AUTO_SHARE` | boolean | Automatically share sessions |
|
||||
| `OPENCODE_GIT_BASH_PATH` | string | Path to Git Bash executable on Windows |
|
||||
| `OPENCODE_CONFIG` | string | Path to config file |
|
||||
| `OPENCODE_CONFIG_DIR` | string | Path to config directory |
|
||||
| `OPENCODE_CONFIG_CONTENT` | string | Inline json config content |
|
||||
| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | Disable automatic update checks |
|
||||
| `OPENCODE_DISABLE_PRUNE` | boolean | Disable pruning of old data |
|
||||
| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | Disable automatic terminal title updates |
|
||||
| `OPENCODE_PERMISSION` | string | Inlined json permissions config |
|
||||
| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | Disable default plugins |
|
||||
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | Disable automatic LSP server downloads |
|
||||
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | Enable experimental models |
|
||||
| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | Disable automatic context compaction |
|
||||
| `OPENCODE_CLIENT` | string | Client identifier (defaults to `cli`) |
|
||||
| `OPENCODE_ENABLE_EXA` | boolean | Enable Exa web search tools |
|
||||
| Variable | Type | Description |
|
||||
| ------------------------------------- | ------- | ------------------------------------------------- |
|
||||
| `OPENCODE_AUTO_SHARE` | boolean | Automatically share sessions |
|
||||
| `OPENCODE_GIT_BASH_PATH` | string | Path to Git Bash executable on Windows |
|
||||
| `OPENCODE_CONFIG` | string | Path to config file |
|
||||
| `OPENCODE_CONFIG_DIR` | string | Path to config directory |
|
||||
| `OPENCODE_CONFIG_CONTENT` | string | Inline json config content |
|
||||
| `OPENCODE_DISABLE_AUTOUPDATE` | boolean | Disable automatic update checks |
|
||||
| `OPENCODE_DISABLE_PRUNE` | boolean | Disable pruning of old data |
|
||||
| `OPENCODE_DISABLE_TERMINAL_TITLE` | boolean | Disable automatic terminal title updates |
|
||||
| `OPENCODE_PERMISSION` | string | Inlined json permissions config |
|
||||
| `OPENCODE_DISABLE_DEFAULT_PLUGINS` | boolean | Disable default plugins |
|
||||
| `OPENCODE_DISABLE_LSP_DOWNLOAD` | boolean | Disable automatic LSP server downloads |
|
||||
| `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | Enable experimental models |
|
||||
| `OPENCODE_DISABLE_AUTOCOMPACT` | boolean | Disable automatic context compaction |
|
||||
| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | Disable reading from `.claude` (prompt + skills) |
|
||||
| `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | Disable reading `~/.claude/CLAUDE.md` |
|
||||
| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | Disable loading `.claude/skills` |
|
||||
| `OPENCODE_CLIENT` | string | Client identifier (defaults to `cli`) |
|
||||
| `OPENCODE_ENABLE_EXA` | boolean | Enable Exa web search tools |
|
||||
| `OPENCODE_SERVER_PASSWORD` | string | Enable basic auth for `serve`/`web` |
|
||||
| `OPENCODE_SERVER_USERNAME` | string | Override basic auth username (default `opencode`) |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -277,7 +277,7 @@ This is an **optional** config option. If not specified, defaults to your curren
|
|||
### Subtask
|
||||
|
||||
Use the `subtask` boolean to force the command to trigger a [subagent](/docs/agents/#subagents) invocation.
|
||||
This useful if you want the command to not pollute your primary context and will **force** the agent to act as a subagent,
|
||||
This is useful if you want the command to not pollute your primary context and will **force** the agent to act as a subagent,
|
||||
even if `mode` is set to `primary` on the [agent](/docs/agents) configuration.
|
||||
|
||||
```json title="opencode.json"
|
||||
|
|
|
|||
|
|
@ -28,23 +28,78 @@ OpenCode supports both **JSON** and **JSONC** (JSON with Comments) formats.
|
|||
You can place your config in a couple of different locations and they have a
|
||||
different order of precedence.
|
||||
|
||||
:::note[Config Merging]
|
||||
Configuration files are **merged together**, not replaced. Settings from all config locations are combined using a deep merge strategy, where later configs override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.
|
||||
:::note
|
||||
Configuration files are **merged together**, not replaced.
|
||||
:::
|
||||
|
||||
Configuration files are merged together, not replaced. Settings from the following config locations are combined. Later configs override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.
|
||||
|
||||
For example, if your global config sets `theme: "opencode"` and `autoupdate: true`, and your project config sets `model: "anthropic/claude-sonnet-4-5"`, the final configuration will include all three settings.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### Precedence order
|
||||
|
||||
Config sources are loaded in this order (later sources override earlier ones):
|
||||
|
||||
1. **Remote config** (from `.well-known/opencode`) - organizational defaults
|
||||
2. **Global config** (`~/.config/opencode/opencode.json`) - user preferences
|
||||
3. **Custom config** (`OPENCODE_CONFIG` env var) - custom overrides
|
||||
4. **Project config** (`opencode.json` in project) - project-specific settings
|
||||
5. **`.opencode` directories** - agents, commands, plugins
|
||||
6. **Inline config** (`OPENCODE_CONFIG_CONTENT` env var) - runtime overrides
|
||||
|
||||
This means project configs can override global defaults, and global configs can override remote organizational defaults.
|
||||
|
||||
---
|
||||
|
||||
### Remote
|
||||
|
||||
Organizations can provide default configuration via the `.well-known/opencode` endpoint. This is fetched automatically when you authenticate with a provider that supports it.
|
||||
|
||||
Remote config is loaded first, serving as the base layer. All other config sources (global, project) can override these defaults.
|
||||
|
||||
For example, if your organization provides MCP servers that are disabled by default:
|
||||
|
||||
```json title="Remote config from .well-known/opencode"
|
||||
{
|
||||
"mcp": {
|
||||
"jira": {
|
||||
"type": "remote",
|
||||
"url": "https://jira.example.com/mcp",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can enable specific servers in your local config:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"mcp": {
|
||||
"jira": {
|
||||
"type": "remote",
|
||||
"url": "https://jira.example.com/mcp",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Global
|
||||
|
||||
Place your global OpenCode config in `~/.config/opencode/opencode.json`. You'll want to use the global config for things like themes, providers, or keybinds.
|
||||
Place your global OpenCode config in `~/.config/opencode/opencode.json`. Use global config for user-wide preferences like themes, providers, or keybinds.
|
||||
|
||||
Global config overrides remote organizational defaults.
|
||||
|
||||
---
|
||||
|
||||
### Per project
|
||||
|
||||
You can also add a `opencode.json` in your project. Settings from this config are merged with and can override the global config. This is useful for configuring providers or modes specific to your project.
|
||||
Add `opencode.json` in your project root. Project config has the highest precedence among standard config files - it overrides both global and remote configs.
|
||||
|
||||
:::tip
|
||||
Place project specific config in the root of your project.
|
||||
|
|
@ -58,18 +113,20 @@ This is also safe to be checked into Git and uses the same schema as the global
|
|||
|
||||
### Custom path
|
||||
|
||||
You can also specify a custom config file path using the `OPENCODE_CONFIG` environment variable. Settings from this config are merged with and can override the global and project configs.
|
||||
Specify a custom config file path using the `OPENCODE_CONFIG` environment variable.
|
||||
|
||||
```bash
|
||||
export OPENCODE_CONFIG=/path/to/my/custom-config.json
|
||||
opencode run "Hello world"
|
||||
```
|
||||
|
||||
Custom config is loaded between global and project configs in the precedence order.
|
||||
|
||||
---
|
||||
|
||||
### Custom directory
|
||||
|
||||
You can specify a custom config directory using the `OPENCODE_CONFIG_DIR`
|
||||
Specify a custom config directory using the `OPENCODE_CONFIG_DIR`
|
||||
environment variable. This directory will be searched for agents, commands,
|
||||
modes, and plugins just like the standard `.opencode` directory, and should
|
||||
follow the same structure.
|
||||
|
|
@ -79,7 +136,7 @@ export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
|
|||
opencode run "Hello world"
|
||||
```
|
||||
|
||||
Note: The custom directory is loaded after the global config and `.opencode` directories, so it can override their settings.
|
||||
The custom directory is loaded after the global config and `.opencode` directories, so it **can override** their settings.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -102,7 +159,8 @@ You can configure TUI-specific settings through the `tui` option.
|
|||
"scroll_speed": 3,
|
||||
"scroll_acceleration": {
|
||||
"enabled": true
|
||||
}
|
||||
},
|
||||
"diff_style": "auto"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -110,12 +168,40 @@ You can configure TUI-specific settings through the `tui` option.
|
|||
Available options:
|
||||
|
||||
- `scroll_acceleration.enabled` - Enable macOS-style scroll acceleration. **Takes precedence over `scroll_speed`.**
|
||||
- `scroll_speed` - Custom scroll speed multiplier (default: `1`, minimum: `1`). Ignored if `scroll_acceleration.enabled` is `true`.
|
||||
- `scroll_speed` - Custom scroll speed multiplier (default: `3`, minimum: `1`). Ignored if `scroll_acceleration.enabled` is `true`.
|
||||
- `diff_style` - Control diff rendering. `"auto"` adapts to terminal width, `"stacked"` always shows single column.
|
||||
|
||||
[Learn more about using the TUI here](/docs/tui).
|
||||
|
||||
---
|
||||
|
||||
### Server
|
||||
|
||||
You can configure server settings for the `opencode serve` and `opencode web` commands through the `server` option.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"server": {
|
||||
"port": 4096,
|
||||
"hostname": "0.0.0.0",
|
||||
"mdns": true,
|
||||
"cors": ["http://localhost:5173"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Available options:
|
||||
|
||||
- `port` - Port to listen on.
|
||||
- `hostname` - Hostname to listen on. When `mdns` is enabled and no hostname is set, defaults to `0.0.0.0`.
|
||||
- `mdns` - Enable mDNS service discovery. This allows other devices on the network to discover your OpenCode server.
|
||||
- `cors` - Additional origins to allow for CORS when using the HTTP server from a browser-based client. Values must be full origins (scheme + host + optional port), eg `https://app.example.com`.
|
||||
|
||||
[Learn more about the server here](/docs/server).
|
||||
|
||||
---
|
||||
|
||||
### Tools
|
||||
|
||||
You can manage the tools an LLM can use through the `tools` option.
|
||||
|
|
@ -149,10 +235,64 @@ You can configure the providers and models you want to use in your OpenCode conf
|
|||
|
||||
The `small_model` option configures a separate model for lightweight tasks like title generation. By default, OpenCode tries to use a cheaper model if one is available from your provider, otherwise it falls back to your main model.
|
||||
|
||||
Provider options can include `timeout` and `setCacheKey`:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"anthropic": {
|
||||
"options": {
|
||||
"timeout": 600000,
|
||||
"setCacheKey": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `timeout` - Request timeout in milliseconds (default: 300000). Set to `false` to disable.
|
||||
- `setCacheKey` - Ensure a cache key is always set for designated provider.
|
||||
|
||||
You can also configure [local models](/docs/models#local). [Learn more](/docs/models).
|
||||
|
||||
---
|
||||
|
||||
#### Provider-Specific Options
|
||||
|
||||
Some providers support additional configuration options beyond the generic `timeout` and `apiKey` settings.
|
||||
|
||||
##### Amazon Bedrock
|
||||
|
||||
Amazon Bedrock supports AWS-specific configuration:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"amazon-bedrock": {
|
||||
"options": {
|
||||
"region": "us-east-1",
|
||||
"profile": "my-aws-profile",
|
||||
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `region` - AWS region for Bedrock (defaults to `AWS_REGION` env var or `us-east-1`)
|
||||
- `profile` - AWS named profile from `~/.aws/credentials` (defaults to `AWS_PROFILE` env var)
|
||||
- `endpoint` - Custom endpoint URL for VPC endpoints. This is an alias for the generic `baseURL` option using AWS-specific terminology. If both are specified, `endpoint` takes precedence.
|
||||
|
||||
:::note
|
||||
Bearer tokens (`AWS_BEARER_TOKEN_BEDROCK` or `/connect`) take precedence over profile-based authentication. See [authentication precedence](/docs/providers#authentication-precedence) for details.
|
||||
:::
|
||||
|
||||
[Learn more about Amazon Bedrock configuration](/docs/providers#amazon-bedrock).
|
||||
|
||||
---
|
||||
|
||||
### Themes
|
||||
|
||||
You can configure the theme you want to use in your OpenCode config through the `theme` option.
|
||||
|
|
@ -334,6 +474,42 @@ For example, to ensure that the `edit` and `bash` tools require user approval:
|
|||
|
||||
---
|
||||
|
||||
### Compaction
|
||||
|
||||
You can control context compaction behavior through the `compaction` option.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"compaction": {
|
||||
"auto": true,
|
||||
"prune": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `auto` - Automatically compact the session when context is full (default: `true`).
|
||||
- `prune` - Remove old tool outputs to save tokens (default: `true`).
|
||||
|
||||
---
|
||||
|
||||
### Watcher
|
||||
|
||||
You can configure file watcher ignore patterns through the `watcher` option.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"watcher": {
|
||||
"ignore": ["node_modules/**", "dist/**", ".git/**"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Patterns follow glob syntax. Use this to exclude noisy directories from file watching.
|
||||
|
||||
---
|
||||
|
||||
### MCP servers
|
||||
|
||||
You can configure MCP servers you want to use through the `mcp` option.
|
||||
|
|
@ -349,6 +525,23 @@ You can configure MCP servers you want to use through the `mcp` option.
|
|||
|
||||
---
|
||||
|
||||
### Plugins
|
||||
|
||||
[Plugins](/docs/plugins) extend OpenCode with custom tools, hooks, and integrations.
|
||||
|
||||
Place plugin files in `.opencode/plugin/` or `~/.config/opencode/plugin/`. You can also load plugins from npm through the `plugin` option.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
|
||||
}
|
||||
```
|
||||
|
||||
[Learn more here](/docs/plugins).
|
||||
|
||||
---
|
||||
|
||||
### Instructions
|
||||
|
||||
You can configure the instructions for the model you're using through the `instructions` option.
|
||||
|
|
@ -376,6 +569,10 @@ You can disable providers that are loaded automatically through the `disabled_pr
|
|||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The `disabled_providers` takes priority over `enabled_providers`.
|
||||
:::
|
||||
|
||||
The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
|
||||
|
||||
- It won't be loaded even if environment variables are set.
|
||||
|
|
@ -398,7 +595,26 @@ You can specify an allowlist of providers through the `enabled_providers` option
|
|||
This is useful when you want to restrict OpenCode to only use specific providers rather than disabling them one by one.
|
||||
|
||||
:::note
|
||||
The `disabled_providers` takes priority over `enabled_providers`.
|
||||
:::
|
||||
|
||||
If a provider appears in both `enabled_providers` and `disabled_providers`, the `disabled_providers` takes priority for backwards compatibility.
|
||||
|
||||
---
|
||||
|
||||
### Experimental
|
||||
|
||||
The `experimental` key contains options that are under active development.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"experimental": {}
|
||||
}
|
||||
```
|
||||
|
||||
:::caution
|
||||
Experimental options are not stable. They may change or be removed without notice.
|
||||
:::
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -15,24 +15,33 @@ You can also check out [awesome-opencode](https://github.com/awesome-opencode/aw
|
|||
|
||||
## Plugins
|
||||
|
||||
| Name | Description |
|
||||
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) | Automatically inject Helicone session headers for request grouping |
|
||||
| [opencode-skills](https://github.com/malhashemi/opencode-skills) | Manage and organize OpenCode skills and capabilities |
|
||||
| [opencode-type-inject](https://github.com/nick-vi/opencode-type-inject) | Auto-inject TypeScript/Svelte types into file reads with lookup tools |
|
||||
| [opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) | Use your ChatGPT Plus/Pro subscription instead of API credits |
|
||||
| [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) | Use your existing Gemini plan instead of API billing |
|
||||
| [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) | Use Antigravity's free models instead of API billing |
|
||||
| [opencode-google-antigravity-auth](https://github.com/shekohex/opencode-google-antigravity-auth) | Google Antigravity OAuth Plugin, with support for Google Search, and more robust API handling |
|
||||
| [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) | Optimize token usage by pruning obsolete tool outputs |
|
||||
| [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited.git) | Add native websearch support for supported providers with Google grounded style |
|
||||
| [opencode-pty](https://github.com/shekohex/opencode-pty.git) | Enables AI agents to run background processes in a PTY, send interactive input to them. |
|
||||
| [opencode-shell-strategy](https://github.com/JRedeker/opencode-shell-strategy) | Instructions for non-interactive shell commands - prevents hangs from TTY-dependent operations |
|
||||
| [opencode-wakatime](https://github.com/angristan/opencode-wakatime) | Track OpenCode usage with Wakatime |
|
||||
| [opencode-md-table-formatter](https://github.com/franlol/opencode-md-table-formatter/tree/main) | Clean up markdown tables produced by LLMs |
|
||||
| [opencode-morph-fast-apply](https://github.com/JRedeker/opencode-morph-fast-apply) | 10x faster code editing with Morph Fast Apply API and lazy edit markers |
|
||||
| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | Background agents, pre-built LSP/AST/MCP tools, curated agents, Claude Code compatible |
|
||||
| [opencode-zellij-namer](https://github.com/24601/opencode-zellij-namer) | AI-powered automatic Zellij session naming based on OpenCode context |
|
||||
| Name | Description |
|
||||
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) | Automatically inject Helicone session headers for request grouping |
|
||||
| [opencode-type-inject](https://github.com/nick-vi/opencode-type-inject) | Auto-inject TypeScript/Svelte types into file reads with lookup tools |
|
||||
| [opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth) | Use your ChatGPT Plus/Pro subscription instead of API credits |
|
||||
| [opencode-gemini-auth](https://github.com/jenslys/opencode-gemini-auth) | Use your existing Gemini plan instead of API billing |
|
||||
| [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) | Use Antigravity's free models instead of API billing |
|
||||
| [opencode-devcontainers](https://github.com/athal7/opencode-devcontainers) | Multi-branch devcontainer isolation with shallow clones and auto-assigned ports |
|
||||
| [opencode-google-antigravity-auth](https://github.com/shekohex/opencode-google-antigravity-auth) | Google Antigravity OAuth Plugin, with support for Google Search, and more robust API handling |
|
||||
| [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) | Optimize token usage by pruning obsolete tool outputs |
|
||||
| [opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited.git) | Add native websearch support for supported providers with Google grounded style |
|
||||
| [opencode-pty](https://github.com/shekohex/opencode-pty.git) | Enables AI agents to run background processes in a PTY, send interactive input to them. |
|
||||
| [opencode-shell-strategy](https://github.com/JRedeker/opencode-shell-strategy) | Instructions for non-interactive shell commands - prevents hangs from TTY-dependent operations |
|
||||
| [opencode-wakatime](https://github.com/angristan/opencode-wakatime) | Track OpenCode usage with Wakatime |
|
||||
| [opencode-md-table-formatter](https://github.com/franlol/opencode-md-table-formatter/tree/main) | Clean up markdown tables produced by LLMs |
|
||||
| [opencode-morph-fast-apply](https://github.com/JRedeker/opencode-morph-fast-apply) | 10x faster code editing with Morph Fast Apply API and lazy edit markers |
|
||||
| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | Background agents, pre-built LSP/AST/MCP tools, curated agents, Claude Code compatible |
|
||||
| [opencode-notificator](https://github.com/panta82/opencode-notificator) | Desktop notifications and sound alerts for OpenCode sessions |
|
||||
| [opencode-notifier](https://github.com/mohak34/opencode-notifier) | Desktop notifications and sound alerts for permission, completion, and error events |
|
||||
| [opencode-zellij-namer](https://github.com/24601/opencode-zellij-namer) | AI-powered automatic Zellij session naming based on OpenCode context |
|
||||
| [opencode-skillful](https://github.com/zenobi-us/opencode-skillful) | Allow OpenCode agents to lazy load prompts on demand with skill discovery and injection |
|
||||
| [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory) | Persistent memory across sessions using Supermemory |
|
||||
| [@plannotator/opencode](https://github.com/backnotprop/plannotator/tree/main/apps/opencode-plugin) | Interactive plan review with visual annotation and private/offline sharing |
|
||||
| [@openspoon/subtask2](https://github.com/spoons-and-mirrors/subtask2) | Extend opencode /commands into a powerful orchestration system with granular flow control |
|
||||
| [opencode-scheduler](https://github.com/different-ai/opencode-scheduler) | Schedule recurring jobs using launchd (Mac) or systemd (Linux) with cron syntax |
|
||||
| [micode](https://github.com/vtemian/micode) | Structured Brainstorm → Plan → Implement workflow with session continuity |
|
||||
| [octto](https://github.com/vtemian/octto) | Interactive browser UI for AI brainstorming with multi-question forms |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -47,6 +56,7 @@ You can also check out [awesome-opencode](https://github.com/awesome-opencode/aw
|
|||
| [opencode.nvim](https://github.com/sudo-tee/opencode.nvim) | Neovim frontend for opencode - a terminal-based AI coding agent |
|
||||
| [ai-sdk-provider-opencode-sdk](https://github.com/ben-vargas/ai-sdk-provider-opencode-sdk) | Vercel AI SDK provider for using OpenCode via @opencode-ai/sdk |
|
||||
| [OpenChamber](https://github.com/btriapitsyn/openchamber) | Web / Desktop App and VS Code Extension for OpenCode |
|
||||
| [OpenCode-Obsidian](https://github.com/mtymek/opencode-obsidian) | Obsidian plugin that embedds OpenCode in Obsidian's UI |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -11,26 +11,30 @@ OpenCode automatically formats files after they are written or edited using lang
|
|||
|
||||
OpenCode comes with several built-in formatters for popular languages and frameworks. Below is a list of the formatters, supported file extensions, and commands or config options it needs.
|
||||
|
||||
| Formatter | Extensions | Requirements |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| gofmt | .go | `gofmt` command available |
|
||||
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` command available |
|
||||
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://prettier.io/docs/en/index.html) | `prettier` dependency in `package.json` |
|
||||
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://biomejs.dev/) | `biome.json(c)` config file |
|
||||
| zig | .zig, .zon | `zig` command available |
|
||||
| clang-format | .c, .cpp, .h, .hpp, .ino, and [more](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` config file |
|
||||
| ktlint | .kt, .kts | `ktlint` command available |
|
||||
| ruff | .py, .pyi | `ruff` command available with config |
|
||||
| uv | .py, .pyi | `uv` command available |
|
||||
| rubocop | .rb, .rake, .gemspec, .ru | `rubocop` command available |
|
||||
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` command available |
|
||||
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` command available |
|
||||
| air | .R | `air` command available |
|
||||
| dart | .dart | `dart` command available |
|
||||
| ocamlformat | .ml, .mli | `ocamlformat` command available and `.ocamlformat` config file |
|
||||
| terraform | .tf, .tfvars | `terraform` command available |
|
||||
| gleam | .gleam | `gleam` command available |
|
||||
| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | `oxfmt` dependency in `package.json` and an [experiental env variable flag](/docs/cli/#experimental) |
|
||||
| Formatter | Extensions | Requirements |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| gofmt | .go | `gofmt` command available |
|
||||
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` command available |
|
||||
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://prettier.io/docs/en/index.html) | `prettier` dependency in `package.json` |
|
||||
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://biomejs.dev/) | `biome.json(c)` config file |
|
||||
| zig | .zig, .zon | `zig` command available |
|
||||
| clang-format | .c, .cpp, .h, .hpp, .ino, and [more](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` config file |
|
||||
| ktlint | .kt, .kts | `ktlint` command available |
|
||||
| ruff | .py, .pyi | `ruff` command available with config |
|
||||
| rustfmt | .rs | `rustfmt` command available |
|
||||
| cargofmt | .rs | `cargo fmt` command available |
|
||||
| uv | .py, .pyi | `uv` command available |
|
||||
| rubocop | .rb, .rake, .gemspec, .ru | `rubocop` command available |
|
||||
| standardrb | .rb, .rake, .gemspec, .ru | `standardrb` command available |
|
||||
| htmlbeautifier | .erb, .html.erb | `htmlbeautifier` command available |
|
||||
| air | .R | `air` command available |
|
||||
| dart | .dart | `dart` command available |
|
||||
| ocamlformat | .ml, .mli | `ocamlformat` command available and `.ocamlformat` config file |
|
||||
| terraform | .tf, .tfvars | `terraform` command available |
|
||||
| gleam | .gleam | `gleam` command available |
|
||||
| nixfmt | .nix | `nixfmt` command available |
|
||||
| shfmt | .sh, .bash | `shfmt` command available |
|
||||
| oxfmt (Experimental) | .js, .jsx, .ts, .tsx | `oxfmt` dependency in `package.json` and an [experimental env variable flag](/docs/cli/#experimental) |
|
||||
|
||||
So if your project has `prettier` in your `package.json`, OpenCode will automatically use it.
|
||||
|
||||
|
|
|
|||
|
|
@ -58,12 +58,12 @@ Or you can set it up manually.
|
|||
id-token: write
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Run OpenCode
|
||||
uses: sst/opencode/github@latest
|
||||
uses: anomalyco/opencode/github@latest
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
with:
|
||||
|
|
@ -104,12 +104,14 @@ Or you can set it up manually.
|
|||
|
||||
OpenCode can be triggered by the following GitHub events:
|
||||
|
||||
| Event Type | Triggered By | Details |
|
||||
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `issue_comment` | Comment on an issue or PR | Mention `/opencode` or `/oc` in your comment. OpenCode reads the issue/PR context and can create branches, open PRs, or reply with explanations. |
|
||||
| `pull_request_review_comment` | Comment on specific code lines in a PR | Mention `/opencode` or `/oc` while reviewing code. OpenCode receives file path, line numbers, and diff context for precise responses. |
|
||||
| `schedule` | Cron-based schedule | Run OpenCode on a schedule using the `prompt` input. Useful for automated code reviews, reports, or maintenance tasks. OpenCode can create issues or PRs as needed. |
|
||||
| `pull_request` | PR opened or updated | Automatically trigger OpenCode when PRs are opened, synchronized, or reopened. Useful for automated reviews without needing to leave a comment. |
|
||||
| Event Type | Triggered By | Details |
|
||||
| ----------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| `issue_comment` | Comment on an issue or PR | Mention `/opencode` or `/oc` in your comment. OpenCode reads context and can create branches, open PRs, or reply. |
|
||||
| `pull_request_review_comment` | Comment on specific code lines in a PR | Mention `/opencode` or `/oc` while reviewing code. OpenCode receives file path, line numbers, and diff context. |
|
||||
| `issues` | Issue opened or edited | Automatically trigger OpenCode when issues are created or modified. Requires `prompt` input. |
|
||||
| `pull_request` | PR opened or updated | Automatically trigger OpenCode when PRs are opened, synchronized, or reopened. Useful for automated reviews. |
|
||||
| `schedule` | Cron-based schedule | Run OpenCode on a schedule. Requires `prompt` input. Output goes to logs and PRs (no issue to comment on). |
|
||||
| `workflow_dispatch` | Manual trigger from GitHub UI | Trigger OpenCode on demand via Actions tab. Requires `prompt` input. Output goes to logs and PRs. |
|
||||
|
||||
### Schedule Example
|
||||
|
||||
|
|
@ -132,10 +134,10 @@ jobs:
|
|||
issues: write
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Run OpenCode
|
||||
uses: sst/opencode/github@latest
|
||||
uses: anomalyco/opencode/github@latest
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
with:
|
||||
|
|
@ -145,9 +147,7 @@ jobs:
|
|||
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.
|
||||
|
||||
> **Note:** 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 during a scheduled run.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -171,8 +171,8 @@ jobs:
|
|||
pull-requests: read
|
||||
issues: read
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: sst/opencode/github@latest
|
||||
- uses: actions/checkout@v6
|
||||
- uses: anomalyco/opencode/github@latest
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
with:
|
||||
|
|
@ -188,12 +188,65 @@ For `pull_request` events, if no `prompt` is provided, OpenCode defaults to revi
|
|||
|
||||
---
|
||||
|
||||
### Issues Triage Example
|
||||
|
||||
Automatically triage new issues. This example filters to accounts older than 30 days to reduce spam:
|
||||
|
||||
```yaml title=".github/workflows/opencode-triage.yml"
|
||||
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'
|
||||
|
||||
- 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.
|
||||
```
|
||||
|
||||
For `issues` events, the `prompt` input is **required** since there's no comment to extract instructions from.
|
||||
|
||||
---
|
||||
|
||||
## Custom prompts
|
||||
|
||||
Override the default prompt to customize OpenCode's behavior for your workflow.
|
||||
|
||||
```yaml title=".github/workflows/opencode.yml"
|
||||
- uses: sst/opencode/github@latest
|
||||
- uses: anomalyco/opencode/github@latest
|
||||
with:
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
prompt: |
|
||||
|
|
|
|||
|
|
@ -76,9 +76,11 @@ You can also install it with the following commands:
|
|||
- **Using Homebrew on macOS and Linux**
|
||||
|
||||
```bash
|
||||
brew install opencode
|
||||
brew install anomalyco/tap/opencode
|
||||
```
|
||||
|
||||
> We recommend using the OpenCode tap for the most up to date releases. The official `brew install opencode` formula is maintained by the Homebrew team and is updated less frequently.
|
||||
|
||||
- **Using Paru on Arch Linux**
|
||||
|
||||
```bash
|
||||
|
|
@ -109,18 +111,18 @@ You can also install it with the following commands:
|
|||
- **Using Mise**
|
||||
|
||||
```bash
|
||||
mise use -g github:sst/opencode
|
||||
mise use -g github:anomalyco/opencode
|
||||
```
|
||||
|
||||
- **Using Docker**
|
||||
|
||||
```bash
|
||||
docker run -it --rm ghcr.io/sst/opencode
|
||||
docker run -it --rm ghcr.io/anomalyco/opencode
|
||||
```
|
||||
|
||||
Support for installing OpenCode on Windows using Bun is currently in progress.
|
||||
|
||||
You can also grab the binary from the [Releases](https://github.com/sst/opencode/releases).
|
||||
You can also grab the binary from the [Releases](https://github.com/anomalyco/opencode/releases).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -14,12 +14,16 @@ OpenCode has a list of keybinds that you can customize through the OpenCode conf
|
|||
"editor_open": "<leader>e",
|
||||
"theme_list": "<leader>t",
|
||||
"sidebar_toggle": "<leader>b",
|
||||
"scrollbar_toggle": "none",
|
||||
"username_toggle": "none",
|
||||
"status_view": "<leader>s",
|
||||
"tool_details": "none",
|
||||
"session_export": "<leader>x",
|
||||
"session_new": "<leader>n",
|
||||
"session_list": "<leader>l",
|
||||
"session_timeline": "<leader>g",
|
||||
"session_fork": "none",
|
||||
"session_rename": "none",
|
||||
"session_share": "none",
|
||||
"session_unshare": "none",
|
||||
"session_interrupt": "escape",
|
||||
|
|
@ -43,6 +47,9 @@ OpenCode has a list of keybinds that you can customize through the OpenCode conf
|
|||
"model_list": "<leader>m",
|
||||
"model_cycle_recent": "f2",
|
||||
"model_cycle_recent_reverse": "shift+f2",
|
||||
"model_cycle_favorite": "none",
|
||||
"model_cycle_favorite_reverse": "none",
|
||||
"variant_cycle": "ctrl+t",
|
||||
"command_list": "ctrl+p",
|
||||
"agent_list": "<leader>a",
|
||||
"agent_cycle": "tab",
|
||||
|
|
@ -86,7 +93,9 @@ OpenCode has a list of keybinds that you can customize through the OpenCode conf
|
|||
"input_delete_word_backward": "ctrl+w,ctrl+backspace,alt+backspace",
|
||||
"history_previous": "up",
|
||||
"history_next": "down",
|
||||
"terminal_suspend": "ctrl+z"
|
||||
"terminal_suspend": "ctrl+z",
|
||||
"terminal_title_toggle": "none",
|
||||
"tips_toggle": "<leader>h"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -118,6 +127,28 @@ You can disable a keybind by adding the key to your config with a value of "none
|
|||
|
||||
---
|
||||
|
||||
## Desktop prompt shortcuts
|
||||
|
||||
The OpenCode desktop app prompt input supports common Readline/Emacs-style shortcuts for editing text. These are built-in and currently not configurable via `opencode.json`.
|
||||
|
||||
| Shortcut | Action |
|
||||
| -------- | ---------------------------------------- |
|
||||
| `ctrl+a` | Move to start of current line |
|
||||
| `ctrl+e` | Move to end of current line |
|
||||
| `ctrl+b` | Move cursor back one character |
|
||||
| `ctrl+f` | Move cursor forward one character |
|
||||
| `alt+b` | Move cursor back one word |
|
||||
| `alt+f` | Move cursor forward one word |
|
||||
| `ctrl+d` | Delete character under cursor |
|
||||
| `ctrl+k` | Kill to end of line |
|
||||
| `ctrl+u` | Kill to start of line |
|
||||
| `ctrl+w` | Kill previous word |
|
||||
| `alt+d` | Kill next word |
|
||||
| `ctrl+t` | Transpose characters |
|
||||
| `ctrl+g` | Cancel popovers / abort running response |
|
||||
|
||||
---
|
||||
|
||||
## Shift+Enter
|
||||
|
||||
Some terminals don't send modifier keys with Enter by default. You may need to configure your terminal to send `Shift+Enter` as an escape sequence.
|
||||
|
|
|
|||
|
|
@ -26,11 +26,13 @@ OpenCode comes with several built-in LSP servers for popular languages:
|
|||
| gleam | .gleam | `gleam` command available |
|
||||
| gopls | .go | `go` command available |
|
||||
| jdtls | .java | `Java SDK (version 21+)` installed |
|
||||
| kotlin-ls | .kt, .kts | Auto-installs for Kotlin projects |
|
||||
| lua-ls | .lua | Auto-installs for Lua projects |
|
||||
| nixd | .nix | `nixd` command available |
|
||||
| ocaml-lsp | .ml, .mli | `ocamllsp` command available |
|
||||
| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | `oxlint` dependency in project |
|
||||
| php intelephense | .php | Auto-installs for PHP projects |
|
||||
| prisma | .prisma | `prisma` command available |
|
||||
| pyright | .py, .pyi | `pyright` dependency installed |
|
||||
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | `ruby` and `gem` commands available |
|
||||
| rust | .rs | `rust-analyzer` command available |
|
||||
|
|
|
|||
|
|
@ -3,37 +3,27 @@ title: MCP servers
|
|||
description: Add local and remote MCP tools.
|
||||
---
|
||||
|
||||
You can add external tools to OpenCode using the _Model Context Protocol_, or MCP.
|
||||
|
||||
OpenCode supports both:
|
||||
|
||||
- Local servers
|
||||
- Remote servers
|
||||
You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both local and remote servers.
|
||||
|
||||
Once added, MCP tools are automatically available to the LLM alongside built-in tools.
|
||||
|
||||
---
|
||||
|
||||
## Caveats
|
||||
#### Caveats
|
||||
|
||||
When you use an MCP server, it adds to the context. This can quickly add up if
|
||||
you have a lot of tools. So we recommend being careful with which MCP servers
|
||||
you use.
|
||||
When you use an MCP server, it adds to the context. This can quickly add up if you have a lot of tools. So we recommend being careful with which MCP servers you use.
|
||||
|
||||
:::tip
|
||||
MCP servers add to your context, so you want to be careful with which
|
||||
ones you enable.
|
||||
MCP servers add to your context, so you want to be careful with which ones you enable.
|
||||
:::
|
||||
|
||||
Certain MCP servers, like the GitHub MCP server tend to add a lot of tokens and
|
||||
can easily exceed the context limit.
|
||||
Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit.
|
||||
|
||||
---
|
||||
|
||||
## Configure
|
||||
## Enable
|
||||
|
||||
You can define MCP servers in your OpenCode config under `mcp`. Add each MCP
|
||||
with a unique name. You can refer to that MCP by name when prompting the LLM.
|
||||
You can define MCP servers in your [OpenCode Config](https://opencode.ai/docs/config/) under `mcp`. Add each MCP with a unique name. You can refer to that MCP by name when prompting the LLM.
|
||||
|
||||
```jsonc title="opencode.jsonc" {6}
|
||||
{
|
||||
|
|
@ -54,7 +44,30 @@ You can also disable a server by setting `enabled` to `false`. This is useful if
|
|||
|
||||
---
|
||||
|
||||
### Local
|
||||
### Overriding remote defaults
|
||||
|
||||
Organizations can provide default MCP servers via their `.well-known/opencode` endpoint. These servers may be disabled by default, allowing users to opt-in to the ones they need.
|
||||
|
||||
To enable a specific server from your organization's remote config, add it to your local config with `enabled: true`:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"jira": {
|
||||
"type": "remote",
|
||||
"url": "https://jira.example.com/mcp",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Your local config values override the remote defaults. See [config precedence](/docs/config#precedence-order) for more details.
|
||||
|
||||
---
|
||||
|
||||
## Local
|
||||
|
||||
Add local MCP servers using `type` to `"local"` within the MCP object.
|
||||
|
||||
|
|
@ -77,8 +90,7 @@ Add local MCP servers using `type` to `"local"` within the MCP object.
|
|||
|
||||
The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
|
||||
|
||||
For example, here's how I can add the test
|
||||
[`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
|
||||
For example, here's how you can add the test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
|
|
@ -98,6 +110,8 @@ And to use it I can add `use the mcp_everything tool` to my prompts.
|
|||
use the mcp_everything tool to add the number 3 and 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Options
|
||||
|
||||
Here are all the options for configuring a local MCP server.
|
||||
|
|
@ -112,9 +126,9 @@ Here are all the options for configuring a local MCP server.
|
|||
|
||||
---
|
||||
|
||||
### Remote
|
||||
## Remote
|
||||
|
||||
Add remote MCP servers under by setting `type` to `"remote"`.
|
||||
Add remote MCP servers by setting `type` to `"remote"`.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
|
|
@ -132,7 +146,9 @@ Add remote MCP servers under by setting `type` to `"remote"`.
|
|||
}
|
||||
```
|
||||
|
||||
Here the `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
|
||||
The `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
|
||||
|
||||
---
|
||||
|
||||
#### Options
|
||||
|
||||
|
|
@ -147,7 +163,7 @@ Here the `url` is the URL of the remote MCP server and with the `headers` option
|
|||
|
||||
---
|
||||
|
||||
### OAuth
|
||||
## OAuth
|
||||
|
||||
OpenCode automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, OpenCode will:
|
||||
|
||||
|
|
@ -155,7 +171,9 @@ OpenCode automatically handles OAuth authentication for remote MCP servers. When
|
|||
2. Use **Dynamic Client Registration (RFC 7591)** if supported by the server
|
||||
3. Store tokens securely for future requests
|
||||
|
||||
#### Automatic OAuth
|
||||
---
|
||||
|
||||
### Automatic
|
||||
|
||||
For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server:
|
||||
|
||||
|
|
@ -173,11 +191,13 @@ For most OAuth-enabled MCP servers, no special configuration is needed. Just con
|
|||
|
||||
If the server requires authentication, OpenCode will prompt you to authenticate when you first try to use it. If not, you can [manually trigger the flow](#authenticating) with `opencode mcp auth <server-name>`.
|
||||
|
||||
#### Pre-registered Client
|
||||
---
|
||||
|
||||
### Pre-registered
|
||||
|
||||
If you have client credentials from the MCP server provider, you can configure them:
|
||||
|
||||
```json title="opencode.json"
|
||||
```json title="opencode.json" {7-11}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
|
|
@ -194,11 +214,39 @@ If you have client credentials from the MCP server provider, you can configure t
|
|||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Authenticating
|
||||
|
||||
You can manually trigger authentication or manage credentials.
|
||||
|
||||
Authenticate with a specific MCP server:
|
||||
|
||||
```bash
|
||||
opencode mcp auth my-oauth-server
|
||||
```
|
||||
|
||||
List all MCP servers and their auth status:
|
||||
|
||||
```bash
|
||||
opencode mcp list
|
||||
```
|
||||
|
||||
Remove stored credentials:
|
||||
|
||||
```bash
|
||||
opencode mcp logout my-oauth-server
|
||||
```
|
||||
|
||||
The `mcp auth` command will open your browser for authorization. After you authorize, OpenCode will store the tokens securely in `~/.local/share/opencode/mcp-auth.json`.
|
||||
|
||||
---
|
||||
|
||||
#### Disabling OAuth
|
||||
|
||||
If you want to disable automatic OAuth for a server (e.g., for servers that use API keys instead), set `oauth` to `false`:
|
||||
|
||||
```json title="opencode.json"
|
||||
```json title="opencode.json" {7}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
|
|
@ -214,31 +262,16 @@ If you want to disable automatic OAuth for a server (e.g., for servers that use
|
|||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### OAuth Options
|
||||
|
||||
| Option | Type | Required | Description |
|
||||
| -------------- | --------------- | -------- | -------------------------------------------------------------------------------- |
|
||||
| `oauth` | Object \| false | | OAuth config object, or `false` to disable OAuth auto-detection. |
|
||||
| `clientId` | String | | OAuth client ID. If not provided, dynamic client registration will be attempted. |
|
||||
| `clientSecret` | String | | OAuth client secret, if required by the authorization server. |
|
||||
| `scope` | String | | OAuth scopes to request during authorization. |
|
||||
|
||||
#### Authenticating
|
||||
|
||||
You can manually trigger authentication or manage credentials:
|
||||
|
||||
```bash
|
||||
# Authenticate with a specific MCP server
|
||||
opencode mcp auth my-oauth-server
|
||||
|
||||
# List all MCP servers and their auth status
|
||||
opencode mcp list
|
||||
|
||||
# Remove stored credentials
|
||||
opencode mcp logout my-oauth-server
|
||||
```
|
||||
|
||||
The `mcp auth` command will open your browser for authorization. After you authorize, OpenCode will store the tokens securely in `~/.local/share/opencode/mcp-auth.json`.
|
||||
| Option | Type | Description |
|
||||
| -------------- | --------------- | -------------------------------------------------------------------------------- |
|
||||
| `oauth` | Object \| false | OAuth config object, or `false` to disable OAuth auto-detection. |
|
||||
| `clientId` | String | OAuth client ID. If not provided, dynamic client registration will be attempted. |
|
||||
| `clientSecret` | String | OAuth client secret, if required by the authorization server. |
|
||||
| `scope` | String | OAuth scopes to request during authorization. |
|
||||
|
||||
#### Debugging
|
||||
|
||||
|
|
@ -258,8 +291,7 @@ The `mcp debug` command shows the current auth status, tests HTTP connectivity,
|
|||
|
||||
## Manage
|
||||
|
||||
Your MCPs are available as tools in OpenCode, alongside built-in tools. So you
|
||||
can manage them through the OpenCode config like any other tool.
|
||||
Your MCPs are available as tools in OpenCode, alongside built-in tools. So you can manage them through the OpenCode config like any other tool.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -313,11 +345,10 @@ Here we are using the glob pattern `my-mcp*` to disable all MCPs.
|
|||
|
||||
### Per agent
|
||||
|
||||
If you have a large number of MCP servers you may want to only enable them per
|
||||
agent and disable them globally. To do this:
|
||||
If you have a large number of MCP servers you may want to only enable them per agent and disable them globally. To do this:
|
||||
|
||||
1. Disable it as a tool globally.
|
||||
2. In your [agent config](/docs/agents#tools) enable the MCP server as a tool.
|
||||
2. In your [agent config](/docs/agents#tools), enable the MCP server as a tool.
|
||||
|
||||
```json title="opencode.json" {11, 14-18}
|
||||
{
|
||||
|
|
@ -346,12 +377,21 @@ agent and disable them globally. To do this:
|
|||
|
||||
#### Glob patterns
|
||||
|
||||
The glob pattern uses simple regex globbing patterns.
|
||||
The glob pattern uses simple regex globbing patterns:
|
||||
|
||||
- `*` matches zero or more of any character
|
||||
- `*` matches zero or more of any character (e.g., `"my-mcp*"` matches `my-mcp_search`, `my-mcp_list`, etc.)
|
||||
- `?` matches exactly one character
|
||||
- All other characters match literally
|
||||
|
||||
:::note
|
||||
MCP server tools are registered with server name as prefix, so to diable all tools for a server simply use:
|
||||
|
||||
```
|
||||
"mymcpservername_*": false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
|
@ -360,6 +400,39 @@ Below are examples of some common MCP servers. You can submit a PR if you want t
|
|||
|
||||
---
|
||||
|
||||
### Sentry
|
||||
|
||||
Add the [Sentry MCP server](https://mcp.sentry.dev) to interact with your Sentry projects and issues.
|
||||
|
||||
```json title="opencode.json" {4-8}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"sentry": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.sentry.dev/mcp",
|
||||
"oauth": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After adding the configuration, authenticate with Sentry:
|
||||
|
||||
```bash
|
||||
opencode mcp auth sentry
|
||||
```
|
||||
|
||||
This will open a browser window to complete the OAuth flow and connect OpenCode to your Sentry account.
|
||||
|
||||
Once authenticated, you can use Sentry tools in your prompts to query issues, projects, and error data.
|
||||
|
||||
```txt "use sentry"
|
||||
Show me the latest unresolved issues in my project. use sentry
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Context7
|
||||
|
||||
Add the [Context7 MCP server](https://github.com/upstash/context7) to search through docs.
|
||||
|
|
@ -401,8 +474,7 @@ Add `use context7` to your prompts to use Context7 MCP server.
|
|||
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
|
||||
```
|
||||
|
||||
Alternatively, you can add something like this to your
|
||||
[AGENTS.md](/docs/rules/).
|
||||
Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
|
||||
|
||||
```md title="AGENTS.md"
|
||||
When you need to search docs, use `context7` tools.
|
||||
|
|
@ -432,9 +504,8 @@ Since we named our MCP server `gh_grep`, you can add `use the gh_grep tool` to y
|
|||
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
|
||||
```
|
||||
|
||||
Alternatively, you can add something like this to your
|
||||
[AGENTS.md](/docs/rules/).
|
||||
Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
|
||||
|
||||
```md title="AGENTS.md"
|
||||
If you are unsure how to do something, use `gh_grep` to search code examples from github.
|
||||
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
|
||||
```
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Models
|
|||
description: Configuring an LLM provider and model.
|
||||
---
|
||||
|
||||
OpenCode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support for **75+ LLM providers** and it supports running local models.
|
||||
OpenCode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support **75+ LLM providers** and it supports running local models.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -35,15 +35,13 @@ Consider using one of the models we recommend.
|
|||
|
||||
However, there are only a few of them that are good at both generating code and tool calling.
|
||||
|
||||
Here are several models that work well with OpenCode, in no particular order. (This is not an exhaustive list):
|
||||
Here are several models that work well with OpenCode, in no particular order. (This is not an exhaustive list nor is it necessarily up to date):
|
||||
|
||||
- GPT 5.1
|
||||
- GPT 5.2
|
||||
- GPT 5.1 Codex
|
||||
- Claude Opus 4.5
|
||||
- Claude Sonnet 4.5
|
||||
- Claude Haiku 4.5
|
||||
- Kimi K2
|
||||
- GLM 4.6
|
||||
- Qwen3 Coder
|
||||
- Minimax M2.1
|
||||
- Gemini 3 Pro
|
||||
|
||||
---
|
||||
|
|
@ -107,30 +105,26 @@ The built-in provider and model names can be found on [Models.dev](https://model
|
|||
|
||||
You can also configure these options for any agents that you are using. The agent config overrides any global options here. [Learn more](/docs/agents/#additional).
|
||||
|
||||
You can also define custom models that extend built-in ones and can optionally use specific options by referring to their id:
|
||||
You can also define custom variants that extend built-in ones. Variants let you configure different settings for the same model without creating duplicate entries:
|
||||
|
||||
```jsonc title="opencode.jsonc" {6-20}
|
||||
```jsonc title="opencode.jsonc" {6-21}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"opencode": {
|
||||
"models": {
|
||||
"gpt-5-high": {
|
||||
"id": "gpt-5",
|
||||
"name": "MyGPT5 (High Reasoning)",
|
||||
"options": {
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
},
|
||||
},
|
||||
"gpt-5-low": {
|
||||
"id": "gpt-5",
|
||||
"name": "MyGPT5 (Low Reasoning)",
|
||||
"options": {
|
||||
"reasoningEffort": "low",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
"gpt-5": {
|
||||
"variants": {
|
||||
"high": {
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
},
|
||||
"low": {
|
||||
"reasoningEffort": "low",
|
||||
"textVerbosity": "low",
|
||||
"reasoningSummary": "auto",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
|
@ -141,6 +135,72 @@ You can also define custom models that extend built-in ones and can optionally u
|
|||
|
||||
---
|
||||
|
||||
## Variants
|
||||
|
||||
Many models support multiple variants with different configurations. OpenCode ships with built-in default variants for popular providers.
|
||||
|
||||
### Built-in variants
|
||||
|
||||
OpenCode ships with default variants for many providers:
|
||||
|
||||
**Anthropic**:
|
||||
|
||||
- `high` - High thinking budget (default)
|
||||
- `max` - Maximum thinking budget
|
||||
|
||||
**OpenAI**:
|
||||
|
||||
Varies by model but roughly:
|
||||
|
||||
- `none` - No reasoning
|
||||
- `minimal` - Minimal reasoning effort
|
||||
- `low` - Low reasoning effort
|
||||
- `medium` - Medium reasoning effort
|
||||
- `high` - High reasoning effort
|
||||
- `xhigh` - Extra high reasoning effort
|
||||
|
||||
**Google**:
|
||||
|
||||
- `low` - Lower effort/token budget
|
||||
- `high` - Higher effort/token budget
|
||||
|
||||
:::tip
|
||||
This list is not comprehensive. Many other providers have built-in defaults too.
|
||||
:::
|
||||
|
||||
### Custom variants
|
||||
|
||||
You can override existing variants or add your own:
|
||||
|
||||
```jsonc title="opencode.jsonc" {7-18}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"openai": {
|
||||
"models": {
|
||||
"gpt-5": {
|
||||
"variants": {
|
||||
"thinking": {
|
||||
"reasoningEffort": "high",
|
||||
"textVerbosity": "low",
|
||||
},
|
||||
"fast": {
|
||||
"disabled": true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Cycle variants
|
||||
|
||||
Use the keybind `variant_cycle` to quickly switch between variants. [Learn more](/docs/keybinds).
|
||||
|
||||
---
|
||||
|
||||
## Loading models
|
||||
|
||||
When OpenCode starts up, it checks for models in the following priority order:
|
||||
|
|
|
|||
|
|
@ -3,129 +3,75 @@ title: Permissions
|
|||
description: Control which actions require approval to run.
|
||||
---
|
||||
|
||||
By default, OpenCode allows most operations without approval, except `doom_loop` and `external_directory` which default to `ask`. You can configure this using the `permission` option.
|
||||
OpenCode uses the `permission` config to decide whether a given action should run automatically, prompt you, or be blocked.
|
||||
|
||||
As of `v1.1.1`, the legacy `tools` boolean config is deprecated and has been merged into `permission`. The old `tools` config is still supported for backwards compatibility.
|
||||
|
||||
---
|
||||
|
||||
## Actions
|
||||
|
||||
Each permission rule resolves to one of:
|
||||
|
||||
- `"allow"` — run without approval
|
||||
- `"ask"` — prompt for approval
|
||||
- `"deny"` — block the action
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
You can set permissions globally (with `*`), and override specific tools.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "allow",
|
||||
"bash": "ask",
|
||||
"skill": "ask",
|
||||
"webfetch": "deny",
|
||||
"doom_loop": "ask",
|
||||
"external_directory": "ask"
|
||||
"*": "ask",
|
||||
"bash": "allow",
|
||||
"edit": "deny"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This lets you configure granular controls for the `edit`, `bash`, `skill`, `webfetch`, `doom_loop`, and `external_directory` tools.
|
||||
You can also set all permissions at once:
|
||||
|
||||
- `"ask"` — Prompt for approval before running the tool
|
||||
- `"allow"` — Allow all operations without approval
|
||||
- `"deny"` — Disable the tool
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
|
||||
Currently, the permissions for the `edit`, `bash`, `skill`, `webfetch`, `doom_loop`, and `external_directory` tools can be configured through the `permission` option.
|
||||
|
||||
---
|
||||
|
||||
### edit
|
||||
|
||||
Use the `permission.edit` key to control whether file editing operations require user approval.
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "ask"
|
||||
}
|
||||
"permission": "allow"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### bash
|
||||
## Granular Rules (Object Syntax)
|
||||
|
||||
You can use the `permission.bash` key to control whether bash commands as a
|
||||
whole need user approval.
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or, you can target specific commands and set it to `allow`, `ask`, or `deny`.
|
||||
For most permissions, you can use an object to apply different actions based on the tool input.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": {
|
||||
"git push": "ask",
|
||||
"git status": "allow",
|
||||
"git diff": "allow",
|
||||
"npm run build": "allow",
|
||||
"ls": "allow",
|
||||
"pwd": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Wildcards
|
||||
|
||||
You can also use wildcards to manage permissions for specific bash commands.
|
||||
|
||||
:::tip
|
||||
You can use wildcards to manage permissions for specific bash commands.
|
||||
:::
|
||||
|
||||
For example, **disable all** Terraform commands.
|
||||
|
||||
```json title="opencode.json" {5}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": {
|
||||
"terraform *": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also use the `*` wildcard to manage permissions for all commands. For
|
||||
example, **deny all commands** except a couple of specific ones.
|
||||
|
||||
```json title="opencode.json" {5}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git *": "allow",
|
||||
"npm *": "allow",
|
||||
"rm *": "deny"
|
||||
},
|
||||
"edit": {
|
||||
"*": "deny",
|
||||
"pwd": "allow",
|
||||
"git status": "ask"
|
||||
"packages/web/src/content/docs/*.mdx": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here a specific rule can override the `*` wildcard.
|
||||
Rules are evaluated by pattern match, with the **last matching rule winning**. A common pattern is to put the catch-all `"*"` rule first, and more specific rules after it.
|
||||
|
||||
---
|
||||
### Wildcards
|
||||
|
||||
##### Glob patterns
|
||||
|
||||
The wildcard uses simple regex globbing patterns.
|
||||
Permission patterns use simple wildcard matching:
|
||||
|
||||
- `*` matches zero or more of any character
|
||||
- `?` matches exactly one character
|
||||
|
|
@ -133,43 +79,43 @@ The wildcard uses simple regex globbing patterns.
|
|||
|
||||
---
|
||||
|
||||
#### Scope of the `"ask"` option
|
||||
## Available Permissions
|
||||
|
||||
When the agent asks for permission to run a particular bash command, it will
|
||||
request feedback with the three options "accept", "accept always" and "deny".
|
||||
The "accept always" answer applies for the rest of the current session.
|
||||
OpenCode permissions are keyed by tool name, plus a couple of safety guards:
|
||||
|
||||
In addition, command permissions are applied to the first two elements of a command. So, an "accept always" response for a command like `git log` would whitelist `git log *` but not `git commit ...`.
|
||||
|
||||
When an agent asks for permission to run a command in a pipeline, we use tree sitter to parse each command in the pipeline. The "accept always" permission thus applies separately to each command in the pipeline.
|
||||
- `read` — reading a file (matches the file path)
|
||||
- `edit` — all file modifications (covers `edit`, `write`, `patch`, `multiedit`)
|
||||
- `glob` — file globbing (matches the glob pattern)
|
||||
- `grep` — content search (matches the regex pattern)
|
||||
- `list` — listing files in a directory (matches the directory path)
|
||||
- `bash` — running shell commands (matches parsed commands like `git status --porcelain`)
|
||||
- `task` — launching subagents (matches the subagent type)
|
||||
- `skill` — loading a skill (matches the skill name)
|
||||
- `lsp` — running LSP queries (currently non-granular)
|
||||
- `todoread`, `todowrite` — reading/updating the todo list
|
||||
- `webfetch` — fetching a URL (matches the URL)
|
||||
- `websearch`, `codesearch` — web/code search (matches the query)
|
||||
- `external_directory` — triggered when a tool touches paths outside the project working directory
|
||||
- `doom_loop` — triggered when the same tool call repeats 3 times with identical input
|
||||
|
||||
---
|
||||
|
||||
### skill
|
||||
## Defaults
|
||||
|
||||
Use the `permission.skill` key to control whether the model can load skills via the built-in `skill` tool.
|
||||
If you don’t specify anything, OpenCode starts from permissive defaults:
|
||||
|
||||
You can apply a single rule to all skills:
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"skill": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or configure per-skill rules (supports the same wildcard patterns as `permission.bash`):
|
||||
- Most permissions default to `"allow"`.
|
||||
- `doom_loop` and `external_directory` default to `"ask"`.
|
||||
- `read` is `"allow"`, but `.env` files are denied by default:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"skill": {
|
||||
"*": "deny",
|
||||
"git-*": "allow",
|
||||
"frontend/*": "ask"
|
||||
"read": {
|
||||
"*": "allow",
|
||||
"*.env": "deny",
|
||||
"*.env.*": "deny",
|
||||
"*.env.example": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -177,72 +123,37 @@ Or configure per-skill rules (supports the same wildcard patterns as `permission
|
|||
|
||||
---
|
||||
|
||||
### webfetch
|
||||
## What “Ask” Does
|
||||
|
||||
Use the `permission.webfetch` key to control whether the LLM can fetch web pages.
|
||||
When OpenCode prompts for approval, the UI offers three outcomes:
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"webfetch": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
- `once` — approve just this request
|
||||
- `always` — approve future requests matching the suggested patterns (for the rest of the current OpenCode session)
|
||||
- `reject` — deny the request
|
||||
|
||||
---
|
||||
|
||||
### doom_loop
|
||||
|
||||
Use the `permission.doom_loop` key to control whether approval is required when a doom loop is detected. A doom loop occurs when the same tool is called 3 times in a row with identical arguments.
|
||||
|
||||
This helps prevent infinite loops where the LLM repeatedly attempts the same action without making progress.
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"doom_loop": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### external_directory
|
||||
|
||||
Use the `permission.external_directory` key to control whether file operations require approval when accessing files outside the working directory.
|
||||
|
||||
This provides an additional safety layer to prevent unintended modifications to files outside your project.
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"external_directory": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
The set of patterns that `always` would approve is provided by the tool (for example, bash approvals typically whitelist a safe command prefix like `git status*`).
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
You can also configure permissions per agent. Where the agent specific config
|
||||
overrides the global config. [Learn more](/docs/agents#permissions) about agent permissions.
|
||||
You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence. [Learn more](/docs/agents#permissions) about agent permissions.
|
||||
|
||||
```json title="opencode.json" {3-7,10-14}
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"bash": {
|
||||
"git push": "ask"
|
||||
"*": "ask",
|
||||
"git status": "allow"
|
||||
}
|
||||
},
|
||||
"agent": {
|
||||
"build": {
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git status": "allow",
|
||||
"git push": "allow"
|
||||
}
|
||||
}
|
||||
|
|
@ -251,10 +162,7 @@ overrides the global config. [Learn more](/docs/agents#permissions) about agent
|
|||
}
|
||||
```
|
||||
|
||||
For example, here the `build` agent overrides the global `bash` permission to
|
||||
allow `git push` commands.
|
||||
|
||||
You can also configure permissions for agents in Markdown.
|
||||
You can also configure agent permissions in Markdown:
|
||||
|
||||
```markdown title="~/.config/opencode/agent/review.md"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -9,6 +9,61 @@ For examples, check out the [plugins](/docs/ecosystem#plugins) created by the co
|
|||
|
||||
---
|
||||
|
||||
## Use a plugin
|
||||
|
||||
There are two ways to load plugins.
|
||||
|
||||
---
|
||||
|
||||
### From local files
|
||||
|
||||
Place JavaScript or TypeScript files in the plugin directory.
|
||||
|
||||
- `.opencode/plugin/` - Project-level plugins
|
||||
- `~/.config/opencode/plugin/` - Global plugins
|
||||
|
||||
Files in these directories are automatically loaded at startup.
|
||||
|
||||
---
|
||||
|
||||
### From npm
|
||||
|
||||
Specify npm packages in your config file.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
|
||||
}
|
||||
```
|
||||
|
||||
Both regular and scoped npm packages are supported.
|
||||
|
||||
Browse available plugins in the [ecosystem](/docs/ecosystem#plugins).
|
||||
|
||||
---
|
||||
|
||||
### How plugins are installed
|
||||
|
||||
**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in `~/.cache/opencode/node_modules/`.
|
||||
|
||||
**Local plugins** are loaded directly from the plugin directory. To use external packages, you must create a `package.json` within your config directory (see [Dependencies](#dependencies)), or publish the plugin to npm and [add it to your config](/docs/config#plugins).
|
||||
|
||||
---
|
||||
|
||||
### Load order
|
||||
|
||||
Plugins are loaded from all sources and all hooks run in sequence. The load order is:
|
||||
|
||||
1. Global config (`~/.config/opencode/opencode.json`)
|
||||
2. Project config (`opencode.json`)
|
||||
3. Global plugin directory (`~/.config/opencode/plugin/`)
|
||||
4. Project plugin directory (`.opencode/plugin/`)
|
||||
|
||||
Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.
|
||||
|
||||
---
|
||||
|
||||
## Create a plugin
|
||||
|
||||
A plugin is a **JavaScript/TypeScript module** that exports one or more plugin
|
||||
|
|
@ -16,12 +71,33 @@ functions. Each function receives a context object and returns a hooks object.
|
|||
|
||||
---
|
||||
|
||||
### Location
|
||||
### Dependencies
|
||||
|
||||
Plugins are loaded from:
|
||||
Local plugins and custom tools can use external npm packages. Add a `package.json` to your config directory with the dependencies you need.
|
||||
|
||||
1. `.opencode/plugin` directory either in your project
|
||||
2. Or, globally in `~/.config/opencode/plugin`
|
||||
```json title=".opencode/package.json"
|
||||
{
|
||||
"dependencies": {
|
||||
"shescape": "^2.1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OpenCode runs `bun install` at startup to install these. Your plugins and tools can then import them.
|
||||
|
||||
```ts title=".opencode/plugin/my-plugin.ts"
|
||||
import { escape } from "shescape"
|
||||
|
||||
export const MyPlugin = async (ctx) => {
|
||||
return {
|
||||
"tool.execute.before": async (input, output) => {
|
||||
if (input.tool === "bash") {
|
||||
output.args.command = escape(output.args.command)
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -154,6 +230,10 @@ export const NotificationPlugin = async ({ project, client, $, directory, worktr
|
|||
|
||||
We are using `osascript` to run AppleScript on macOS. Here we are using it to send notifications.
|
||||
|
||||
:::note
|
||||
If you’re using the OpenCode desktop app, it can send system notifications automatically when a response is ready or when a session errors.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### .env protection
|
||||
|
|
@ -208,6 +288,25 @@ Your custom tools will be available to opencode alongside built-in tools.
|
|||
|
||||
---
|
||||
|
||||
### Logging
|
||||
|
||||
Use `client.app.log()` instead of `console.log` for structured logging:
|
||||
|
||||
```ts title=".opencode/plugin/my-plugin.ts"
|
||||
export const MyPlugin = async ({ client }) => {
|
||||
await client.app.log({
|
||||
service: "my-plugin",
|
||||
level: "info",
|
||||
message: "Plugin initialized",
|
||||
extra: { foo: "bar" },
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Levels: `debug`, `info`, `warn`, `error`. See [SDK documentation](https://opencode.ai/docs/sdk) for details.
|
||||
|
||||
---
|
||||
|
||||
### Compaction hooks
|
||||
|
||||
Customize the context included when a session is compacted:
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ description: Using any LLM provider in OpenCode.
|
|||
import config from "../../../config.mjs"
|
||||
export const console = config.console
|
||||
|
||||
OpenCode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support for **75+ LLM providers** and it supports running local models.
|
||||
OpenCode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support **75+ LLM providers** and it supports running local models.
|
||||
|
||||
To add a provider you need to:
|
||||
|
||||
|
|
@ -80,8 +80,7 @@ If you are new, we recommend starting with OpenCode Zen.
|
|||
/models
|
||||
```
|
||||
|
||||
It works like any other provider in OpenCode. And is completely optional to use
|
||||
it.
|
||||
It works like any other provider in OpenCode and is completely optional to use.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -107,27 +106,96 @@ To use Amazon Bedrock with OpenCode:
|
|||
You need to have access to the model you want in Amazon Bedrock.
|
||||
:::
|
||||
|
||||
1. You'll need either to set one of the following environment variables:
|
||||
- `AWS_ACCESS_KEY_ID`: You can get this by creating an IAM user and generating
|
||||
an access key for it.
|
||||
- `AWS_PROFILE`: First login through AWS IAM Identity Center (or AWS SSO) using
|
||||
`aws sso login`. Then get the name of the profile you want to use.
|
||||
- `AWS_BEARER_TOKEN_BEDROCK`: You can generate a long-term API key from the
|
||||
Amazon Bedrock console.
|
||||
2. **Configure authentication** using one of the following methods:
|
||||
|
||||
Once you have one of the above, set it while running opencode.
|
||||
#### Environment Variables (Quick Start)
|
||||
|
||||
Set one of these environment variables while running opencode:
|
||||
|
||||
```bash
|
||||
AWS_ACCESS_KEY_ID=XXX opencode
|
||||
# Option 1: Using AWS access keys
|
||||
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode
|
||||
|
||||
# Option 2: Using named AWS profile
|
||||
AWS_PROFILE=my-profile opencode
|
||||
|
||||
# Option 3: Using Bedrock bearer token
|
||||
AWS_BEARER_TOKEN_BEDROCK=XXX opencode
|
||||
```
|
||||
|
||||
Or add it to your bash profile.
|
||||
Or add them to your bash profile:
|
||||
|
||||
```bash title="~/.bash_profile"
|
||||
export AWS_ACCESS_KEY_ID=XXX
|
||||
export AWS_PROFILE=my-dev-profile
|
||||
export AWS_REGION=us-east-1
|
||||
```
|
||||
|
||||
1. Run the `/models` command to select the model you want.
|
||||
#### Configuration File (Recommended)
|
||||
|
||||
For project-specific or persistent configuration, use `opencode.json`:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"amazon-bedrock": {
|
||||
"options": {
|
||||
"region": "us-east-1",
|
||||
"profile": "my-aws-profile"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available options:**
|
||||
- `region` - AWS region (e.g., `us-east-1`, `eu-west-1`)
|
||||
- `profile` - AWS named profile from `~/.aws/credentials`
|
||||
- `endpoint` - Custom endpoint URL for VPC endpoints (alias for generic `baseURL` option)
|
||||
|
||||
:::tip
|
||||
Configuration file options take precedence over environment variables.
|
||||
:::
|
||||
|
||||
#### Advanced: VPC Endpoints
|
||||
|
||||
If you're using VPC endpoints for Bedrock:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"amazon-bedrock": {
|
||||
"options": {
|
||||
"region": "us-east-1",
|
||||
"profile": "production",
|
||||
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The `endpoint` option is an alias for the generic `baseURL` option, using AWS-specific terminology. If both `endpoint` and `baseURL` are specified, `endpoint` takes precedence.
|
||||
:::
|
||||
|
||||
#### Authentication Methods
|
||||
- **`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`**: Create an IAM user and generate access keys in the AWS Console
|
||||
- **`AWS_PROFILE`**: Use named profiles from `~/.aws/credentials`. First configure with `aws configure --profile my-profile` or `aws sso login`
|
||||
- **`AWS_BEARER_TOKEN_BEDROCK`**: Generate long-term API keys from the Amazon Bedrock console
|
||||
|
||||
#### Authentication Precedence
|
||||
|
||||
Amazon Bedrock uses the following authentication priority:
|
||||
1. **Bearer Token** - `AWS_BEARER_TOKEN_BEDROCK` environment variable or token from `/connect` command
|
||||
2. **AWS Credential Chain** - Profile, access keys, shared credentials, IAM roles, instance metadata
|
||||
|
||||
:::note
|
||||
When a bearer token is set (via `/connect` or `AWS_BEARER_TOKEN_BEDROCK`), it takes precedence over all AWS credential methods including configured profiles.
|
||||
:::
|
||||
|
||||
3. Run the `/models` command to select the model you want.
|
||||
|
||||
```txt
|
||||
/models
|
||||
|
|
@ -157,7 +225,7 @@ We recommend signing up for [Claude Pro](https://www.anthropic.com/news/claude-p
|
|||
└
|
||||
```
|
||||
|
||||
3. Now all the the Anthropic models should be available when you use the `/models` command.
|
||||
3. Now all the Anthropic models should be available when you use the `/models` command.
|
||||
|
||||
```txt
|
||||
/models
|
||||
|
|
@ -869,6 +937,33 @@ To use Kimi K2 from Moonshot AI:
|
|||
|
||||
---
|
||||
|
||||
### MiniMax
|
||||
|
||||
1. Head over to the [MiniMax API Console](https://platform.minimax.io/login), create an account, and generate an API key.
|
||||
|
||||
2. Run the `/connect` command and search for **MiniMax**.
|
||||
|
||||
```txt
|
||||
/connect
|
||||
```
|
||||
|
||||
3. Enter your MiniMax API key.
|
||||
|
||||
```txt
|
||||
┌ API key
|
||||
│
|
||||
│
|
||||
└ enter
|
||||
```
|
||||
|
||||
4. Run the `/models` command to select a model like _M2.1_.
|
||||
|
||||
```txt
|
||||
/models
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Nebius Token Factory
|
||||
|
||||
1. Head over to the [Nebius Token Factory console](https://tokenfactory.nebius.com/), create an account, and click **Add Key**.
|
||||
|
|
@ -975,29 +1070,35 @@ To use Ollama Cloud with OpenCode:
|
|||
|
||||
### OpenAI
|
||||
|
||||
1. Head over to the [OpenAI Platform console](https://platform.openai.com/api-keys), click **Create new secret key**, and copy the key.
|
||||
We recommend signing up for [ChatGPT Plus or Pro](https://chatgpt.com/pricing).
|
||||
|
||||
2. Run the `/connect` command and search for OpenAI.
|
||||
1. Once you've signed up, run the `/connect` command and select OpenAI.
|
||||
|
||||
```txt
|
||||
/connect
|
||||
```
|
||||
|
||||
3. Enter the API key for the provider.
|
||||
2. Here you can select the **ChatGPT Plus/Pro** option and it'll open your browser
|
||||
and ask you to authenticate.
|
||||
|
||||
```txt
|
||||
┌ API key
|
||||
┌ Select auth method
|
||||
│
|
||||
│
|
||||
└ enter
|
||||
│ ChatGPT Plus/Pro
|
||||
│ Manually enter API Key
|
||||
└
|
||||
```
|
||||
|
||||
4. Run the `/models` command to select the one you want.
|
||||
3. Now all the OpenAI models should be available when you use the `/models` command.
|
||||
|
||||
```txt
|
||||
/models
|
||||
```
|
||||
|
||||
##### Using API keys
|
||||
|
||||
If you already have an API key, you can select **Manually enter API Key** and paste it in your terminal.
|
||||
|
||||
---
|
||||
|
||||
### OpenCode Zen
|
||||
|
|
@ -1175,6 +1276,35 @@ SAP AI Core provides access to 40+ models from OpenAI, Anthropic, Google, Amazon
|
|||
|
||||
---
|
||||
|
||||
### Scaleway
|
||||
|
||||
To use [Scaleway Generative APIs](https://www.scaleway.com/en/docs/generative-apis/) with Opencode:
|
||||
|
||||
1. Head over to the [Scaleway Console IAM settings](https://console.scaleway.com/iam/api-keys) to generate a new API key.
|
||||
|
||||
2. Run the `/connect` command and search for **Scaleway**.
|
||||
|
||||
```txt
|
||||
/connect
|
||||
```
|
||||
|
||||
3. Enter your Scaleway API key.
|
||||
|
||||
```txt
|
||||
┌ API key
|
||||
│
|
||||
│
|
||||
└ enter
|
||||
```
|
||||
|
||||
4. Run the `/models` command to select a model like _devstral-2-123b-instruct-2512_ or _gpt-oss-120b_.
|
||||
|
||||
```txt
|
||||
/models
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Together AI
|
||||
|
||||
1. Head over to the [Together AI console](https://api.together.ai), create an account, and click **Add Key**.
|
||||
|
|
@ -1229,6 +1359,62 @@ SAP AI Core provides access to 40+ models from OpenAI, Anthropic, Google, Amazon
|
|||
|
||||
---
|
||||
|
||||
### Vercel AI Gateway
|
||||
|
||||
Vercel AI Gateway lets you access models from OpenAI, Anthropic, Google, xAI, and more through a unified endpoint. Models are offered at list price with no markup.
|
||||
|
||||
1. Head over to the [Vercel dashboard](https://vercel.com/), navigate to the **AI Gateway** tab, and click **API keys** to create a new API key.
|
||||
|
||||
2. Run the `/connect` command and search for **Vercel AI Gateway**.
|
||||
|
||||
```txt
|
||||
/connect
|
||||
```
|
||||
|
||||
3. Enter your Vercel AI Gateway API key.
|
||||
|
||||
```txt
|
||||
┌ API key
|
||||
│
|
||||
│
|
||||
└ enter
|
||||
```
|
||||
|
||||
4. Run the `/models` command to select a model.
|
||||
|
||||
```txt
|
||||
/models
|
||||
```
|
||||
|
||||
You can also customize models through your opencode config. Here's an example of specifying provider routing order.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"vercel": {
|
||||
"models": {
|
||||
"anthropic/claude-sonnet-4": {
|
||||
"options": {
|
||||
"order": ["anthropic", "vertex"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Some useful routing options:
|
||||
|
||||
| Option | Description |
|
||||
| ------------------- | ---------------------------------------------------- |
|
||||
| `order` | Provider sequence to try |
|
||||
| `only` | Restrict to specific providers |
|
||||
| `zeroDataRetention` | Only use providers with zero data retention policies |
|
||||
|
||||
---
|
||||
|
||||
### xAI
|
||||
|
||||
1. Head over to the [xAI console](https://console.x.ai/), create an account, and generate an API key.
|
||||
|
|
@ -1277,7 +1463,7 @@ SAP AI Core provides access to 40+ models from OpenAI, Anthropic, Google, Amazon
|
|||
└ enter
|
||||
```
|
||||
|
||||
4. Run the `/models` command to select a model like _GLM-4.5_.
|
||||
4. Run the `/models` command to select a model like _GLM-4.7_.
|
||||
|
||||
```txt
|
||||
/models
|
||||
|
|
|
|||
|
|
@ -92,6 +92,17 @@ Example:
|
|||
}
|
||||
```
|
||||
|
||||
You can also use remote URLs to load instructions from the web.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
|
||||
}
|
||||
```
|
||||
|
||||
Remote instructions are fetched with a 5 second timeout.
|
||||
|
||||
All instruction files are combined with your `AGENTS.md` files.
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -355,13 +355,19 @@ await client.session.prompt({
|
|||
|
||||
### Files
|
||||
|
||||
| Method | Description | Response |
|
||||
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `find.text({ query })` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
||||
| `find.files({ query })` | Find files by name | `string[]` (file paths) |
|
||||
| `find.symbols({ query })` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
|
||||
| `file.read({ query })` | Read a file | `{ type: "raw" \| "patch", content: string }` |
|
||||
| `file.status({ query? })` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
||||
| Method | Description | Response |
|
||||
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `find.text({ query })` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
||||
| `find.files({ query })` | Find files and directories by name | `string[]` (paths) |
|
||||
| `find.symbols({ query })` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
|
||||
| `file.read({ query })` | Read a file | `{ type: "raw" \| "patch", content: string }` |
|
||||
| `file.status({ query? })` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
||||
|
||||
`find.files` supports a few optional query fields:
|
||||
|
||||
- `type`: `"file"` or `"directory"`
|
||||
- `directory`: override the project root for the search
|
||||
- `limit`: max results (1–200)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -374,7 +380,11 @@ const textResults = await client.find.text({
|
|||
})
|
||||
|
||||
const files = await client.find.files({
|
||||
query: { query: "*.ts" },
|
||||
query: { query: "*.ts", type: "file" },
|
||||
})
|
||||
|
||||
const directories = await client.find.files({
|
||||
query: { query: "packages", type: "directory", limit: 20 },
|
||||
})
|
||||
|
||||
const content = await client.file.read({
|
||||
|
|
|
|||
|
|
@ -13,15 +13,33 @@ The `opencode serve` command runs a headless HTTP server that exposes an OpenAPI
|
|||
### Usage
|
||||
|
||||
```bash
|
||||
opencode serve [--port <number>] [--hostname <string>]
|
||||
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
| Flag | Short | Description | Default |
|
||||
| ------------ | ----- | --------------------- | ----------- |
|
||||
| `--port` | `-p` | Port to listen on | `4096` |
|
||||
| `--hostname` | `-h` | Hostname to listen on | `127.0.0.1` |
|
||||
| Flag | Description | Default |
|
||||
| ------------ | ----------------------------------- | ----------- |
|
||||
| `--port` | Port to listen on | `4096` |
|
||||
| `--hostname` | Hostname to listen on | `127.0.0.1` |
|
||||
| `--mdns` | Enable mDNS discovery | `false` |
|
||||
| `--cors` | Additional browser origins to allow | `[]` |
|
||||
|
||||
`--cors` can be passed multiple times:
|
||||
|
||||
```bash
|
||||
opencode serve --cors http://localhost:5173 --cors https://app.example.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Authentication
|
||||
|
||||
Set `OPENCODE_SERVER_PASSWORD` to protect the server with HTTP basic auth. The username defaults to `opencode`, or set `OPENCODE_SERVER_USERNAME` to override it. This applies to both `opencode serve` and `opencode web`.
|
||||
|
||||
```bash
|
||||
OPENCODE_SERVER_PASSWORD=your-password opencode serve
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -172,14 +190,22 @@ The opencode server exposes the following APIs.
|
|||
|
||||
### Files
|
||||
|
||||
| Method | Path | Description | Response |
|
||||
| ------ | ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `GET` | `/find?pattern=<pat>` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
||||
| `GET` | `/find/file?query=<q>` | Find files by name | `string[]` (file paths) |
|
||||
| `GET` | `/find/symbol?query=<q>` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
|
||||
| `GET` | `/file?path=<path>` | List files and directories | <a href={typesUrl}><code>FileNode[]</code></a> |
|
||||
| `GET` | `/file/content?path=<p>` | Read a file | <a href={typesUrl}><code>FileContent</code></a> |
|
||||
| `GET` | `/file/status` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
||||
| Method | Path | Description | Response |
|
||||
| ------ | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `GET` | `/find?pattern=<pat>` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
||||
| `GET` | `/find/file?query=<q>` | Find files and directories by name | `string[]` (paths) |
|
||||
| `GET` | `/find/symbol?query=<q>` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
|
||||
| `GET` | `/file?path=<path>` | List files and directories | <a href={typesUrl}><code>FileNode[]</code></a> |
|
||||
| `GET` | `/file/content?path=<p>` | Read a file | <a href={typesUrl}><code>FileContent</code></a> |
|
||||
| `GET` | `/file/status` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
||||
|
||||
#### `/find/file` query parameters
|
||||
|
||||
- `query` (required) — search string (fuzzy match)
|
||||
- `type` (optional) — limit results to `"file"` or `"directory"`
|
||||
- `directory` (optional) — override the project root for the search
|
||||
- `limit` (optional) — max results (1–200)
|
||||
- `dirs` (optional) — legacy flag (`"false"` returns only files)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -14,8 +14,9 @@ Create one folder per skill name and put a `SKILL.md` inside it.
|
|||
OpenCode searches these locations:
|
||||
|
||||
- Project config: `.opencode/skill/<name>/SKILL.md`
|
||||
- Global config: `~/.opencode/skill/<name>/SKILL.md`
|
||||
- Claude-compatible: `.claude/skills/<name>/SKILL.md`
|
||||
- Global config: `~/.config/opencode/skill/<name>/SKILL.md`
|
||||
- Project Claude-compatible: `.claude/skills/<name>/SKILL.md`
|
||||
- Global Claude-compatible: `~/.claude/skills/<name>/SKILL.md`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -24,7 +25,7 @@ OpenCode searches these locations:
|
|||
For project-local paths, OpenCode walks up from your current working directory until it reaches the git worktree.
|
||||
It loads any matching `skill/*/SKILL.md` in `.opencode/` and any matching `.claude/skills/*/SKILL.md` along the way.
|
||||
|
||||
Global definitions are also loaded from `~/.opencode/skill/*/SKILL.md`.
|
||||
Global definitions are also loaded from `~/.config/opencode/skill/*/SKILL.md` and `~/.claude/skills/*/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -127,10 +128,10 @@ Control which skills agents can access using pattern-based permissions in `openc
|
|||
{
|
||||
"permission": {
|
||||
"skill": {
|
||||
"*": "allow",
|
||||
"pr-review": "allow",
|
||||
"internal-*": "deny",
|
||||
"experimental-*": "ask",
|
||||
"*": "allow"
|
||||
"experimental-*": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -5,86 +5,37 @@ description: Manage the tools an LLM can use.
|
|||
|
||||
Tools allow the LLM to perform actions in your codebase. OpenCode comes with a set of built-in tools, but you can extend it with [custom tools](/docs/custom-tools) or [MCP servers](/docs/mcp-servers).
|
||||
|
||||
By default, all tools are **enabled** and don't need permission to run. But you can configure this and control the [permissions](/docs/permissions) through your config.
|
||||
By default, all tools are **enabled** and don't need permission to run. You can control tool behavior through [permissions](/docs/permissions).
|
||||
|
||||
---
|
||||
|
||||
## Configure
|
||||
|
||||
You can configure tools globally or per agent. Agent-specific configs override global settings.
|
||||
|
||||
By default, all tools are set to `true`. To disable a tool, set it to `false`.
|
||||
|
||||
---
|
||||
|
||||
### Global
|
||||
|
||||
Disable or enable tools globally using the `tools` option.
|
||||
Use the `permission` field to control tool behavior. You can allow, deny, or require approval for each tool.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"bash": false,
|
||||
"webfetch": true
|
||||
"permission": {
|
||||
"edit": "deny",
|
||||
"bash": "ask",
|
||||
"webfetch": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also use wildcards to control multiple tools at once. For example, to disable all tools from an MCP server:
|
||||
You can also use wildcards to control multiple tools at once. For example, to require approval for all tools from an MCP server:
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"mymcp_*": false
|
||||
"permission": {
|
||||
"mymcp_*": "ask"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Per agent
|
||||
|
||||
Override global tool settings for specific agents using the `tools` config in the agent definition.
|
||||
|
||||
```json title="opencode.json" {3-6,9-12}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"write": true,
|
||||
"bash": true
|
||||
},
|
||||
"agent": {
|
||||
"plan": {
|
||||
"tools": {
|
||||
"write": false,
|
||||
"bash": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For example, here the `plan` agent overrides the global config to disable `write` and `bash` tools.
|
||||
|
||||
You can also configure tools for agents in Markdown.
|
||||
|
||||
```markdown title="~/.config/opencode/agent/readonly.md"
|
||||
---
|
||||
description: Read-only analysis agent
|
||||
mode: subagent
|
||||
tools:
|
||||
write: false
|
||||
edit: false
|
||||
bash: false
|
||||
---
|
||||
|
||||
Analyze code without making any modifications.
|
||||
```
|
||||
|
||||
[Learn more](/docs/agents#tools) about configuring tools per agent.
|
||||
[Learn more](/docs/permissions) about configuring permissions.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -101,8 +52,8 @@ Execute shell commands in your project environment.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"bash": true
|
||||
"permission": {
|
||||
"bash": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -118,8 +69,8 @@ Modify existing files using exact string replacements.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"edit": true
|
||||
"permission": {
|
||||
"edit": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -135,14 +86,18 @@ Create new files or overwrite existing ones.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"write": true
|
||||
"permission": {
|
||||
"edit": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use this to allow the LLM to create new files. It will overwrite existing files if they already exist.
|
||||
|
||||
:::note
|
||||
The `write` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`).
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### read
|
||||
|
|
@ -152,8 +107,8 @@ Read file contents from your codebase.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"read": true
|
||||
"permission": {
|
||||
"read": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -169,8 +124,8 @@ Search file contents using regular expressions.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"grep": true
|
||||
"permission": {
|
||||
"grep": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -186,8 +141,8 @@ Find files by pattern matching.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"glob": true
|
||||
"permission": {
|
||||
"glob": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -203,8 +158,8 @@ List files and directories in a given path.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"list": true
|
||||
"permission": {
|
||||
"list": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -224,8 +179,8 @@ This tool is only available when `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (or `OPEN
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"lsp": true
|
||||
"permission": {
|
||||
"lsp": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -243,14 +198,18 @@ Apply patches to files.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"patch": true
|
||||
"permission": {
|
||||
"edit": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This tool applies patch files to your codebase. Useful for applying diffs and patches from various sources.
|
||||
|
||||
:::note
|
||||
The `patch` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`).
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### skill
|
||||
|
|
@ -260,14 +219,12 @@ Load a [skill](/docs/skills) (a `SKILL.md` file) and return its content in the c
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"skill": true
|
||||
"permission": {
|
||||
"skill": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can control approval prompts for loading skills via [permissions](/docs/permissions) using `permission.skill`.
|
||||
|
||||
---
|
||||
|
||||
### todowrite
|
||||
|
|
@ -277,8 +234,8 @@ Manage todo lists during coding sessions.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"todowrite": true
|
||||
"permission": {
|
||||
"todowrite": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -286,7 +243,7 @@ Manage todo lists during coding sessions.
|
|||
Creates and updates task lists to track progress during complex operations. The LLM uses this to organize multi-step tasks.
|
||||
|
||||
:::note
|
||||
This tool is disabled for subagents by default, but you can enable it manually. [Learn more](/docs/agents/#tools)
|
||||
This tool is disabled for subagents by default, but you can enable it manually. [Learn more](/docs/agents/#permissions)
|
||||
:::
|
||||
|
||||
---
|
||||
|
|
@ -298,8 +255,8 @@ Read existing todo lists.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"todoread": true
|
||||
"permission": {
|
||||
"todoread": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -307,7 +264,7 @@ Read existing todo lists.
|
|||
Reads the current todo list state. Used by the LLM to track what tasks are pending or completed.
|
||||
|
||||
:::note
|
||||
This tool is disabled for subagents by default, but you can enable it manually. [Learn more](/docs/agents/#tools)
|
||||
This tool is disabled for subagents by default, but you can enable it manually. [Learn more](/docs/agents/#permissions)
|
||||
:::
|
||||
|
||||
---
|
||||
|
|
@ -319,8 +276,8 @@ Fetch web content.
|
|||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"tools": {
|
||||
"webfetch": true
|
||||
"permission": {
|
||||
"webfetch": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -329,6 +286,30 @@ Allows the LLM to fetch and read web pages. Useful for looking up documentation
|
|||
|
||||
---
|
||||
|
||||
### question
|
||||
|
||||
Ask the user questions during execution.
|
||||
|
||||
```json title="opencode.json" {4}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"question": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This tool allows the LLM to ask the user questions during a task. It's useful for:
|
||||
|
||||
- Gathering user preferences or requirements
|
||||
- Clarifying ambiguous instructions
|
||||
- Getting decisions on implementation choices
|
||||
- Offering choices about what direction to take
|
||||
|
||||
Each question includes a header, the question text, and a list of options. Users can select from the provided options or type a custom answer. When there are multiple questions, users can navigate between them before submitting all answers.
|
||||
|
||||
---
|
||||
|
||||
## Custom tools
|
||||
|
||||
Custom tools let you define your own functions that the LLM can call. These are defined in your config file and can execute arbitrary code.
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ If you're experiencing issues with OpenCode:
|
|||
|
||||
The best way to report bugs or request features is through our GitHub repository:
|
||||
|
||||
[**github.com/sst/opencode/issues**](https://github.com/sst/opencode/issues)
|
||||
[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)
|
||||
|
||||
Before creating a new issue, search existing issues to see if your problem has already been reported.
|
||||
|
||||
|
|
|
|||
|
|
@ -235,7 +235,7 @@ Share current session. [Learn more](/docs/share).
|
|||
List available themes.
|
||||
|
||||
```bash frame="none"
|
||||
/themes
|
||||
/theme
|
||||
```
|
||||
|
||||
**Keybind:** `ctrl+x t`
|
||||
|
|
@ -358,15 +358,17 @@ You can customize TUI behavior through your OpenCode config file.
|
|||
### Options
|
||||
|
||||
- `scroll_acceleration` - 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: `1`). Defaults to `1` on Unix and `3` on Windows. **Note: This is ignored if `scroll_acceleration.enabled` is set to `true`.**
|
||||
- `scroll_speed` - Controls how fast the TUI scrolls when using scroll commands (minimum: `1`). Defaults to `3`. **Note: This is ignored if `scroll_acceleration.enabled` is set to `true`.**
|
||||
|
||||
---
|
||||
|
||||
## View customization
|
||||
## Customization
|
||||
|
||||
You can customize various aspects of the TUI view using the command palette (`ctrl+x h` or `/help`). These settings persist across restarts.
|
||||
|
||||
### Username display
|
||||
---
|
||||
|
||||
#### Username display
|
||||
|
||||
Toggle whether your username appears in chat messages. Access this through:
|
||||
|
||||
|
|
|
|||
|
|
@ -62,30 +62,32 @@ You are charged per request and you can add credits to your account.
|
|||
|
||||
You can also access our models through the following API endpoints.
|
||||
|
||||
| Model | Model ID | Endpoint | AI SDK Package |
|
||||
| ----------------- | ----------------- | -------------------------------------------------- | --------------------------- |
|
||||
| GPT 5.2 | gpt-5.2 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 | gpt-5.1 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex | gpt-5.1-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex Max | gpt-5.1-codex-max | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 | gpt-5 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 Codex | gpt-5-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 Nano | gpt-5-nano | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| Claude Sonnet 4.5 | claude-sonnet-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Sonnet 4 | claude-sonnet-4 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Haiku 4.5 | claude-haiku-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Haiku 3.5 | claude-3-5-haiku | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.5 | claude-opus-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.1 | claude-opus-4-1 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| GLM 4.7 | glm-4.7-free | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Gemini 3 Pro | gemini-3-pro | `https://opencode.ai/zen/v1/models/gemini-3-pro` | `@ai-sdk/google` |
|
||||
| Gemini 3 Flash | gemini-3-flash | `https://opencode.ai/zen/v1/models/gemini-3-flash` | `@ai-sdk/google` |
|
||||
| GLM 4.6 | glm-4.6 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Kimi K2 | kimi-k2 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Kimi K2 Thinking | kimi-k2-thinking | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Qwen3 Coder 480B | qwen3-coder | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Grok Code Fast 1 | grok-code | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Big Pickle | big-pickle | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Model | Model ID | Endpoint | AI SDK Package |
|
||||
| ------------------ | ------------------ | -------------------------------------------------- | --------------------------- |
|
||||
| GPT 5.2 | gpt-5.2 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 | gpt-5.1 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex | gpt-5.1-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex Max | gpt-5.1-codex-max | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5.1 Codex Mini | gpt-5.1-codex-mini | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 | gpt-5 | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 Codex | gpt-5-codex | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| GPT 5 Nano | gpt-5-nano | `https://opencode.ai/zen/v1/responses` | `@ai-sdk/openai` |
|
||||
| Claude Sonnet 4.5 | claude-sonnet-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Sonnet 4 | claude-sonnet-4 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Haiku 4.5 | claude-haiku-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Haiku 3.5 | claude-3-5-haiku | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.5 | claude-opus-4-5 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Claude Opus 4.1 | claude-opus-4-1 | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| MiniMax M2.1 | minimax-m2.1-free | `https://opencode.ai/zen/v1/messages` | `@ai-sdk/anthropic` |
|
||||
| Gemini 3 Pro | gemini-3-pro | `https://opencode.ai/zen/v1/models/gemini-3-pro` | `@ai-sdk/google` |
|
||||
| Gemini 3 Flash | gemini-3-flash | `https://opencode.ai/zen/v1/models/gemini-3-flash` | `@ai-sdk/google` |
|
||||
| GLM 4.6 | glm-4.6 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| GLM 4.7 | glm-4.7-free | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Kimi K2 | kimi-k2 | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Kimi K2 Thinking | kimi-k2-thinking | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Qwen3 Coder 480B | qwen3-coder | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Grok Code Fast 1 | grok-code | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
| Big Pickle | big-pickle | `https://opencode.ai/zen/v1/chat/completions` | `@ai-sdk/openai-compatible` |
|
||||
|
||||
The [model id](/docs/config/#models) in your OpenCode config
|
||||
uses the format `opencode/<model-id>`. For example, for GPT 5.1 Codex, you would
|
||||
|
|
@ -111,6 +113,7 @@ We support a pay-as-you-go model. Below are the prices **per 1M tokens**.
|
|||
| --------------------------------- | ------ | ------ | ----------- | ------------ |
|
||||
| Big Pickle | Free | Free | Free | - |
|
||||
| Grok Code Fast 1 | Free | Free | Free | - |
|
||||
| MiniMax M2.1 | Free | Free | Free | - |
|
||||
| GLM 4.7 | Free | Free | Free | - |
|
||||
| GLM 4.6 | $0.60 | $2.20 | $0.10 | - |
|
||||
| Kimi K2 | $0.40 | $2.50 | - | - |
|
||||
|
|
@ -131,6 +134,7 @@ We support a pay-as-you-go model. Below are the prices **per 1M tokens**.
|
|||
| GPT 5.1 | $1.07 | $8.50 | $0.107 | - |
|
||||
| GPT 5.1 Codex | $1.07 | $8.50 | $0.107 | - |
|
||||
| GPT 5.1 Codex Max | $1.25 | $10.00 | $0.125 | - |
|
||||
| GPT 5.1 Codex Mini | $0.25 | $2.00 | $0.025 | - |
|
||||
| GPT 5 | $1.07 | $8.50 | $0.107 | - |
|
||||
| GPT 5 Codex | $1.07 | $8.50 | $0.107 | - |
|
||||
| GPT 5 Nano | Free | Free | Free | - |
|
||||
|
|
@ -138,25 +142,46 @@ 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](/docs/config/#models) that's used to generate the titles of your sessions.
|
||||
|
||||
:::note
|
||||
Credit card fees are passed along at cost; we don't charge anything beyond that.
|
||||
Credit card fees are passed along at cost (4.4% + $0.30 per transaction); we don't charge anything beyond that.
|
||||
:::
|
||||
|
||||
The free models:
|
||||
|
||||
- Grok Code Fast 1 is currently free on OpenCode for a limited time. The xAI team is using this time to collect feedback and improve Grok Code.
|
||||
- GLM 4.7 is currently free on OpenCode for a limited time. The team is using this time to collect feedback and improve the model.
|
||||
- MiniMax M2.1 is currently free 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.
|
||||
|
||||
<a href={email}>Contact us</a> 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.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
- Grok Code Fast 1: During its free period, collected data may be used to improve Grok Code.
|
||||
- GLM 4.7: During its free period, collected data may be used to improve the model.
|
||||
- MiniMax M2.1: During its free period, collected data may be used to improve the model.
|
||||
- Big Pickle: During its free period, collected data may be used to improve the model.
|
||||
- OpenAI APIs: Requests are retained for 30 days in accordance with [OpenAI's Data Policies](https://platform.openai.com/docs/guides/your-data).
|
||||
- Anthropic APIs: Requests are retained for 30 days in accordance with [Anthropic's Data Policies](https://docs.anthropic.com/en/docs/claude-code/data-usage).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue