docs: expand OpenCode 2 beta guides · argszero/opencode@1004fbb · GitHub
Skip to content

Commit 1004fbb

Browse files
thdxrthdxr
committed
docs: expand OpenCode 2 beta guides
1 parent a774637 commit 1004fbb

24 files changed

Lines changed: 889 additions & 359 deletions

‎packages/core/src/plugin/skill.ts‎

Lines changed: 1 addition & 1 deletion

‎packages/core/src/plugin/skill/opencode.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,23 @@ settings when editing an existing file.
3737
See the [full configuration guide](https://opencode.mintlify.site/config) for
3838
every field, examples, config locations, and links to dedicated feature guides.
3939

40+
## V1 to V2 migration
41+
42+
For any request to migrate OpenCode configuration, agents, commands, skills,
43+
plugins, integrations, or other behavior from V1 to V2, read the full
44+
[migration guide](https://opencode.mintlify.site/migrate-v1) before acting. In
45+
the repository, its source is `packages/docs/migrate-v1.mdx`.
46+
47+
V1 config files and `.opencode/` definitions are intended to remain compatible.
48+
The only intentional breaking changes are the server API and plugin API. Native
49+
V2 config uses more ergonomic shapes, but conversion is optional. When the user
50+
requests conversion, inspect the complete configuration, preserve behavior and
51+
unrelated settings, and apply only the relevant migrations from the guide. If
52+
the request includes a V1 plugin, explain that its API is not finalized and do
53+
not attempt migration yet. Once the V2 plugin API is finalized, OpenCode should
54+
be able to migrate most plugins. If non-API V1 functionality fails in V2, use
55+
the `report` skill to file it as a compatibility bug.
56+
4057
## Service
4158

4259
OpenCode uses a client-server architecture. Interfaces such as the TUI connect

‎packages/docs/agents.mdx‎

Lines changed: 57 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,13 @@
11
---
22
title: "Agents"
3-
description: "Configure and use primary agents and subagents in OpenCode."
3+
description: ""
44
---
55

66
Agents combine a system prompt, model preference, tool permissions, and display
77
metadata into a reusable assistant profile. OpenCode includes agents for common
88
workflows, and you can override them or add your own in configuration or
99
Markdown files.
1010

11-
## Modes
12-
13-
An agent's `mode` controls where it can run:
14-
15-
| Mode | Behavior |
16-
| --- | --- |
17-
| `primary` | Can be selected as the main agent for a session. It cannot be launched as a subagent. |
18-
| `subagent` | Can run in a child session through the `subagent` tool, but cannot be selected as the main agent. |
19-
| `all` | Can be used either way. This is the default for a custom agent when `mode` is omitted. |
20-
21-
In the TUI, press <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> to cycle
22-
through visible primary and `all` agents, or use `/agents` to choose one.
23-
24-
Subagents run in child sessions with fresh context. A primary agent can invoke
25-
one with the `subagent` tool, either in the foreground or in the background.
26-
You can also `@` mention a visible subagent to ask the current agent to delegate
27-
work to it:
28-
29-
```text
30-
@explore find where authentication errors are handled
31-
```
32-
33-
The parent agent's `subagent` permission controls which agents it may launch.
34-
The child currently uses its own configured permissions, not a restricted copy
35-
of the parent's permissions.
36-
3711
## Built-in agents
3812

3913
| Agent | Mode | Purpose |
@@ -66,42 +40,33 @@ be hidden. If it is unavailable, OpenCode falls back to `build`, then to the
6640
first visible agent that can run as a primary agent. This selection does not
6741
rewrite the agent already stored on an existing session.
6842

69-
## Configure agents
43+
## Modes
7044

71-
### JSON or JSONC
45+
An agent's `mode` controls where it can run:
7246

73-
Use the plural `agents` field in any [OpenCode configuration file](/config):
47+
| Mode | Behavior |
48+
| --- | --- |
49+
| `primary` | Can be selected as the main agent for a session. It cannot be launched as a subagent. |
50+
| `subagent` | Can run in a child session through the `subagent` tool, but cannot be selected as the main agent. |
51+
| `all` | Can be used either way. This is the default for a custom agent when `mode` is omitted. |
7452

75-
```jsonc title="opencode.jsonc"
76-
{
77-
"$schema": "https://opencode.ai/config.json",
78-
"default_agent": "reviewer",
79-
"agents": {
80-
"reviewer": {
81-
"description": "Reviews changes for correctness, security, and missing tests",
82-
"mode": "all",
83-
"model": "anthropic/claude-sonnet-4-5#high",
84-
"system": "Review the current changes. Report findings before any summary.",
85-
"color": "warning",
86-
"steps": 8,
87-
"permissions": [
88-
{ "action": "edit", "resource": "*", "effect": "deny" },
89-
{ "action": "shell", "resource": "*", "effect": "deny" }
90-
]
91-
},
92-
"build": {
93-
"permissions": [
94-
{ "action": "shell", "resource": "git push *", "effect": "ask" }
95-
]
96-
}
97-
}
98-
}
53+
In the TUI, press <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> to cycle
54+
through visible primary and `all` agents, or use `/agents` to choose one.
55+
56+
Subagents run in child sessions with fresh context. A primary agent can invoke
57+
one with the `subagent` tool, either in the foreground or in the background.
58+
You can also `@` mention a visible subagent to ask the current agent to delegate
59+
work to it:
60+
61+
```text
62+
@explore find where authentication errors are handled
9963
```
10064

101-
Agent definitions merge in configuration order. Later scalar fields replace
102-
earlier values, request maps merge by key, and permission rules are appended.
103-
Global `permissions` are applied to every agent before its agent-specific rules,
104-
so a later agent rule can refine a global rule.
65+
The parent agent's `subagent` permission controls which agents it may launch.
66+
The child currently uses its own configured permissions, not a restricted copy
67+
of the parent's permissions.
68+
69+
## Configure agents
10570

10671
### Markdown files
10772

@@ -139,9 +104,40 @@ Review for correctness, security, regressions, and missing tests.
139104
List findings in severity order with file and line references.
140105
```
141106

142-
For compatibility with older layouts, V2 also discovers Markdown under
143-
`agent/`, and treats files under `mode/` or `modes/` as primary agents. Prefer
144-
`agents/` for new files.
107+
### JSON or JSONC
108+
109+
Use the `agents` field in any [OpenCode configuration file](/config):
110+
111+
```jsonc title="opencode.jsonc"
112+
{
113+
"$schema": "https://opencode.ai/config.json",
114+
"default_agent": "reviewer",
115+
"agents": {
116+
"reviewer": {
117+
"description": "Reviews changes for correctness, security, and missing tests",
118+
"mode": "all",
119+
"model": "anthropic/claude-sonnet-4-5#high",
120+
"system": "Review the current changes. Report findings before any summary.",
121+
"color": "warning",
122+
"steps": 8,
123+
"permissions": [
124+
{ "action": "edit", "resource": "*", "effect": "deny" },
125+
{ "action": "shell", "resource": "*", "effect": "deny" }
126+
]
127+
},
128+
"build": {
129+
"permissions": [
130+
{ "action": "shell", "resource": "git push *", "effect": "ask" }
131+
]
132+
}
133+
}
134+
}
135+
```
136+
137+
Agent definitions merge in configuration order. Later scalar fields replace
138+
earlier values, request maps merge by key, and permission rules are appended.
139+
Global `permissions` are applied to every agent before its agent-specific rules,
140+
so a later agent rule can refine a global rule.
145141

146142
## Options
147143

‎packages/docs/attachments.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Attachments"
3-
description: "Attach supported files and images to V2 prompts and configure image processing."
3+
description: ""
44
---
55

66
OpenCode can add local context to a prompt as text or image media. Current V2

‎packages/docs/client.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: "Client"
3+
description: "Connect an application to the OpenCode HTTP API."
4+
---
5+
6+
`@opencode-ai/client` is the generated TypeScript client for the OpenCode HTTP
7+
API. Use it when your application connects to an OpenCode server over the
8+
network. Its types and methods are generated from the same contract as the
9+
[API reference](/api).
10+
11+
<Warning>
12+
The V2 API and client are beta. Method names, inputs, and outputs may change
13+
before the stable release.
14+
</Warning>
15+
16+
## Install
17+
18+
```sh
19+
bun add @opencode-ai/client
20+
```
21+
22+
The package has two entrypoints:
23+
24+
- `@opencode-ai/client/promise` uses `fetch` and returns Promises or async
25+
iterables. It has no Effect runtime dependency.
26+
- `@opencode-ai/client/effect` returns Effects and Streams, decodes values into
27+
the V2 schema types, and requires an `HttpClient` service from Effect.
28+
29+
## Promise client
30+
31+
Create a client with the server URL, then call methods grouped by API resource:
32+
33+
```ts
34+
import { OpenCode } from "@opencode-ai/client/promise"
35+
36+
const client = OpenCode.make({
37+
baseUrl: "http://localhost:4096",
38+
})
39+
40+
const session = await client.session.create({
41+
location: { directory: "/workspace" },
42+
})
43+
44+
await client.session.prompt({
45+
sessionID: session.id,
46+
text: "Review the current changes",
47+
})
48+
```
49+
50+
Pass default authentication or application headers to `OpenCode.make` with
51+
`headers`. You can also supply a custom `fetch` implementation. Each operation
52+
accepts request options as its final argument for an `AbortSignal` or
53+
per-request headers.
54+
55+
Streaming endpoints return async iterables:
56+
57+
```ts
58+
for await (const event of client.event.subscribe()) {
59+
console.log(event.type)
60+
}
61+
```
62+
63+
## Effect client
64+
65+
Install the `effect` peer dependency when using the Effect entrypoint. The
66+
client uses canonical V2 values such as `Location.Ref` and `Session.ID`, and
67+
returns typed failures in the Effect error channel.
68+
69+
```ts
70+
import { AbsolutePath, Location, OpenCode } from "@opencode-ai/client/effect"
71+
import { Effect } from "effect"
72+
import { FetchHttpClient } from "effect/unstable/http"
73+
74+
const program = Effect.gen(function* () {
75+
const client = yield* OpenCode.make({ baseUrl: "http://localhost:4096" })
76+
const session = yield* client.session.create({
77+
location: Location.Ref.make({
78+
directory: AbsolutePath.make("/workspace"),
79+
}),
80+
})
81+
82+
return yield* client.session.get({ sessionID: session.id })
83+
})
84+
85+
const session = await Effect.runPromise(
86+
program.pipe(Effect.provide(FetchHttpClient.layer)),
87+
)
88+
```
89+
90+
Streaming operations, including `client.event.subscribe()` and
91+
`client.session.log(...)`, return Effect `Stream` values.

‎packages/docs/commands.mdx‎

Lines changed: 31 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Commands"
3-
description: "Create reusable slash commands from configuration or Markdown files."
3+
description: ""
44
---
55

66
Custom commands turn a named prompt template into a slash command. Type the
@@ -10,45 +10,18 @@ command in the TUI, followed by any arguments:
1010
/review src/auth
1111
```
1212

13-
## Configure with JSON
14-
15-
Add commands under the plural `commands` key in any OpenCode JSON or JSONC
16-
[configuration file](/config). Each entry's key is the command name and
17-
`template` is required.
18-
19-
```jsonc title="opencode.jsonc"
20-
{
21-
"$schema": "https://opencode.ai/config.json",
22-
"commands": {
23-
"review": {
24-
"description": "Review code for correctness and missing tests",
25-
"template": "Review $ARGUMENTS. Report bugs first, then missing tests.",
26-
"agent": "plan",
27-
"model": "anthropic/claude-sonnet-4-5#high"
28-
}
29-
}
30-
}
31-
```
32-
33-
Run it with:
34-
35-
```text
36-
/review src/auth
37-
```
38-
3913
## Configure with Markdown
4014

41-
OpenCode discovers `.md` command files in both the singular `command/` and
42-
plural `commands/` directories:
15+
OpenCode discovers `.md` command files in `commands/` directories:
4316

4417
```text
4518
~/.config/opencode/commands/ # Global
4619
.opencode/commands/ # Project
4720
```
4821

49-
The equivalent `command/` paths also work. Files may be nested; for example,
50-
`.opencode/commands/team/review.md` defines `/team/review`. Files with other
51-
extensions, including `.mdx`, are not discovered.
22+
Files may be nested; for example, `.opencode/commands/team/review.md` defines
23+
`/team/review`. Files with other extensions, including `.mdx`, are not
24+
discovered.
5225

5326
```md title=".opencode/commands/review.md"
5427
---
@@ -66,6 +39,32 @@ precedence over global definitions, and a later definition can override a
6639
built-in or earlier command with the same name. Changes are reloaded
6740
automatically.
6841

42+
Run it with:
43+
44+
```text
45+
/review src/auth
46+
```
47+
48+
## Configure with JSON
49+
50+
Add commands under the `commands` key in any OpenCode JSON or JSONC
51+
[configuration file](/config). Each entry's key is the command name and
52+
`template` is required.
53+
54+
```jsonc title="opencode.jsonc"
55+
{
56+
"$schema": "https://opencode.ai/config.json",
57+
"commands": {
58+
"review": {
59+
"description": "Review code for correctness and missing tests",
60+
"template": "Review $ARGUMENTS. Report bugs first, then missing tests.",
61+
"agent": "plan",
62+
"model": "anthropic/claude-sonnet-4-5#high"
63+
}
64+
}
65+
}
66+
```
67+
6968
## Fields
7069

7170
| Field | Required | Behavior |

‎packages/docs/compaction.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: "Context compaction"
3-
description: "Configure and run context compaction in OpenCode V2."
2+
title: "Compaction"
3+
description: ""
44
---
55

66
Compaction replaces the active model context from an older part of a session

‎packages/docs/config.mdx‎

Lines changed: 1 addition & 1 deletion

0 commit comments

Comments
 (0)