diff --git a/packages/web/src/content/docs/docs/agents.mdx b/packages/web/src/content/docs/docs/agents.mdx
index 950f910fd..beb1b29ae 100644
--- a/packages/web/src/content/docs/docs/agents.mdx
+++ b/packages/web/src/content/docs/docs/agents.mdx
@@ -1,6 +1,6 @@
---
title: Agents
-description: Configure and use specialized agents in opencode.
+description: Configure and use specialized agents.
---
Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
@@ -9,69 +9,96 @@ Agents are specialized AI assistants that can be configured for specific tasks a
Use the plan agent to analyze code and review suggestions without making any code changes.
:::
-You can switch between agents during a session or configure them in your config file.
+You can switch between agents during a session or invoke them with the `@` mention.
---
-## Agent Types
+## Types
-opencode has two types of agents:
+There are two types of agents in opencode; primary agents and subagents.
-### Primary Agents
+---
-Primary agents are the main assistants you interact with directly. You can cycle through them using the **Tab** key (or your configured `switch_agent` keybind). These agents handle your main conversation and can access all configured tools.
+### Primary agents
-**Built-in Primary Agents:**
+Primary agents are the main assistants you interact with directly. You can cycle through them using the **Tab** key, or your configured `switch_agent` keybind. These agents handle your main conversation and can access all configured tools.
-- **Build** - The default agent with all tools enabled. Standard for development work where you need full access to file operations and system commands.
-- **Plan** - A restricted agent for planning and analysis. Has `write`, `edit`, `patch`, and `bash` tools disabled by default. Useful for analyzing code and suggesting changes without making modifications.
+:::tip
+You can use the **Tab** key to switch between primary agents during a session.
+:::
+
+opencode comes with two built-in primary agents, **Build** and **Plan**. We'll
+look at these below.
+
+---
### Subagents
-Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages (e.g., `@general help me search for this function`).
+Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages.
-**Built-in Subagents:**
-
-- **General** - General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when searching for keywords or files and you're not confident you'll find the right match in the first few tries.
+opencode comes with one built-in subagent, **General**. We'll look at this below.
---
-## Using Agents
+## Built-in
-### Switching Primary Agents
-
-Use the **Tab** key to cycle through available primary agents during a session. You can also use your configured `switch_agent` keybind.
-
-### Invoking Subagents
-
-- **Automatic**: Primary agents will automatically use subagents for specialized tasks based on their descriptions
-- **Manual**: @ mention a subagent in your message: `@general search for authentication code`
-
-See also: [Formatters](/docs/formatters) for information about code formatting configuration.
+opencode comes with two built-in primary agents and one built-in subagent.
---
-## Creating Agents
+### Build
-You can create new agents using the `opencode agent create` command. This interactive command will:
+_Mode_: `primary`
-1. Ask where to save the agent (global or project-specific)
-2. Prompt for a description of what the agent should do
-3. Generate an appropriate system prompt and identifier
-4. Let you select which tools the agent can access
-5. Create a markdown file with the agent configuration
+Build is the **default** primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands.
-```bash
-opencode agent create
-```
+---
-The command will guide you through the process and automatically generate a well-structured agent based on your requirements.
+### Plan
-## Configuration
+_Mode_: `primary`
+
+A restricted agent designed for planning and analysis. In the plan agent, the following tools are disabled by default:
+
+- `write` - Cannot create new files
+- `edit` - Cannot modify existing files
+- `patch` - Cannot apply patches
+- `bash` - Cannot execute shell commands
+
+This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
+
+---
+
+### General
+
+_Mode_: `subagent`
+
+A general-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when searching for keywords or files and you're not confident you'll find the right match in the first few tries.
+
+---
+
+## Usage
+
+1. For primary agents, use the **Tab** key to cycle through them during a session. You can also use your configured `switch_agent` keybind.
+
+2. Subagents can be invoked:
+
+ - **Automatically** by primary agents for specialized tasks based on their descriptions.
+ - Manually by **@ mentioning** a subagent in your message. For example.
+
+ ```txt frame="none"
+ @general help me search for this function
+ ```
+
+---
+
+## Configure
You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:
-### JSON Configuration
+---
+
+### JSON
Configure agents in your `opencode.json` config file:
@@ -112,12 +139,14 @@ Configure agents in your `opencode.json` config file:
}
```
-### Markdown Configuration
+---
+
+### Markdown
You can also define agents using markdown files. Place them in:
- Global: `~/.config/opencode/agent/`
-- Project: `.opencode/agent/`
+- Per-project: `.opencode/agent/`
```markdown title="~/.config/opencode/agent/review.md"
---
@@ -141,31 +170,41 @@ You are in code review mode. Focus on:
Provide constructive feedback without making direct changes.
```
-The markdown file name becomes the agent name (e.g., `review.md` creates a `review` agent).
+The markdown file name becomes the agent name. For example, `review.md` creates a `review` agent.
Let's look at these configuration options in detail.
---
-### Model
+## Options
-Use the `model` config to override the default model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
+Let's look at these configuration options in detail.
+
+---
+
+### Description
+
+Use the `description` option to provide a brief description of what the agent does and when to use it.
```json title="opencode.json"
{
"agent": {
- "plan": {
- "model": "anthropic/claude-haiku-4-20250514"
+ "review": {
+ "description": "Reviews code for best practices and potential issues"
}
}
}
```
+This is a **required** config option.
+
---
### Temperature
-Control the randomness and creativity of the AI's responses with the `temperature` config. Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
+Control the randomness and creativity of the LLM's responses with the `temperature` config.
+
+Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
```json title="opencode.json"
{
@@ -204,7 +243,23 @@ Temperature values typically range from 0.0 to 1.0:
}
```
-If no temperature is specified, opencode uses model-specific defaults (typically 0 for most models, 0.55 for Qwen models).
+If no temperature is specified, opencode uses model-specific defaults; typically 0 for most models, 0.55 for Qwen models.
+
+---
+
+### Disable
+
+Set to `true` to disable the agent.
+
+```json title="opencode.json"
+{
+ "agent": {
+ "review": {
+ "disable": true
+ }
+ }
+}
+```
---
@@ -226,26 +281,27 @@ This path is relative to where the config file is located. So this works for bot
---
-## Agent Properties
+### Model
-### Required
+Use the `model` config to override the default model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
-- **description** - Brief description of what the agent does and when to use it
+```json title="opencode.json"
+{
+ "agent": {
+ "plan": {
+ "model": "anthropic/claude-haiku-4-20250514"
+ }
+ }
+}
+```
-### Optional
-
-- **model** - Specific model to use (defaults to your configured model)
-- **prompt** - Custom system prompt for the agent
-- **tools** - Object specifying which tools the agent can access (true/false for each tool)
-- **temperature** - Control response randomness (0.0-1.0)
-- **mode** - Agent type: `"primary"` (can be cycled with Tab), `"subagent"` (invoked by @ mention), or `"all"` (both)
-- **disable** - Set to true to disable the agent
+---
### Tools
Control which tools are available in this agent with the `tools` config. You can enable or disable specific tools by setting them to `true` or `false`.
-```json
+```json title="opencode.json"
{
"agent": {
"readonly": {
@@ -262,6 +318,22 @@ Control which tools are available in this agent with the `tools` config. You can
}
```
+You can also use wildcards to control multiple tools at once. For example, to disable all tools from an MCP server:
+
+```json title="opencode.json"
+{
+ "agent": {
+ "readonly": {
+ "tools": {
+ "mymcp_*": false,
+ "write": false,
+ "edit": false
+ }
+ }
+ }
+}
+```
+
If no tools are specified, all tools are enabled by default.
---
@@ -286,104 +358,207 @@ Here are all the tools can be controlled through the agent config.
---
-## Tool Access
+### Permissions
-By default, agents inherit the same tool access as the main assistant. You can restrict or enable specific tools as shown in the Tools section above.
+Permissions control what actions an agent can take.
-## Agent Modes
+- edit, bash, webfetch
-The `mode` property determines how an agent can be used:
+Each permission can be set to allow, ask, or deny.
-- **`"primary"`** - Can be cycled through with Tab key as your main assistant
-- **`"subagent"`** - Can be invoked by @ mentioning or automatically by primary agents
-- **`"all"`** - Can be used both as primary and subagent (default for custom agents)
+- allow, ask, deny
-## Best Practices
+Configure permissions globally in opencode.json.
-1. **Clear descriptions** - Write specific descriptions that help the main assistant know when to use each agent
-2. **Focused prompts** - Keep agent prompts focused on their specific role
-3. **Appropriate tool access** - Only give agents the tools they need for their tasks
-4. **Consistent naming** - Use descriptive, consistent names for your agents
-5. **Project-specific agents** - Use `.opencode/agent/` for project-specific workflows
+```json title="opencode.json"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "permission": {
+ "edit": "ask",
+ "bash": "allow",
+ "webfetch": "deny"
+ }
+}
+```
-## Custom Agents
+You can override permissions per agent in JSON.
-You can create your own custom agents by adding them to the configuration. Here are examples using both approaches:
-
-### Using JSON configuration
-
-```json title="opencode.json" {4-14}
+```json title="opencode.json" {7-18}
{
"$schema": "https://opencode.ai/config.json",
"agent": {
- "docs": {
- "prompt": "{file:./prompts/documentation.txt}",
- "tools": {
- "write": true,
- "edit": true,
- "bash": false,
- "read": true,
- "grep": true,
- "glob": true
+ "build": {
+ "permission": {
+ "edit": "allow",
+ "bash": {
+ "*": "allow",
+ "git push": "ask",
+ "terraform *": "deny"
+ },
+ "webfetch": "ask"
}
}
}
}
```
-### Using markdown files
+You can also set permissions in Markdown agents.
-Create agent files in `.opencode/agent/` for project-specific agents or `~/.config/opencode/agent/` for global agents:
-
-```markdown title=".opencode/agent/debug.md"
+```markdown title="~/.config/opencode/agent/review.md"
---
-temperature: 0.1
-tools:
- bash: true
- read: true
- grep: true
- write: false
- edit: false
+description: Code review without edits
+mode: subagent
+permission:
+ edit: deny
+ bash: ask
+ webfetch: deny
---
-You are in debug mode. Your primary goal is to help investigate and diagnose issues.
-
-Focus on:
-
-- Understanding the problem through careful analysis
-- Using bash commands to inspect system state
-- Reading relevant files and logs
-- Searching for patterns and anomalies
-- Providing clear explanations of findings
-
-Do not make any changes to files. Only investigate and report.
+Only analyze code and suggest changes.
```
-```markdown title="~/.config/opencode/agent/refactor.md"
----
-model: anthropic/claude-sonnet-4-20250514
-temperature: 0.2
-tools:
- edit: true
- read: true
- grep: true
- glob: true
----
+Bash permissions support granular patterns for fine-grained control.
-You are in refactoring mode. Focus on improving code quality without changing functionality.
-
-Priorities:
-
-- Improve code readability and maintainability
-- Apply consistent naming conventions
-- Reduce code duplication
-- Optimize performance where appropriate
-- Ensure all tests continue to pass
+```json title="Allow most, ask for risky, deny terraform"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "permission": {
+ "bash": {
+ "*": "allow",
+ "git push": "ask",
+ "terraform *": "deny"
+ }
+ }
+}
```
+If you provide a granular bash map, the default becomes ask unless you set \* explicitly.
+
+```json title="Granular defaults to ask"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "permission": {
+ "bash": {
+ "git status": "allow"
+ }
+ }
+}
+```
+
+Agent-level permissions merge over global settings.
+
+- Global sets defaults; agent overrides when specified
+
+Specific bash rules can override a global default.
+
+```json title="Global ask, agent allows safe commands"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "permission": { "bash": "ask" },
+ "agent": {
+ "build": {
+ "permission": {
+ "bash": { "git status": "allow", "*": "ask" }
+ }
+ }
+ }
+}
+```
+
+Permissions affect tool availability and prompts differently.
+
+- deny hides tools (edit also hides write/patch); ask prompts; allow runs
+
+For quick reference, here are common setups.
+
+```json title="Read-only reviewer"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "agent": {
+ "review": {
+ "permission": { "edit": "deny", "bash": "deny", "webfetch": "allow" }
+ }
+ }
+}
+```
+
+```json title="Planning agent that can browse but cannot change code"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "agent": {
+ "plan": {
+ "permission": { "edit": "deny", "bash": "deny", "webfetch": "ask" }
+ }
+ }
+}
+```
+
+See the full permissions guide for more patterns.
+
+- /docs/permissions
+
---
-### Use cases
+### Mode
+
+Control the agent's mode with the `mode` config. The `mode` option is used to determine how the agent can be used.
+
+```json title="opencode.json"
+{
+ "agent": {
+ "review": {
+ "mode": "subagent"
+ }
+ }
+}
+```
+
+The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is specified, it defaults to `all`.
+
+---
+
+### 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.
+
+For example, with OpenAI's reasoning models, you can control the reasoning effort:
+
+```json title="opencode.json" {6,7}
+{
+ "agent": {
+ "deep-thinker": {
+ "description": "Agent that uses high reasoning effort for complex problems",
+ "model": "openai/gpt-5-turbo",
+ "reasoningEffort": "high",
+ "textVerbosity": "low"
+ }
+ }
+}
+```
+
+These additional options are model and provider-specific. Check your provider's documentation for available parameters.
+
+---
+
+## Create agents
+
+You can create new agents using the following command:
+
+```bash
+opencode agent create
+```
+
+This interactive command will:
+
+1. Ask where to save the agent; global or project-specific.
+2. Description of what the agent should do.
+3. Generate an appropriate system prompt and identifier.
+4. Let you select which tools the agent can access.
+5. Finally, create a markdown file with the agent configuration.
+
+---
+
+## Use cases
Here are some common use cases for different agents.
@@ -393,13 +568,19 @@ Here are some common use cases for different agents.
- **Debug agent**: Focused on investigation with bash and read tools enabled
- **Docs agent**: Documentation writing with file operations but no system commands
-You might also find different models are good for different use cases.
-
---
## Examples
-### Documentation Agent
+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).
+:::
+
+---
+
+### Documentation agent
```markdown title="~/.config/opencode/agent/docs-writer.md"
---
@@ -419,7 +600,9 @@ Focus on:
- User-friendly language
```
-### Security Auditor
+---
+
+### Security auditor
```markdown title="~/.config/opencode/agent/security-auditor.md"
---
diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx
index 9d93c2330..69f2c39a6 100644
--- a/packages/web/src/content/docs/docs/cli.mdx
+++ b/packages/web/src/content/docs/docs/cli.mdx
@@ -101,22 +101,16 @@ Both the `/editor` and `/export` commands use the editor specified in your `EDIT
- ```bash
- export EDITOR=nano # or vim, code, etc.
- ```
- To make it permanent, add this to your shell profile; `~/.bashrc`, `~/.zshrc`, etc.
+ ```bash export EDITOR=nano # or vim, code, etc. ``` To make it permanent, add this to your shell profile;
+ `~/.bashrc`, `~/.zshrc`, etc.
- ```bash
- set EDITOR=notepad # or code, vim, etc.
- ```
- To make it permanent, use **System Properties** > **Environment Variables**.
+ ```bash set EDITOR=notepad # or code, vim, etc. ``` To make it permanent, use **System Properties** > **Environment
+ Variables**.
- ```bash
- $env:EDITOR = "notepad" # or "code", "vim", etc.
- ```
- To make it permanent, add this to your PowerShell profile.
+ ```bash $env:EDITOR = "notepad" # or "code", "vim", etc. ``` To make it permanent, add this to your PowerShell
+ profile.
@@ -136,28 +130,25 @@ The opencode CLI also has the following commands.
---
-### run
+### agent
-Run opencode in non-interactive mode by passing a prompt directly.
+Manage agents for opencode.
```bash
-opencode run [message..]
+opencode agent [command]
```
-This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
+---
-```bash "opencode run"
-opencode run Explain the use of context in Go
+#### create
+
+Create a new agent with custom configuration.
+
+```bash
+opencode agent create
```
-#### Flags
-
-| Flag | Short | Description |
-| ------------ | ----- | ------------------------------------------ |
-| `--continue` | `-c` | Continue the last session |
-| `--session` | `-s` | Session ID to continue |
-| `--share` | | Share the session |
-| `--model` | `-m` | Model to use in the form of provider/model |
+This command will guide you through creating a new agent with a custom system prompt and tool configuration.
---
@@ -209,6 +200,102 @@ opencode auth logout
---
+### github
+
+Manage the GitHub agent for repository automation.
+
+```bash
+opencode github [command]
+```
+
+---
+
+#### install
+
+Install the GitHub agent in your repository.
+
+```bash
+opencode github install
+```
+
+This sets up the necessary GitHub Actions workflow and guides you through the configuration process. [Learn more](/docs/github).
+
+---
+
+#### run
+
+Run the GitHub agent. This is typically used in GitHub Actions.
+
+```bash
+opencode github run
+```
+
+##### Flags
+
+| Flag | Description |
+| --------- | ------------------------------------------------ |
+| `--event` | GitHub mock event to run the agent for |
+| `--token` | GitHub personal access token |
+
+---
+
+### models
+
+List all available models from configured providers.
+
+```bash
+opencode models
+```
+
+This command displays all models available across your configured providers in the format `provider/model`.
+
+---
+
+### run
+
+Run opencode in non-interactive mode by passing a prompt directly.
+
+```bash
+opencode run [message..]
+```
+
+This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
+
+```bash "opencode run"
+opencode run Explain the use of context in Go
+```
+
+#### Flags
+
+| Flag | Short | Description |
+| ------------ | ----- | ------------------------------------------ |
+| `--continue` | `-c` | Continue the last session |
+| `--session` | `-s` | Session ID to continue |
+| `--share` | | Share the session |
+| `--model` | `-m` | Model to use in the form of provider/model |
+| `--agent` | | Agent to use |
+
+---
+
+### serve
+
+Start a headless opencode server for API access.
+
+```bash
+opencode serve
+```
+
+This starts an HTTP server that provides API access to opencode functionality without the TUI interface.
+
+#### Flags
+
+| Flag | Short | Description |
+| ------------ | ----- | ------------------------------------------ |
+| `--port` | `-p` | Port to listen on |
+| `--hostname` | `-h` | Hostname to listen on |
+
+---
+
### upgrade
Updates opencode to the latest version or a specific version.
@@ -229,17 +316,26 @@ To upgrade to a specific version.
opencode upgrade v0.1.48
```
+#### Flags
+
+| Flag | Short | Description |
+| ---------- | ----- | --------------------------------------------------------- |
+| `--method` | `-m` | The installation method that was used; curl, npm, pnpm, bun, brew |
+
---
## Flags
-The opencode CLI takes the following flags.
+The opencode CLI takes the following global flags.
| Flag | Short | Description |
| -------------- | ----- | ------------------------------------------ |
| `--help` | `-h` | Display help |
| `--version` | | Print version number |
| `--print-logs` | | Print logs to stderr |
+| `--log-level` | | Log level (DEBUG, INFO, WARN, ERROR) |
| `--prompt` | `-p` | Prompt to use |
| `--model` | `-m` | Model to use in the form of provider/model |
| `--mode` | | Mode to use |
+| `--port` | | Port to listen on |
+| `--hostname` | | Hostname to listen on |
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx
index 0bacf2bff..06eb6ee7d 100644
--- a/packages/web/src/content/docs/docs/config.mdx
+++ b/packages/web/src/content/docs/docs/config.mdx
@@ -71,25 +71,6 @@ Your editor should be able to validate and autocomplete based on the schema.
---
-### Modes
-
-opencode comes with two built-in modes: _build_, the default with all tools enabled. And _plan_, restricted mode with file modification tools disabled. You can override these built-in modes or define your own custom modes with the `mode` option.
-
-```json title="opencode.json"
-{
- "$schema": "https://opencode.ai/config.json",
- "mode": {
- "build": {},
- "plan": {},
- "my-custom-mode": {}
- }
-}
-```
-
-[Learn more here](/docs/modes).
-
----
-
### Models
You can configure the providers and models you want to use in your opencode config through the `provider`, `model` and `small_model` options.
@@ -317,6 +298,7 @@ Use `{env:VARIABLE_NAME}` to substitute environment variables:
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
+ "models": {},
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
@@ -336,7 +318,7 @@ Use `{file:path/to/file}` to substitute the contents of a file:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
- "instructions": ["{file:./custom-instructions.md}"],
+ "instructions": ["./custom-instructions.md"],
"provider": {
"openai": {
"options": {
diff --git a/packages/web/src/content/docs/docs/formatters.mdx b/packages/web/src/content/docs/docs/formatters.mdx
index 720f3c1af..9c9411aeb 100644
--- a/packages/web/src/content/docs/docs/formatters.mdx
+++ b/packages/web/src/content/docs/docs/formatters.mdx
@@ -16,7 +16,7 @@ opencode comes with several built-in formatters for popular languages and framew
| 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` config file |
+| 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 |
diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx
index 15ed855a8..ccea974ca 100644
--- a/packages/web/src/content/docs/docs/index.mdx
+++ b/packages/web/src/content/docs/docs/index.mdx
@@ -63,7 +63,7 @@ You can also install it with the following:
-- **Using Homebrew on macOS**
+- **Using Homebrew on macOS and Linux**
```bash
brew install sst/tap/opencode
diff --git a/packages/web/src/content/docs/docs/lsp.mdx b/packages/web/src/content/docs/docs/lsp.mdx
index 4783683bb..76edad3ee 100644
--- a/packages/web/src/content/docs/docs/lsp.mdx
+++ b/packages/web/src/content/docs/docs/lsp.mdx
@@ -11,9 +11,10 @@ opencode integrates with your Language Server Protocol (LSP) to help the LLM int
opencode comes with several built-in LSP servers for popular languages:
-| LSP Server | Extensions | Requirements |
+| LSP Server | Extensions | Requirements |
| ---------- | -------------------------------------------- | ----------------------------------- |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | `typescript` dependency in project |
+| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | `eslint` dependency in project |
| gopls | .go | `go` command available |
| ruby-lsp | .rb, .rake, .gemspec, .ru | `ruby` and `gem` commands available |
| pyright | .py, .pyi | `pyright` dependency installed |
@@ -41,7 +42,7 @@ You can customize LSP servers through the `lsp` section in your opencode config.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
- "lsp": { }
+ "lsp": {}
}
```
@@ -49,7 +50,7 @@ Each LSP server supports the following:
| Property | Type | Description |
| ---------------- | -------- | ------------------------------------------------- |
-| `disabled` | boolean | Set this to `true` to disable the LSP server |
+| `disabled` | boolean | Set this to `true` to disable the LSP server |
| `command` | string[] | The command to start the LSP server |
| `extensions` | string[] | File extensions this LSP server should handle |
| `env` | object | Environment variables to set when starting server |
diff --git a/packages/web/src/content/docs/docs/modes.mdx b/packages/web/src/content/docs/docs/modes.mdx
new file mode 100644
index 000000000..ae14c2f32
--- /dev/null
+++ b/packages/web/src/content/docs/docs/modes.mdx
@@ -0,0 +1,331 @@
+---
+title: Modes
+description: Different modes for different use cases.
+---
+
+:::caution
+Modes are now configured through the `agent` option in the opencode config. The
+`mode` option is now deprecated. [Learn more](/docs/agents).
+:::
+
+Modes in opencode allow you to customize the behavior, tools, and prompts for different use cases.
+
+It comes with two built-in modes: **build** and **plan**. You can customize
+these or configure your own through the opencode config.
+
+You can switch between modes during a session or configure them in your config file.
+
+---
+
+## Built-in
+
+opencode comes with two built-in modes.
+
+---
+
+### Build
+
+Build is the **default** mode with all tools enabled. This is the standard mode for development work where you need full access to file operations and system commands.
+
+---
+
+### Plan
+
+A restricted mode designed for planning and analysis. In plan mode, the following tools are disabled by default:
+
+- `write` - Cannot create new files
+- `edit` - Cannot modify existing files
+- `patch` - Cannot apply patches
+- `bash` - Cannot execute shell commands
+
+This mode is useful when you want the AI to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
+
+---
+
+## Switching
+
+You can switch between modes during a session using the _Tab_ key. Or your configured `switch_mode` keybind.
+
+See also: [Formatters](/docs/formatters) for information about code formatting configuration.
+
+---
+
+## Configure
+
+You can customize the built-in modes or create your own through configuration. Modes can be configured in two ways:
+
+### JSON Configuration
+
+Configure modes in your `opencode.json` config file:
+
+```json title="opencode.json"
+{
+ "$schema": "https://opencode.ai/config.json",
+ "mode": {
+ "build": {
+ "model": "anthropic/claude-sonnet-4-20250514",
+ "prompt": "{file:./prompts/build.txt}",
+ "tools": {
+ "write": true,
+ "edit": true,
+ "bash": true
+ }
+ },
+ "plan": {
+ "model": "anthropic/claude-haiku-4-20250514",
+ "tools": {
+ "write": false,
+ "edit": false,
+ "bash": false
+ }
+ }
+ }
+}
+```
+
+### Markdown Configuration
+
+You can also define modes using markdown files. Place them in:
+
+- Global: `~/.config/opencode/mode/`
+- Project: `.opencode/mode/`
+
+```markdown title="~/.config/opencode/mode/review.md"
+---
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+tools:
+ write: false
+ edit: false
+ bash: false
+---
+
+You are in code review mode. Focus on:
+
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance implications
+- Security considerations
+
+Provide constructive feedback without making direct changes.
+```
+
+The markdown file name becomes the mode name (e.g., `review.md` creates a `review` mode).
+
+Let's look at these configuration options in detail.
+
+---
+
+### Model
+
+Use the `model` config to override the default model for this mode. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
+
+```json title="opencode.json"
+{
+ "mode": {
+ "plan": {
+ "model": "anthropic/claude-haiku-4-20250514"
+ }
+ }
+}
+```
+
+---
+
+### Temperature
+
+Control the randomness and creativity of the AI's responses with the `temperature` config. Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
+
+```json title="opencode.json"
+{
+ "mode": {
+ "plan": {
+ "temperature": 0.1
+ },
+ "creative": {
+ "temperature": 0.8
+ }
+ }
+}
+```
+
+Temperature values typically range from 0.0 to 1.0:
+
+- **0.0-0.2**: Very focused and deterministic responses, ideal for code analysis and planning
+- **0.3-0.5**: Balanced responses with some creativity, good for general development tasks
+- **0.6-1.0**: More creative and varied responses, useful for brainstorming and exploration
+
+```json title="opencode.json"
+{
+ "mode": {
+ "analyze": {
+ "temperature": 0.1,
+ "prompt": "{file:./prompts/analysis.txt}"
+ },
+ "build": {
+ "temperature": 0.3
+ },
+ "brainstorm": {
+ "temperature": 0.7,
+ "prompt": "{file:./prompts/creative.txt}"
+ }
+ }
+}
+```
+
+If no temperature is specified, opencode uses model-specific defaults (typically 0 for most models, 0.55 for Qwen models).
+
+---
+
+### Prompt
+
+Specify a custom system prompt file for this mode with the `prompt` config. The prompt file should contain instructions specific to the mode's purpose.
+
+```json title="opencode.json"
+{
+ "mode": {
+ "review": {
+ "prompt": "{file:./prompts/code-review.txt}"
+ }
+ }
+}
+```
+
+This path is relative to where the config file is located. So this works for
+both the global opencode config and the project specific config.
+
+---
+
+### Tools
+
+Control which tools are available in this mode with the `tools` config. You can enable or disable specific tools by setting them to `true` or `false`.
+
+```json
+{
+ "mode": {
+ "readonly": {
+ "tools": {
+ "write": false,
+ "edit": false,
+ "bash": false,
+ "read": true,
+ "grep": true,
+ "glob": true
+ }
+ }
+ }
+}
+```
+
+If no tools are specified, all tools are enabled by default.
+
+---
+
+#### Available tools
+
+Here are all the tools can be controlled through the mode config.
+
+| Tool | Description |
+| ----------- | ----------------------- |
+| `bash` | Execute shell commands |
+| `edit` | Modify existing files |
+| `write` | Create new files |
+| `read` | Read file contents |
+| `grep` | Search file contents |
+| `glob` | Find files by pattern |
+| `list` | List directory contents |
+| `patch` | Apply patches to files |
+| `todowrite` | Manage todo lists |
+| `todoread` | Read todo lists |
+| `webfetch` | Fetch web content |
+
+---
+
+## Custom modes
+
+You can create your own custom modes by adding them to the configuration. Here are examples using both approaches:
+
+### Using JSON configuration
+
+```json title="opencode.json" {4-14}
+{
+ "$schema": "https://opencode.ai/config.json",
+ "mode": {
+ "docs": {
+ "prompt": "{file:./prompts/documentation.txt}",
+ "tools": {
+ "write": true,
+ "edit": true,
+ "bash": false,
+ "read": true,
+ "grep": true,
+ "glob": true
+ }
+ }
+ }
+}
+```
+
+### Using markdown files
+
+Create mode files in `.opencode/mode/` for project-specific modes or `~/.config/opencode/mode/` for global modes:
+
+```markdown title=".opencode/mode/debug.md"
+---
+temperature: 0.1
+tools:
+ bash: true
+ read: true
+ grep: true
+ write: false
+ edit: false
+---
+
+You are in debug mode. Your primary goal is to help investigate and diagnose issues.
+
+Focus on:
+
+- Understanding the problem through careful analysis
+- Using bash commands to inspect system state
+- Reading relevant files and logs
+- Searching for patterns and anomalies
+- Providing clear explanations of findings
+
+Do not make any changes to files. Only investigate and report.
+```
+
+```markdown title="~/.config/opencode/mode/refactor.md"
+---
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+ edit: true
+ read: true
+ grep: true
+ glob: true
+---
+
+You are in refactoring mode. Focus on improving code quality without changing functionality.
+
+Priorities:
+
+- Improve code readability and maintainability
+- Apply consistent naming conventions
+- Reduce code duplication
+- Optimize performance where appropriate
+- Ensure all tests continue to pass
+```
+
+---
+
+### Use cases
+
+Here are some common use cases for different modes.
+
+- **Build mode**: Full development work with all tools enabled
+- **Plan mode**: Analysis and planning without making changes
+- **Review mode**: Code review with read-only access plus documentation tools
+- **Debug mode**: Focused on investigation with bash and read tools enabled
+- **Docs mode**: Documentation writing with file operations but no system commands
+
+You might also find different models are good for different use cases.
diff --git a/packages/web/src/content/docs/docs/permissions.mdx b/packages/web/src/content/docs/docs/permissions.mdx
index a3de452df..44dbc92ef 100644
--- a/packages/web/src/content/docs/docs/permissions.mdx
+++ b/packages/web/src/content/docs/docs/permissions.mdx
@@ -13,6 +13,16 @@ The permissions system provides granular control to restrict what actions AI age
Permissions are configured in your `opencode.json` file under the `permission` key. Here are the available options.
+### Tool Permission Support
+
+| Tool | Description |
+| ---------- | ------------------------------- |
+| `edit` | Control file editing operations |
+| `bash` | Control bash command execution |
+| `webfetch` | Control web content fetching |
+
+They can also be configured per agent, see [Agent Configuration](/docs/agents#agent-configuration) for more details.
+
---
### edit
diff --git a/packages/web/src/content/docs/docs/plugins.mdx b/packages/web/src/content/docs/docs/plugins.mdx
index 1bd662778..08c697a62 100644
--- a/packages/web/src/content/docs/docs/plugins.mdx
+++ b/packages/web/src/content/docs/docs/plugins.mdx
@@ -18,7 +18,7 @@ functions. Each function receives a context object and returns a hooks object.
Plugins are loaded from:
-1. `.opencode/plugin` directory either in your proejct
+1. `.opencode/plugin` directory either in your project
2. Or, globally in `~/.config/opencode/plugin`
---
@@ -90,7 +90,7 @@ We are using `osascript` to run AppleScript on macOS. Here we are using it to se
Prevent opencode from reading `.env` files:
-```javascript title=".opencode/plugin/slack.js"
+```javascript title=".opencode/plugin/env-protection.js"
export const EnvProtection = async ({ client, $ }) => {
return {
tool: {
diff --git a/packages/web/src/content/docs/docs/providers.mdx b/packages/web/src/content/docs/docs/providers.mdx
index cad9878ea..c6455b1d8 100644
--- a/packages/web/src/content/docs/docs/providers.mdx
+++ b/packages/web/src/content/docs/docs/providers.mdx
@@ -546,7 +546,7 @@ To use Kimi K2 from Moonshot AI:
1. Head over to the [Moonshot AI console](https://platform.moonshot.ai/console), create an account, and click **Create API key**.
-2. Run `opencode auth login` and select **Other**.
+2. Run `opencode auth login` and select **Moonshot AI**.
```bash
$ opencode auth login
@@ -555,11 +555,11 @@ To use Kimi K2 from Moonshot AI:
│
◆ Select provider
│ ...
- │ ● Other
+ │ ● Moonshot AI
└
```
-3. Enter `moonshot` as the provider ID.
+3. Enter your Moonshot API key.
```bash
$ opencode auth login
@@ -567,48 +567,14 @@ To use Kimi K2 from Moonshot AI:
┌ Add credential
│
◇ Select provider
- │ Other
- │
- ◇ Enter provider id
- │ moonshot
- └
- ```
-
-4. Enter your Moonshot API key.
-
- ```bash
- $ opencode auth login
-
- ┌ Add credential
+ │ Moonshot AI
│
◇ Enter your API key
- │ sk-...
+ │ _
└
```
-5. Configure Moonshot in your opencode config.
-
- ```json title="opencode.json" ""moonshot"" {5-15}
- {
- "$schema": "https://opencode.ai/config.json",
- "provider": {
- "moonshot": {
- "npm": "@ai-sdk/openai-compatible",
- "name": "Moonshot AI",
- "options": {
- "baseURL": "https://api.moonshot.ai/v1"
- },
- "models": {
- "kimi-k2-0711-preview": {
- "name": "Kimi K2"
- }
- }
- }
- }
- }
- ```
-
-6. Run the `/models` command to select _Kimi K2_.
+4. Run the `/models` command to select _Kimi K2_.
---
diff --git a/packages/web/src/pages/s/[id].astro b/packages/web/src/pages/s/[id].astro
index 430d50cfa..df39f0070 100644
--- a/packages/web/src/pages/s/[id].astro
+++ b/packages/web/src/pages/s/[id].astro
@@ -1,6 +1,5 @@
---
import { Base64 } from "js-base64";
-import config from "virtual:starlight/user-config";
import config from '../../../config.mjs'
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
diff --git a/script/publish.ts b/script/publish.ts
index 7a48749d1..c0f79bb9c 100755
--- a/script/publish.ts
+++ b/script/publish.ts
@@ -38,10 +38,48 @@ await import(`../packages/sdk/js/script/publish.ts`)
console.log("\n=== plugin ===\n")
await import(`../packages/plugin/script/publish.ts`)
+const dir = new URL("..", import.meta.url).pathname
+process.chdir(dir)
+
if (!snapshot) {
await $`git commit -am "release: v${version}"`
await $`git tag v${version}`
- await $`git push origin HEAD --tags --no-verify`
+ await $`git fetch origin`
+ await $`git cherry-pick HEAD..origin/dev`.nothrow()
+ await $`git push origin HEAD --tags --no-verify --force`
+
+ const previous = await fetch("https://api.github.com/repos/sst/opencode/releases/latest")
+ .then((res) => {
+ if (!res.ok) throw new Error(res.statusText)
+ return res.json()
+ })
+ .then((data) => data.tag_name)
+
+ console.log("finding commits between", previous, "and", "HEAD")
+ const commits = await fetch(`https://api.github.com/repos/sst/opencode/compare/${previous}...HEAD`)
+ .then((res) => res.json())
+ .then((data) => data.commits || [])
+
+ const raw = commits.map((commit: any) => `- ${commit.commit.message.split("\n").join(" ")}`)
+ console.log(raw)
+
+ const notes =
+ raw
+ .filter((x: string) => {
+ const lower = x.toLowerCase()
+ return (
+ !lower.includes("release:") &&
+ !lower.includes("ignore:") &&
+ !lower.includes("chore:") &&
+ !lower.includes("ci:") &&
+ !lower.includes("wip:") &&
+ !lower.includes("docs:") &&
+ !lower.includes("doc:")
+ )
+ })
+ .join("\n") || "No notable changes"
+
+ await $`gh release create v${version} --title "v${version}" --notes ${notes} ./packages/opencode/dist/*.zip`
}
if (snapshot) {
await $`git checkout -b snapshot-${version}`
diff --git a/sdks/vscode/package.json b/sdks/vscode/package.json
index f5314dfea..a3398a255 100644
--- a/sdks/vscode/package.json
+++ b/sdks/vscode/package.json
@@ -2,7 +2,7 @@
"name": "opencode",
"displayName": "opencode",
"description": "opencode for VS Code",
- "version": "0.3.133",
+ "version": "0.4.40",
"publisher": "sst-dev",
"repository": {
"type": "git",
diff --git a/sst-env.d.ts b/sst-env.d.ts
index 8286f0938..3af3f82c0 100644
--- a/sst-env.d.ts
+++ b/sst-env.d.ts
@@ -9,13 +9,44 @@ declare module "sst" {
"type": "sst.sst.Secret"
"value": string
}
+ "AUTH_API_URL": {
+ "type": "sst.sst.Linkable"
+ "value": string
+ }
"Api": {
"type": "sst.cloudflare.Worker"
"url": string
}
+ "AuthApi": {
+ "type": "sst.cloudflare.Worker"
+ "url": string
+ }
+ "AuthStorage": {
+ "type": "sst.cloudflare.Kv"
+ }
"Bucket": {
"type": "sst.cloudflare.Bucket"
}
+ "Console": {
+ "type": "sst.cloudflare.StaticSite"
+ "url": string
+ }
+ "DATABASE_PASSWORD": {
+ "type": "sst.sst.Secret"
+ "value": string
+ }
+ "DATABASE_USERNAME": {
+ "type": "sst.sst.Secret"
+ "value": string
+ }
+ "Database": {
+ "database": string
+ "host": string
+ "password": string
+ "port": number
+ "type": "sst.sst.Linkable"
+ "username": string
+ }
"GITHUB_APP_ID": {
"type": "sst.sst.Secret"
"value": string
@@ -24,6 +55,18 @@ declare module "sst" {
"type": "sst.sst.Secret"
"value": string
}
+ "GITHUB_CLIENT_ID_CONSOLE": {
+ "type": "sst.sst.Secret"
+ "value": string
+ }
+ "GITHUB_CLIENT_SECRET_CONSOLE": {
+ "type": "sst.sst.Secret"
+ "value": string
+ }
+ "GOOGLE_CLIENT_ID": {
+ "type": "sst.sst.Secret"
+ "value": string
+ }
"GatewayApi": {
"type": "sst.cloudflare.Worker"
"url": string
@@ -32,10 +75,14 @@ declare module "sst" {
"type": "sst.sst.Secret"
"value": string
}
- "OPENCODE_API_KEY": {
+ "STRIPE_SECRET_KEY": {
"type": "sst.sst.Secret"
"value": string
}
+ "STRIPE_WEBHOOK_SECRET": {
+ "type": "sst.sst.Linkable"
+ "value": string
+ }
"Web": {
"type": "sst.cloudflare.Astro"
"url": string
diff --git a/sst.config.ts b/sst.config.ts
index c15fdabb6..44f984b93 100644
--- a/sst.config.ts
+++ b/sst.config.ts
@@ -7,13 +7,20 @@ export default $config({
removal: input?.stage === "production" ? "retain" : "remove",
protect: ["production"].includes(input?.stage),
home: "cloudflare",
+ providers: {
+ stripe: {
+ apiKey: process.env.STRIPE_SECRET_KEY,
+ },
+ },
}
},
async run() {
- const { api, gateway } = await import("./infra/app.js")
+ const { api } = await import("./infra/app.js")
+ const { auth, gateway } = await import("./infra/cloud.js")
return {
api: api.url,
gateway: gateway.url,
+ auth: auth.url,
}
},
})