@@ -53,7 +56,7 @@ if (image) {
@@ -66,9 +69,6 @@ if (image) {
-
@@ -82,19 +82,95 @@ if (image) {
+
+
+
npm
+
+
+ npm install -g opencode-ai
+
+
+
+
+
+
+
Bun
+
+
+ bun install -g opencode-ai
+
+
+
+
+
+
+
Homebrew
+
+
+ brew install sst/tap/opencode
+
+
+
+
+
+
+
Paru
+
+
+ paru -S opencode-bin
+
+
+
+
+
+
+
-
-
opencode TUI with the tokyonight theme
-
+
+
+ opencode TUI with the tokyonight theme
+
+
+
+
+
+
+
+ opencode in VS Code
+
+
+
+
+
+
+ opencode in GitHub
+
+
+
+
-
- ```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 $env:EDITOR = "notepad" # or "code", "vim", etc. ``` To make it permanent, add this to your PowerShell
- profile.
-
-
-
-Popular editor options include:
-
-- `code` - Visual Studio Code
-- `vim` - Vim editor
-- `nano` - Nano editor
-- `notepad` - Windows Notepad
-- `subl` - Sublime Text
---
@@ -232,10 +129,10 @@ opencode github run
##### Flags
-| Flag | Description |
-| --------- | ------------------------------------------------ |
-| `--event` | GitHub mock event to run the agent for |
-| `--token` | GitHub personal access token |
+| Flag | Description |
+| --------- | -------------------------------------- |
+| `--event` | GitHub mock event to run the agent for |
+| `--token` | GitHub personal access token |
---
@@ -279,7 +176,7 @@ opencode run Explain the use of context in Go
### serve
-Start a headless opencode server for API access.
+Start a headless opencode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
```bash
opencode serve
@@ -289,9 +186,9 @@ This starts an HTTP server that provides API access to opencode functionality wi
#### Flags
-| Flag | Short | Description |
-| ------------ | ----- | ------------------------------------------ |
-| `--port` | `-p` | Port to listen on |
+| Flag | Short | Description |
+| ------------ | ----- | --------------------- |
+| `--port` | `-p` | Port to listen on |
| `--hostname` | `-h` | Hostname to listen on |
---
@@ -318,8 +215,8 @@ opencode upgrade v0.1.48
#### Flags
-| Flag | Short | Description |
-| ---------- | ----- | --------------------------------------------------------- |
+| Flag | Short | Description |
+| ---------- | ----- | ----------------------------------------------------------------- |
| `--method` | `-m` | The installation method that was used; curl, npm, pnpm, bun, brew |
---
@@ -336,6 +233,6 @@ The opencode CLI takes the following global flags.
| `--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 |
+| `--agent` | | Agent to use |
+| `--port` | | Port to listen on |
+| `--hostname` | | Hostname to listen on |
diff --git a/packages/web/src/content/docs/docs/commands.mdx b/packages/web/src/content/docs/docs/commands.mdx
new file mode 100644
index 000000000..3869ea8a4
--- /dev/null
+++ b/packages/web/src/content/docs/docs/commands.mdx
@@ -0,0 +1,156 @@
+---
+title: Commands
+description: Create custom commands for repetitive tasks.
+---
+
+Define custom commands to automate repetitive coding tasks.
+
+---
+
+## Create command files
+
+Create markdown files in the `command/` directory to define custom commands.
+
+Create `.opencode/command/test.md`:
+
+```md title=".opencode/command/test.md"
+---
+description: Run tests with coverage
+agent: build
+model: anthropic/claude-3-5-sonnet-20241022
+---
+
+Run the full test suite with coverage report and show any failures.
+Focus on the failing tests and suggest fixes.
+```
+
+The frontmatter defines command properties. The content becomes the template.
+
+Use the command by typing `/` followed by the command name.
+
+```bash frame="none"
+"/test"
+```
+
+---
+
+## Use arguments
+
+Pass arguments to commands using the `$ARGUMENTS` placeholder.
+
+Create `.opencode/command/component.md`:
+
+```md title=".opencode/command/component.md"
+---
+description: Create a new component
+---
+
+Create a new React component named $ARGUMENTS with TypeScript support.
+Include proper typing and basic structure.
+```
+
+Run the command with arguments:
+
+```bash frame="none"
+"/component Button"
+```
+
+---
+
+## Inject shell output
+
+Use `!command` to inject shell command output into your prompt.
+
+Create `.opencode/command/analyze-coverage.md`:
+
+```md title=".opencode/command/analyze-coverage.md"
+---
+description: Analyze test coverage
+---
+
+Here are the current test results:
+`!npm test`
+
+Based on these results, suggest improvements to increase coverage.
+```
+
+Create `.opencode/command/review-changes.md`:
+
+```md title=".opencode/command/review-changes.md"
+---
+description: Review recent changes
+---
+
+Recent git commits:
+`!git log --oneline -10`
+
+Review these changes and suggest any improvements.
+```
+
+Commands run in your project's root directory and their output becomes part of the prompt.
+
+---
+
+## Reference files
+
+Include files in your command using `@` followed by the filename.
+
+Create `.opencode/command/review-component.md`:
+
+```md title=".opencode/command/review-component.md"
+---
+description: Review component
+---
+
+Review the component in @src/components/Button.tsx.
+Check for performance issues and suggest improvements.
+```
+
+The file content gets included in the prompt automatically.
+
+---
+
+## Command properties
+
+Configure commands with these optional frontmatter properties:
+
+- **description**: Brief explanation of what the command does
+- **agent**: Agent to use (defaults to "build")
+- **model**: Specific model to use for this command
+
+Create `.opencode/command/code-review.md`:
+
+```md title=".opencode/command/code-review.md"
+---
+description: Code review assistant
+agent: build
+model: anthropic/claude-3-5-sonnet-20241022
+---
+
+Review the code for best practices and suggest improvements.
+```
+
+---
+
+## Command directory
+
+Store command files in these locations:
+
+- `.opencode/command/` - Project-specific commands
+- `command/` - Global commands in config directory
+
+Project commands take precedence over global ones.
+
+---
+
+## Built-in commands
+
+opencode includes several built-in commands:
+
+- `/init` - Initialize project and create AGENTS.md
+- `/undo` - Revert the last changes
+- `/redo` - Restore reverted changes
+- `/share` - Share the current conversation
+- `/help` - Show available commands and keybinds
+
+Use `/help` to see all available commands in your setup.
diff --git a/packages/web/src/content/docs/docs/github.mdx b/packages/web/src/content/docs/docs/github.mdx
index ca1a7398a..d592fc84f 100644
--- a/packages/web/src/content/docs/docs/github.mdx
+++ b/packages/web/src/content/docs/docs/github.mdx
@@ -1,6 +1,6 @@
---
title: GitHub
-description: Use opencode in GitHub issues and pull-requests
+description: Use opencode in GitHub issues and pull-requests.
---
opencode integrates with your GitHub workflow. Mention `/opencode` or `/oc` in your comment, and opencode will execute tasks within your GitHub Actions runner.
@@ -67,6 +67,7 @@ Or you can set it up manually.
with:
model: anthropic/claude-sonnet-4-20250514
# share: true
+ # github_token: xxxx
```
3. **Store the API keys in secrets**
@@ -77,8 +78,21 @@ Or you can set it up manually.
## Configuration
-- `model`: The model used by opencode. Takes the format of `provider/model`. This is **required**.
-- `share`: Share the session. Sessions are shared by default for public repos.
+- `model`: The model to use with opencode. Takes the format of `provider/model`. This is **required**.
+- `share`: Whether to share the opencode session. Defaults to **true** for public repositories.
+- `token`: Optional GitHub access token for performing operations such as creating comments, commiting changes, and opening pull requests. By default, opencode uses the installation access token from the opencode GitHub App, so commits, comments, and pull requests appear as coming from the app.
+
+ Alternatively, you can use the GitHub Action runner's [built-in `GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) without installing the opencode GitHub App. Just make sure to grant the required permissions in your workflow:
+
+ ```yaml
+ permissions:
+ id-token: write
+ contents: write
+ pull-requests: write
+ issues: write
+ ```
+
+ You can also use a [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)(PAT) if preferred.
---
diff --git a/packages/web/src/content/docs/docs/gitlab.mdx b/packages/web/src/content/docs/docs/gitlab.mdx
new file mode 100644
index 000000000..023ac678e
--- /dev/null
+++ b/packages/web/src/content/docs/docs/gitlab.mdx
@@ -0,0 +1,151 @@
+---
+title: GitLab
+description: Use opencode in GitLab issues and merge requests.
+---
+
+opencode integrates with your GitLab workflow.
+Mention `@opencode` in a comment, and opencode will execute tasks within your GitLab CI pipeline.
+
+---
+
+## Features
+
+- **Triage issues**: Ask opencode to look into an issue and explain it to you.
+- **Fix and implement**: Ask opencode to fix an issue or implement a feature.
+ It will work create a new branch and raised a merge request with the changes.
+- **Secure**: opencode runs on your GitLab runners.
+
+---
+
+## Setup
+
+opencode runs in your GitLab CI/CD pipeline, here's what you'll need to set it up:
+
+:::tip
+Check out the [**GitLab docs**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) for up to date instructions.
+:::
+
+1. Configure your GitLab environment
+2. Set up CI/CD
+3. Get an AI model provider API key
+4. Create a service account
+5. Configure CI/CD variables
+6. Create a flow config file, here's an example:
+
+
+ Flow configuration
+
+ ```yaml
+ image: node:22-slim
+ commands:
+ - echo "Installing opencode"
+ - npm install --global opencode-ai
+ - echo "Installing glab"
+ - export GITLAB_TOKEN=$GITLAB_TOKEN_OPENCODE
+ - apt-get update --quiet && apt-get install --yes curl wget gpg git && rm --recursive --force /var/lib/apt/lists/*
+ - curl --silent --show-error --location "https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository" | bash
+ - apt-get install --yes glab
+ - echo "Configuring glab"
+ - echo $GITLAB_HOST
+ - echo "Creating opencode auth configuration"
+ - mkdir --parents ~/.local/share/opencode
+ - |
+ cat > ~/.local/share/opencode/auth.json << EOF
+ {
+ "anthropic": {
+ "type": "api",
+ "key": "$ANTHROPIC_API_KEY"
+ }
+ }
+ EOF
+ - echo "Configuring git"
+ - git config --global user.email "opencode@gitlab.com"
+ - git config --global user.name "Opencode"
+ - echo "Testing glab"
+ - glab issue list
+ - echo "Running Opencode"
+ - |
+ opencode run "
+ You are an AI assistant helping with GitLab operations.
+
+ Context: $AI_FLOW_CONTEXT
+ Task: $AI_FLOW_INPUT
+ Event: $AI_FLOW_EVENT
+
+ Please execute the requested task using the available GitLab tools.
+ Be thorough in your analysis and provide clear explanations.
+
+
+ Please use the glab CLI to access data from GitLab. The glab CLI has already been authenticated. You can run the corresponding commands.
+
+ If you are asked to summarise an MR or issue or asked to provide more information then please post back a note to the MR/Issue so that the user can see it.
+ You don't need to commit or push up changes, those will be done automatically based on the file changes you make.
+
+ "
+ - git checkout --branch $CI_WORKLOAD_REF origin/$CI_WORKLOAD_REF
+ - echo "Checking for git changes and pushing if any exist"
+ - |
+ if ! git diff --quiet || ! git diff --cached --quiet || [ --not --zero "$(git ls-files --others --exclude-standard)" ]; then
+ echo "Git changes detected, adding and pushing..."
+ git add .
+ if git diff --cached --quiet; then
+ echo "No staged changes to commit"
+ else
+ echo "Committing changes to branch: $CI_WORKLOAD_REF"
+ git commit --message "Codex changes"
+ echo "Pushing changes up to $CI_WORKLOAD_REF"
+ git push https://gitlab-ci-token:$GITLAB_TOKEN@$GITLAB_HOST/gl-demo-ultimate-dev-ai-epic-17570/test-java-project.git $CI_WORKLOAD_REF
+ echo "Changes successfully pushed"
+ fi
+ else
+ echo "No git changes detected, skipping push"
+ fi
+ variables:
+ - ANTHROPIC_API_KEY
+ - GITLAB_TOKEN_OPENCODE
+ - GITLAB_HOST
+ ```
+
+
+
+You can refer to the [GitLab CLI agents docs](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) for detailed instructions.
+
+---
+
+## Examples
+
+Here are some examples of how you can use opencode in GitLab.
+
+:::tip
+You can configure to use a different trigger phrase than `@opencode`.
+:::
+
+- **Explain an issue**
+
+ Add this comment in a GitLab issue.
+
+ ```
+ @opencode explain this issue
+ ```
+
+ opencode will read the issue and reply with a clear explanation.
+
+- **Fix an issue**
+
+ In a GitLab issue, say:
+
+ ```
+ @opencode fix this
+ ```
+
+ opencode will create a new branch, implement the changes, and open a merge request with the changes.
+
+- **Review merge requests**
+
+ Leave the following comment on a GitLab merge request.
+
+ ```
+ @opencode review this merge request
+ ```
+
+ opencode will review the merge request and provide feedback.
diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx
index ccea974ca..97910e0e5 100644
--- a/packages/web/src/content/docs/docs/index.mdx
+++ b/packages/web/src/content/docs/docs/index.mdx
@@ -42,24 +42,24 @@ You can also install it with the following:
- ```bash
- npm install -g opencode-ai
- ```
+ ```bash
+ npm install -g opencode-ai
+ ```
- ```bash
- bun install -g opencode-ai
- ```
+ ```bash
+ bun install -g opencode-ai
+ ```
- ```bash
- pnpm install -g opencode-ai
- ```
+ ```bash
+ pnpm install -g opencode-ai
+ ```
- ```bash
- yarn global add opencode-ai
- ```
+ ```bash
+ yarn global add opencode-ai
+ ```
@@ -157,16 +157,16 @@ help.
You can ask opencode to explain the codebase to you.
-```txt frame="none"
+:::tip
+Use the `@` key to fuzzy search for files in the project.
+:::
+
+```txt frame="none" "@packages/functions/src/api/index.ts"
How is authentication handled in @packages/functions/src/api/index.ts
```
This is helpful if there's a part of the codebase that you didn't work on.
-:::tip
-Use the `@` key to fuzzy search for files in the project.
-:::
-
---
### Add features
@@ -238,7 +238,7 @@ You can ask opencode to add new features to your project. Though we first recomm
For more straightforward changes, you can ask opencode to directly build it
without having to review the plan first.
-```txt frame="none"
+```txt frame="none" "@packages/functions/src/settings.ts" "@packages/functions/src/notes.ts"
We need to add authentication to the /settings route. Take a look at how this is
handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts
@@ -253,7 +253,7 @@ changes.
Let's say you ask opencode to make some changes.
-```txt frame="none"
+```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```
@@ -267,7 +267,7 @@ using the `/undo` command.
opencode will now revert the changes you made and show your original message
again.
-```txt frame="none"
+```txt frame="none" "@packages/functions/src/api/index.ts"
Can you refactor the function in @packages/functions/src/api/index.ts?
```
@@ -308,4 +308,4 @@ Here's an [example conversation](https://opencode.ai/s/4XP1fce5) with opencode.
And that's it! You are now a pro at using opencode.
-To make it your own, we recommend [picking a theme](/docs/themes), [customizing the keybinds](/docs/keybinds), [configuring code formatters](/docs/formatters), or playing around with the [opencode config](/docs/config).
+To make it your own, we recommend [picking a theme](/docs/themes), [customizing the keybinds](/docs/keybinds), [configuring code formatters](/docs/formatters), [creating custom commands](/docs/commands), or playing around with the [opencode config](/docs/config).
diff --git a/packages/web/src/content/docs/docs/keybinds.mdx b/packages/web/src/content/docs/docs/keybinds.mdx
index 6bb573bce..6fd6148e1 100644
--- a/packages/web/src/content/docs/docs/keybinds.mdx
+++ b/packages/web/src/content/docs/docs/keybinds.mdx
@@ -11,27 +11,21 @@ opencode has a list of keybinds that you can customize through the opencode conf
"keybinds": {
"leader": "ctrl+x",
"app_help": "h",
- "switch_agent": "tab",
-
+ "app_exit": "ctrl+c,q",
"editor_open": "e",
-
+ "theme_list": "t",
+ "project_init": "i",
+ "tool_details": "d",
+ "thinking_blocks": "b",
+ "session_export": "x",
"session_new": "n",
"session_list": "l",
"session_share": "s",
- "session_unshare": "u",
+ "session_unshare": "none",
"session_interrupt": "esc",
"session_compact": "c",
-
- "tool_details": "d",
- "model_list": "m",
- "theme_list": "t",
- "project_init": "i",
-
- "input_clear": "ctrl+c",
- "input_paste": "ctrl+v",
- "input_submit": "enter",
- "input_newline": "shift+enter,ctrl+j",
-
+ "session_child_cycle": "ctrl+right",
+ "session_child_cycle_reverse": "ctrl+left",
"messages_page_up": "pgup",
"messages_page_down": "pgdown",
"messages_half_page_up": "ctrl+alt+u",
@@ -39,8 +33,18 @@ opencode has a list of keybinds that you can customize through the opencode conf
"messages_first": "ctrl+g",
"messages_last": "ctrl+alt+g",
"messages_copy": "y",
-
- "app_exit": "ctrl+c,q"
+ "messages_undo": "u",
+ "messages_redo": "r",
+ "model_list": "m",
+ "model_cycle_recent": "f2",
+ "model_cycle_recent_reverse": "shift+f2",
+ "agent_list": "a",
+ "agent_cycle": "tab",
+ "agent_cycle_reverse": "shift+tab",
+ "input_clear": "ctrl+c",
+ "input_paste": "ctrl+v",
+ "input_submit": "enter",
+ "input_newline": "shift+enter,ctrl+j"
}
}
```
@@ -65,7 +69,7 @@ You can disable a keybind by adding the key to your config with a value of "none
{
"$schema": "https://opencode.ai/config.json",
"keybinds": {
- "session_compact": "none",
+ "session_compact": "none"
}
}
```
diff --git a/packages/web/src/content/docs/docs/lsp.mdx b/packages/web/src/content/docs/docs/lsp.mdx
index 76edad3ee..d674cc70d 100644
--- a/packages/web/src/content/docs/docs/lsp.mdx
+++ b/packages/web/src/content/docs/docs/lsp.mdx
@@ -3,7 +3,7 @@ title: LSP Servers
description: opencode integrates with your LSP servers.
---
-opencode integrates with your Language Server Protocol (LSP) to help the LLM interacts with your codebase. It uses diagnostics to provide feebdack to the LLM. And _go-to-definition_ and _find-references_ to help navigate your codebase.
+opencode integrates with your Language Server Protocol (LSP) to help the LLM interacts with your codebase. It uses diagnostics to provide feedback to the LLM. And _go-to-definition_ and _find-references_ to help navigate your codebase.
---
diff --git a/packages/web/src/content/docs/docs/models.mdx b/packages/web/src/content/docs/docs/models.mdx
index 5308921a3..e06ab0eab 100644
--- a/packages/web/src/content/docs/docs/models.mdx
+++ b/packages/web/src/content/docs/docs/models.mdx
@@ -64,6 +64,36 @@ If you've configured a [custom provider](/docs/providers#custom), the `provider_
---
+## Configure models
+
+You can globally configure a model's options through the config.
+
+```jsonc title="opencode.jsonc" {7-11}
+{
+ "$schema": "https://opencode.ai/config.json",
+ "provider": {
+ "openai": {
+ "models": {
+ "gpt-5": {
+ "options": {
+ "reasoningEffort": "high",
+ "textVerbosity": "low",
+ "reasoningSummary": "auto",
+ "include": ["reasoning.encrypted_content"]
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+Here we are setting global options for the `gpt-5` model when used through the `openai` provider.
+
+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).
+
+---
+
## Loading models
When opencode starts up, it checks for models in the following priority order:
diff --git a/packages/web/src/content/docs/docs/plugins.mdx b/packages/web/src/content/docs/docs/plugins.mdx
index 08c697a62..22c78b0b3 100644
--- a/packages/web/src/content/docs/docs/plugins.mdx
+++ b/packages/web/src/content/docs/docs/plugins.mdx
@@ -93,13 +93,9 @@ Prevent opencode from reading `.env` files:
```javascript title=".opencode/plugin/env-protection.js"
export const EnvProtection = async ({ client, $ }) => {
return {
- tool: {
- execute: {
- before: async (input, output) => {
- if (input.tool === "read" && output.args.filePath.includes(".env")) {
- throw new Error("Do not read .env files")
- }
- }
+ "tool.execute.before": async (input, output) => {
+ if (input.tool === "read" && output.args.filePath.includes(".env")) {
+ throw new Error("Do not read .env files")
}
}
}
diff --git a/packages/web/src/content/docs/docs/providers.mdx b/packages/web/src/content/docs/docs/providers.mdx
index c6455b1d8..9d7b808c8 100644
--- a/packages/web/src/content/docs/docs/providers.mdx
+++ b/packages/web/src/content/docs/docs/providers.mdx
@@ -614,8 +614,6 @@ In this example:
### OpenAI
-https://platform.openai.com/api-keys
-
1. Head over to the [OpenAI Platform console](https://platform.openai.com/api-keys), click **Create new secret key**, and copy the key.
2. Run `opencode auth login` and select OpenAI.
@@ -761,11 +759,11 @@ https://platform.openai.com/api-keys
---
-### Zhipu AI
+### Z.AI
-1. Head over to the [Zhipu API console](https://z.ai/manage-apikey/apikey-list), create an account, and click **Create a new API key**.
+1. Head over to the [Z.AI API console](https://z.ai/manage-apikey/apikey-list), create an account, and click **Create a new API key**.
-2. Run `opencode auth login` and select **Zhipu AI**.
+2. Run `opencode auth login` and select **Z.AI**.
```bash
$ opencode auth login
@@ -773,12 +771,12 @@ https://platform.openai.com/api-keys
┌ Add credential
│
◆ Select provider
- │ ● Zhipu AI
+ │ ● Z.AI
│ ...
└
```
-3. Enter your Zhipu AI API key.
+3. Enter your Z.AI API key.
```bash
$ opencode auth login
@@ -786,7 +784,7 @@ https://platform.openai.com/api-keys
┌ Add credential
│
◇ Select provider
- │ Zhipu AI
+ │ Z.AI
│
◇ Enter your API key
│ _
diff --git a/packages/web/src/content/docs/docs/sdk.mdx b/packages/web/src/content/docs/docs/sdk.mdx
new file mode 100644
index 000000000..6002d135a
--- /dev/null
+++ b/packages/web/src/content/docs/docs/sdk.mdx
@@ -0,0 +1,314 @@
+---
+title: SDK
+description: JS SDK for the opencode server.
+---
+
+import config from "../../../../config.mjs"
+export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
+
+The opencode [JS/TS SDK](https://www.npmjs.com/package/@opencode-ai/sdk) provides a type-safe client for interacting with the opencode server. You can use it to build custom integrations and control opencode programmatically.
+
+[Learn more](/docs/server) about how the opencode server works.
+
+---
+
+## Install
+
+Install the SDK from npm:
+
+```bash
+npm install @opencode-ai/sdk
+```
+
+---
+
+## Create client
+
+Create a client instance to connect to your opencode server:
+
+```javascript
+import { createOpencodeClient } from "@opencode-ai/sdk"
+
+const client = createOpencodeClient({
+ baseUrl: "http://localhost:4096",
+})
+```
+
+#### Options
+
+| Option | Type | Description | Default |
+| --------------- | ---------- | --------------------------------- | ----------------------- |
+| `baseUrl` | `string` | URL of the opencode server | `http://localhost:4096` |
+| `fetch` | `function` | Custom fetch implementation | `globalThis.fetch` |
+| `parseAs` | `string` | Response parsing method | `auto` |
+| `responseStyle` | `string` | Return style: `data` or `fields` | `fields` |
+| `throwOnError` | `boolean` | Throw errors instead of returning | `false` |
+
+---
+
+## Start server
+
+You can also programmatically start an opencode server:
+
+````javascript
+import { createOpencodeServer } from "@opencode-ai/sdk"
+
+const server = await createOpencodeServer({
+ hostname: "127.0.0.1",
+ port: 4096,
+})
+
+console.log(`Server running at ${server.url}`)
+
+server.close()
+}
+
+#### Options
+
+| Option | Type | Description | Default |
+| ---------- | -------------- | ------------------------------ | ------------- |
+| `hostname` | `string` | Server hostname | `127.0.0.1` |
+| `port` | `number` | Server port | `4096` |
+| `signal` | `AbortSignal` | Abort signal for cancellation | `undefined` |
+| `timeout` | `number` | Timeout in ms for server start | `5000` |
+
+---
+
+## Types
+
+The SDK includes TypeScript definitions for all API types. Import them directly:
+
+```typescript
+import type { Session, Message, Part } from "@opencode-ai/sdk"
+````
+
+All types are generated from the server's OpenAPI specification and available in the types file .
+
+---
+
+## Errors
+
+The SDK throws typed errors that you can catch and handle:
+
+```typescript
+try {
+ const session = await client.session.get({ id: "invalid-id" })
+} catch (error) {
+ console.error("Failed to get session:", error.message)
+}
+```
+
+---
+
+## APIs
+
+The SDK exposes all server APIs through a type-safe client interface.
+
+---
+
+### App
+
+| Method | Description | Response |
+| ------------ | ------------------ | --------------------------------------- |
+| `app.get()` | Get app info | AppConfigProvider[]Session[]SessionSession[]SessionSessionSessionSessionMessagePart[]MessagePart[]MessageMessageSessionSessionSymbol[]File[]Agent[]] [--hostname ]
+```
+
+#### Options
+
+| Flag | Short | Description | Default |
+| ------------ | ----- | --------------------- | ----------- |
+| `--port` | `-p` | Port to listen on | `4096` |
+| `--hostname` | `-h` | Hostname to listen on | `127.0.0.1` |
+
+---
+
+### How it works
+
+When you run `opencode` it starts a TUI and a server. Where the TUI is the
+client that talks to the server. The server exposes an OpenAPI 3.1 spec
+endpoint. This endpoint is also used to generate an [SDK](/docs/sdk).
+
+:::tip
+Use the opencode server to interact with opencode programmatically.
+:::
+
+This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically.
+
+You can run `opencode serve` to start a standalone server. If you have the
+opencode TUI running, `opencode serve` will start a new server.
+
+---
+
+#### Connect to an existing server
+
+When you start the TUI it randomly assigns a port and hostname. You can instead pass in the `--hostname` and `--port` [flags](/docs/cli). Then use this to connect to its server.
+
+The [`/tui`](#tui) endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the opencode [IDE](/docs/ide) plugins.
+
+---
+
+## Spec
+
+The server publishes an OpenAPI 3.1 spec that can be viewed at:
+
+```
+http://:/doc
+```
+
+For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
+
+---
+
+## APIs
+
+The opencode server exposes the following APIs.
+
+---
+
+### App
+
+| Method | Path | Description | Response |
+| ------ | ----------- | ------------------ | --------------------------------------- |
+| `GET` | `/app` | Get app info | AppConfigProvider[] `, default: { [key: string]: string } }` |
+
+---
+
+### Sessions
+
+| Method | Path | Description | Notes |
+| -------- | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET` | `/session` | List sessions | Returns Session[]SessionSession[]SessionSessionSessionSessionMessage `, parts: `Part[] `}[]` |
+| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `Message `, parts: `Part[] `}` |
+| `POST` | `/session/:id/message` | Send chat message | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns MessageMessage` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
+| `GET` | `/find/file?query=` | Find files by name | `string[]` (file paths) |
+| `GET` | `/find/symbol?query=` | Find workspace symbols | Symbol[]` | Read a file | `{ type: "raw" \| "patch", content: string }` |
+| `GET` | `/file/status` | Get status for tracked files | File[]Agent[]
+ ```
+
+---
+
+### AI_APICallError and provider package issues
+
+If you encounter API call errors, this may be due to outdated provider packages. opencode dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.
+
+To resolve provider package issues:
+
+1. Clear the provider package cache:
+
+ ```bash
+ rm -rf ~/.cache/opencode
+ ```
+
+2. Restart opencode to reinstall the latest provider packages
+
+This will force opencode to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.
+
+---
+
### Copy/paste not working on Linux
Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:
@@ -116,4 +154,3 @@ export DISPLAY=:99.0
```
opencode will detect if you're using Wayland and prefer `wl-clipboard`, otherwise it will try to find clipboard tools in order of: `xclip` and `xsel`.
-
diff --git a/packages/web/src/content/docs/docs/tui.mdx b/packages/web/src/content/docs/docs/tui.mdx
new file mode 100644
index 000000000..e6ad10162
--- /dev/null
+++ b/packages/web/src/content/docs/docs/tui.mdx
@@ -0,0 +1,290 @@
+---
+title: TUI
+description: Using the opencode terminal user interface.
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components"
+
+opencode provides an interactive terminal interface or TUI for working on your projects with an LLM.
+
+Running opencode starts the TUI for the current directory.
+
+```bash
+opencode
+```
+
+Or you can start it for a specific working directory.
+
+```bash
+opencode /path/to/project
+```
+
+Once you're in the TUI, you can prompt it with a message.
+
+```text
+Give me a quick summary of the codebase.
+```
+
+:::tip
+You can also use `@` to reference files in your messages.
+:::
+
+```text "@packages/functions/src/api/index.ts"
+How is auth handled in @packages/functions/src/api/index.ts?
+```
+
+---
+
+## Commands
+
+When using the opencode TUI, you can type `/` followed by a command name to quickly execute actions. For example:
+
+```bash frame="none"
+/help
+```
+
+Most commands also have keybind using `ctrl+x` as the leader key, where `ctrl+x` is the default leader key. [Learn more](/docs/keybinds).
+
+Here are all available slash commands:
+
+---
+
+### compact
+
+Compact the current session. _Alias_: `/summarize`
+
+```bash frame="none"
+/compact
+```
+
+**Keybind:** `ctrl+x c`
+
+---
+
+### details
+
+Toggle tool execution details.
+
+```bash frame="none"
+/details
+```
+
+**Keybind:** `ctrl+x d`
+
+---
+
+### editor
+
+Open external editor for composing messages. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup).
+
+```bash frame="none"
+/editor
+```
+
+**Keybind:** `ctrl+x e`
+
+---
+
+### exit
+
+Exit opencode. _Aliases_: `/quit`, `/q`
+
+```bash frame="none"
+/exit
+```
+
+**Keybind:** `ctrl+x q`
+
+---
+
+### export
+
+Export current conversation to Markdown and open in your default editor. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup).
+
+```bash frame="none"
+/export
+```
+
+**Keybind:** `ctrl+x x`
+
+---
+
+### help
+
+Show the help dialog.
+
+```bash frame="none"
+/help
+```
+
+**Keybind:** `ctrl+x h`
+
+---
+
+### init
+
+Create or update `AGENTS.md` file. [Learn more](/docs/rules).
+
+```bash frame="none"
+/init
+```
+
+**Keybind:** `ctrl+x i`
+
+---
+
+### models
+
+List available models.
+
+```bash frame="none"
+/models
+```
+
+**Keybind:** `ctrl+x m`
+
+---
+
+### new
+
+Start a new session. _Alias_: `/clear`
+
+```bash frame="none"
+/new
+```
+
+**Keybind:** `ctrl+x n`
+
+---
+
+### redo
+
+Redo a previously undone message. Only available after using `/undo`.
+
+:::tip
+Any file changes will also be restored.
+:::
+
+```bash frame="none"
+/redo
+```
+
+**Keybind:** `ctrl+x r`
+
+---
+
+### sessions
+
+List and switch between sessions. _Aliases_: `/resume`, `/continue`
+
+```bash frame="none"
+/sessions
+```
+
+**Keybind:** `ctrl+x l`
+
+---
+
+### share
+
+Share current session. [Learn more](/docs/share).
+
+```bash frame="none"
+/share
+```
+
+**Keybind:** `ctrl+x s`
+
+---
+
+### themes
+
+List available themes.
+
+```bash frame="none"
+/themes
+```
+
+**Keybind:** `ctrl+x t`
+
+---
+
+### undo
+
+Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes.
+
+:::tip
+Any file changes made will also be reverted.
+:::
+
+```bash frame="none"
+/undo
+```
+
+**Keybind:** `ctrl+x u`
+
+---
+
+### unshare
+
+Unshare current session. [Learn more](/docs/share#un-sharing).
+
+```bash frame="none"
+/unshare
+```
+
+---
+
+## Bash commands
+
+Start a message with `!` to run a shell command.
+
+```bash frame="none"
+!ls -la
+```
+
+The output of the command is added to the conversation as a tool result.
+
+---
+
+## Editor setup
+
+Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable.
+
+
+
+ ```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
+ $env:EDITOR = "notepad" # or "code", "vim", etc.
+ ```
+
+ To make it permanent, add this to your PowerShell
+ profile.
+
+
+
+
+Popular editor options include:
+
+- `code` - Visual Studio Code
+- `vim` - Vim editor
+- `nano` - Nano editor
+- `notepad` - Windows Notepad
+- `subl` - Sublime Text
diff --git a/sdks/vscode/package.json b/sdks/vscode/package.json
index a3398a255..e69839c88 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.4.40",
+ "version": "0.5.18",
"publisher": "sst-dev",
"repository": {
"type": "git",
diff --git a/sst-env.d.ts b/sst-env.d.ts
index 3af3f82c0..358891fdf 100644
--- a/sst-env.d.ts
+++ b/sst-env.d.ts
@@ -27,10 +27,6 @@ declare module "sst" {
"Bucket": {
"type": "sst.cloudflare.Bucket"
}
- "Console": {
- "type": "sst.cloudflare.StaticSite"
- "url": string
- }
"DATABASE_PASSWORD": {
"type": "sst.sst.Secret"
"value": string
diff --git a/tsconfig.json b/tsconfig.json
index 65fa6c7f3..75ddeff3e 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,5 +1,9 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
"extends": "@tsconfig/bun/tsconfig.json",
- "compilerOptions": {}
+ "compilerOptions": {
+ "customConditions": [
+ "development"
+ ],
+ }
}
+ 
+ 
+ 
+ 
\n`
+ })()
+ const shareUrl = shareId ? `[opencode session](${useShareUrl()}/s/${shareId}) | ` : ""
+ return `\n\n${image}${shareUrl}[github run](${useEnvRunUrl()})`
+}
+
+async function fetchRepo() {
+ const { repo } = useContext()
+ return await octoRest.rest.repos.get({ owner: repo.owner, repo: repo.repo })
+}
+
+async function fetchIssue() {
+ console.log("Fetching prompt data for issue...")
+ const { repo } = useContext()
+ const issueResult = await octoGraph