aljaz/opencode
1
0
Fork 0
mirror of https://github.com/aljazceru/opencode.git synced 2025-12-22 18:24:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: edits

Browse Source
This commit is contained in:
Jay V
2025-06-19 16:26:58 -04:00
parent f5e7f079ea
commit 44fe012812
20 changed files with 454 additions and 500 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
packages/web/src/content/docs/docs/cli.mdx
View File

@@ -2,88 +2,119 @@
title: CLI
---
Once installed you can run the OpenCode CLI.
Running the opencode CLI starts it for the current directory.
```bash
opencode
```
Or pass in flags. For example, to start with debug logging:
Or you can start it for a specific working directory.
```bash
opencode -d
opencode /path/to/project
```
Or start with a specific working directory.
---
## Commands
The opencode CLI also has the following commands.
### run
Run opencode in non-interactive mode by passing a prompt directly.
```bash
opencode -c /path/to/project
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` | Mode to use in the form of provider/model |
---
### auth
Command to manage credentials and login for providers.
```bash
opencode auth [command]
```
#### login
Logs you into a provider and saves them in the credentials file in `~/.local/share/opencode/auth.json`.
```bash
opencode auth login
```
When opencode starts up it will loads the providers from the credentials file. And if there are any keys defined in your environments or a `.env` file in your project.
#### list
Lists all the authenticated providers as stored in the credentials file.
```bash
opencode auth list
```
Or the short version.
```bash
opencode auth ls
```
#### logout
Logs you out of a provider by clearing it from the credentials file.
```bash
opencode auth logout
```
---
### upgrade
Updates opencode to the latest version or a specific version.
```bash
opencode upgrade [target]
```
To upgrade to the latest version.
```bash
opencode upgrade
```
To upgrade to a specific version.
```bash
opencode upgrade v0.1.48
```
---
## Flags
The OpenCode CLI takes the following flags.
The opencode CLI takes the following flags.
| Flag | Short | Description |
| ----------------- | ----- | -------------------------------------------------------- |
| `--help` | `-h` | Display help |
| `--debug` | `-d` | Enable debug mode |
| `--cwd` | `-c` | Set current working directory |
| `--prompt` | `-p` | Run a single prompt in non-interactive mode |
| `--output-format` | `-f` | Output format for non-interactive mode, `text` or `json` |
| `--quiet` | `-q` | Hide spinner in non-interactive mode |
| `--verbose` | | Display logs to stderr in non-interactive mode |
| `--allowedTools` | | Restrict the agent to only use specified tools |
| `--excludedTools` | | Prevent the agent from using specified tools |
## Non-interactive
By default, OpenCode runs in interactive mode.
But you can also run OpenCode in non-interactive mode by passing a prompt directly as a command-line argument. This is useful for scripting, automation, or when you want a quick answer without launching the full TUI.
For example, to run a single prompt use the `-p` flag.
```bash "-p"
opencode -p "Explain the use of context in Go"
```
If you want to run without showing the spinner, use `-q`.
```bash "-q"
opencode -p "Explain the use of context in Go" -q
```
In this mode, OpenCode will process your prompt, print the result to standard output, and then exit. All **permissions are auto-approved** for the session.
#### Tool restrictions
You can control which tools the AI assistant has access to in non-interactive mode.
- `--allowedTools`
A comma-separated list of tools that the agent is allowed to use. Only these tools will be available.
```bash "--allowedTools"
opencode -p "Explain the use of context in Go" --allowedTools=view,ls,glob
```
- `--excludedTools`
Comma-separated list of tools that the agent is not allowed to use. All other tools will be available.
```bash "--excludedTools"
opencode -p "Explain the use of context in Go" --excludedTools=bash,edit
```
These flags are mutually exclusive. So you can either use `--allowedTools` or `--excludedTools`, but not both.
#### Output formats
In non-interactive mode, you can also set the CLI to return as JSON using `-f`.
```bash "-f json"
opencode -p "Explain the use of context in Go" -f json
```
By default, this is set to `text`, to return plain text.
| Flag | Short | Description |
| ----------------- | ----- | --------------------- |
| `--help` | `-h` | Display help |
| `--version` | | Print version number |
| `--print-logs` | | Print logs to stderr |

92
packages/web/src/content/docs/docs/config.mdx
View File

@@ -2,86 +2,28 @@
title: Config
---
You can configure OpenCode using the OpenCode config. It can be places in:
You can configure opencode using a JSON config file that can be placed in:
- `$HOME/.opencode.json`
- `$XDG_CONFIG_HOME/opencode/.opencode.json`
- Globally under `~/.config/opencode/config.json`.
- Your project root under `opencode.json`. This is safe to checked into Git and uses the same schema as the global one.
Or in the current directory, `./.opencode.json`.
## OpenCode config
The config file has the following structure.
```json title=".opencode.json"
```json
{
"data": {
"directory": ".opencode"
},
"providers": {
"openai": {
"apiKey": "your-api-key",
"disabled": false
},
"anthropic": {
"apiKey": "your-api-key",
"disabled": false
},
"groq": {
"apiKey": "your-api-key",
"disabled": false
},
"openrouter": {
"apiKey": "your-api-key",
"disabled": false
}
},
"agents": {
"primary": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000
},
"task": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000
},
"title": {
"model": "claude-3.7-sonnet",
"maxTokens": 80
}
},
"mcpServers": {
"example": {
"type": "stdio",
"command": "path/to/mcp-server",
"env": [],
"args": []
}
},
"lsp": {
"go": {
"disabled": false,
"command": "gopls"
}
},
"debug": false,
"debugLSP": false
"$schema": "https://opencode.ai/config.json",
"theme": "opencode",
"model": "anthropic/claude-sonnet-4-20250514",
"autoshare": false,
"autoupdate": true
}
```
## Environment variables
In most cases, you'll want to use the global config for things like themes, providers, or keybinds. Having a config per project is useful if you are using different providers for your company.
For the providers, you can also specify the keys using environment variables.
When opencode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
| Environment Variable | Models |
| -------------------------- | ------------------------------------------ |
| `ANTHROPIC_API_KEY` | Claude |
| `OPENAI_API_KEY` | OpenAI |
| `GEMINI_API_KEY` | Google Gemini |
| `GROQ_API_KEY` | Groq |
| `AWS_ACCESS_KEY_ID` | Amazon Bedrock |
| `AWS_SECRET_ACCESS_KEY` | Amazon Bedrock |
| `AWS_REGION` | Amazon Bedrock |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI, optional when using Entra ID |
| `AZURE_OPENAI_API_VERSION` | Azure OpenAI |
## Schema
The config file has a schema that's defined in [**`opencode.ai/config.json`**](https://opencode.ai/config.json).
Your editor should be able to validate and autocomplete based on the schema.

88
packages/web/src/content/docs/docs/index.mdx
View File

@@ -2,57 +2,85 @@
title: Intro
---
OpenCode is an AI coding agent built natively for the terminal. It features:
import { Tabs, TabItem } from '@astrojs/starlight/components';
- Native TUI for a smoother, snappier experience
- Uses LSPs to help the LLM make fewer mistakes
- Opening multiple conversations with the same project
- Use of any model through the AI SDK
- Tracks and visualizes all the file changes
- Editing longer messages with Vim
[**opencode**](/) is an AI coding agent built for the terminal. It features:
- A responsive, native, themeable terminal UI.
- Automatically loads the right LSPs, so the LLMs make fewer mistakes.
- Have multiple agents working in parallel on the same project.
- Create shareable links to any session for reference or to debug.
- Log in with Anthropic to use your Claude Pro or Claude Max account.
- Supports 75+ LLM providers through [Models.dev](https://models.dev), including local models.
## Installation
```bash
npm i -g opencode
```
<Tabs>
<TabItem label="npm">
```bash
npm install -g opencode-ai
```
</TabItem>
<TabItem label="Bun">
```bash
bun install -g opencode-ai
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm install -g opencode-ai
```
</TabItem>
<TabItem label="Yarn">
```bash
yarn global add opencode-ai
```
</TabItem>
</Tabs>
If you don't have NPM installed, you can also install the OpenCode binary through the following.
You can also install the opencode binary through the following.
#### Using the install script
##### Using the install script
```bash
curl -fsSL https://opencode.ai/install | bash
```
Or install a specific version.
```bash
curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash
```
#### Using Homebrew on macOS and Linux
##### Using Homebrew on macOS
```bash
brew install sst/tap/opencode
```
#### Using AUR in Arch Linux
With yay.
```bash
yay -S opencode-bin
```
Or with paru.
##### Using Paru on Arch Linux
```bash
paru -S opencode-bin
```
#### Using Go
## Providers
We recommend signing up for Claude Pro or Max, running `opencode auth login` and selecting Anthropic. It's the most cost-effective way to use opencode.
```bash
go install github.com/sst/opencode@latest
$ opencode auth login
┌ Add credential
│
◆ Select provider
│ ● Anthropic (recommended)
│ ○ OpenAI
│ ○ Google
│ ○ Amazon Bedrock
│ ○ Azure
│ ○ DeepSeek
│ ○ Groq
│ ...
└
```
opencode is powered by the provider list at [Models.dev](https://models.dev), so you can use `opencode auth login` to configure API keys for any provider you'd like to use. This is stored in `~/.local/share/opencode/auth.json`.
The Models.dev dataset is also used to detect common environment variables like `OPENAI_API_KEY` to autoload that provider.
If there are additional providers you want to use you can submit a PR to the [Models.dev repo](https://github.com/sst/models.dev). You can also [add them to your config](/docs/config) for yourself.

48
packages/web/src/content/docs/docs/keybinds.mdx Normal file
View File

@@ -0,0 +1,48 @@
---
title: Keybinds
---
opencode has a list of keybinds that you can customize through the opencode config.
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"keybinds": {
"leader": "ctrl+x",
"help": "<leader>h",
"editor_open": "<leader>e",
"session_new": "<leader>n",
"session_list": "<leader>l",
"session_share": "<leader>s",
"session_interrupt": "esc",
"session_compact": "<leader>c",
"tool_details": "<leader>d",
"model_list": "<leader>m",
"theme_list": "<leader>t",
"project_init": "<leader>i",
"input_clear": "ctrl+c",
"input_paste": "ctrl+v",
"input_submit": "enter",
"input_newline": "shift+enter,ctrl+j",
"history_previous": "up",
"history_next": "down",
"messages_page_up": "pgup",
"messages_page_down": "pgdown",
"messages_half_page_up": "ctrl+alt+u",
"messages_half_page_down": "ctrl+alt+d",
"messages_previous": "ctrl+alt+k",
"messages_next": "ctrl+alt+j",
"messages_first": "ctrl+g",
"messages_last": "ctrl+alt+g",
"app_exit": "ctrl+c,<leader>q"
}
}
```
## Leader key
opencode uses a `leader` key for most keybinds. This avoids conflicts in your terminal.
By default, `ctrl+x` is the leader key and most actions require you to first press the leader key and then the shortcut. For example, to start a new session you first press `ctrl+x` and then press `n`.
You don't need to use a leader key for your keybinds but we recommend doing so.

8
packages/web/src/content/docs/docs/lsp-servers.mdx
View File

@@ -2,7 +2,7 @@
title: LSP servers
---
OpenCode integrates with _Language Server Protocol_, or LSP to improve how the LLM interacts with your codebase.
opencode integrates with _Language Server Protocol_, or LSP to improve how the LLM interacts with your codebase.
LSP servers for different languages give the LLM:
@@ -11,13 +11,13 @@ LSP servers for different languages give the LLM:
## Auto-detection
By default, OpenCode will **automatically detect** the languages used in your project and add the right LSP servers.
By default, opencode will **automatically detect** the languages used in your project and add the right LSP servers.
## Manual configuration
You can also manually configure LSP servers by adding them under the `lsp` section in your OpenCode config.
You can also manually configure LSP servers by adding them under the `lsp` section in your opencode config.
```json title=".opencode.json"
```json title="opencode.json"
{
"lsp": {
"go": {

52
packages/web/src/content/docs/docs/mcp-servers.mdx
View File

@@ -2,27 +2,33 @@
title: MCP servers
---
You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both:
You can add external tools to opencode using the _Model Context Protocol_, or MCP. opencode supports both:
- Local servers that use standard input/output, `stdio`
- Remote servers that use server-sent events `sse`
- Local servers
- And remote servers
## Add MCP servers
Once added, MCP tools are automatically available to the LLM alongside built-in tools.
You can define MCP servers in your OpenCode config under the `mcpServers` section:
---
## Configure
You can define MCP servers in your opencode config under `mcp`.
### Local
To add a local or `stdio` MCP server.
Add a local MCP servers under `mcp.localmcp`.
```json title=".opencode.json" {4}
```json title="opencode.json"
{
"mcpServers": {
"local-example": {
"type": "stdio",
"command": "path/to/mcp-server",
"env": [],
"args": []
"$schema": "https://opencode.ai/config.json",
"mcp": {
"localmcp": {
"type": "local",
"command": ["bun", "x", "my-mcp-command"],
"environment": {
"MY_ENV_VAR": "my_env_var_value"
}
}
}
}
@@ -30,22 +36,16 @@ To add a local or `stdio` MCP server.
### Remote
To add a remote or `sse` MCP server.
Add a remote MCP servers under `mcp.remotemcp`.
```json title=".opencode.json" {4}
```json title="opencode.json"
{
"mcpServers": {
"remote-example": {
"type": "sse",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer token"
}
"$schema": "https://opencode.ai/config.json",
"mcp": {
"remotemcp": {
"type": "remote",
"url": "https://my-mcp-server.com"
}
}
}
```
## Usage
Once added, MCP tools are automatically available to the LLM alongside built-in tools. They follow the same permission model; requiring user approval before execution.

93
packages/web/src/content/docs/docs/models.mdx
View File

@@ -2,33 +2,88 @@
title: Models
---
OpenCode uses the [AI SDK](https://ai-sdk.dev/) to have the support for **all the AI models**.
opencode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support for **75+ LLM providers** and it supports running local models.
Start by setting the [keys for the providers](/docs/config) you want to use in your OpenCode config.
---
## Model select
## Providers
You can now select the model you want from the menu by hitting `Ctrl+O`.
You can configure providers in your opencode config under the `provider` section.
## Multiple models
### Defaults
You can also use specific models for specific tasks. For example, you can use a smaller model to generate the title of the conversation or to run a sub task.
Most popular providers are preloaded by default. If you've added the credentials for a provider through `opencode auth login`, they'll be available when you start opencode.
```json title=".opencode.json"
### Custom
You can add custom providers by specifying the npm package for the provider and the models you want to use.
```json title="opencode.json" {5,9-11}
{
"agents": {
"primary": {
"model": "gpt-4",
"maxTokens": 5000
},
"task": {
"model": "gpt-3.5-turbo",
"maxTokens": 5000
},
"title": {
"model": "gpt-3.5-turbo",
"maxTokens": 80
"$schema": "https://opencode.ai/config.json",
"provider": {
"openrouter": {
"npm": "@openrouter/ai-sdk-provider",
"name": "OpenRouter",
"options": {},
"models": {
"anthropic/claude-3.5-sonnet": {
"name": "Claude 3.5 Sonnet"
}
}
}
}
}
```
### Local
To configure a local model, specify the npm package to use and the `baseURL`.
```json title="opencode.json" {5,7}
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"llama2": {}
}
}
}
}
```
---
## Select a model
If you have multiple models, you can select the model you want by typing in:
```bash frame="none"
/models
```
---
## Loading models
When opencode starts up, it checks for the following:
1. The model list in the opencode config.
```json title="opencode.json" {4}
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-20250514"
}
```
The format here is `provider/model`.
2. The last used model.
3. The first model using an internal priority.

68
packages/web/src/content/docs/docs/shortcuts.mdx
View File

@@ -1,68 +0,0 @@
---
title: Keyboard shortcuts
sidebar:
label: Shortcuts
---
Below are a list of keyboard shortcuts that OpenCode supports.
## Global
| Shortcut | Action |
| -------- | ------------------------------------------------------- |
| `Ctrl+C` | Quit application |
| `Ctrl+?` | Toggle help dialog |
| `?` | Toggle help dialog (when not in editing mode) |
| `Ctrl+L` | View logs |
| `Ctrl+A` | Switch session |
| `Ctrl+K` | Command dialog |
| `Ctrl+O` | Toggle model selection dialog |
| `Esc` | Close current overlay/dialog or return to previous mode |
## Chat pane
| Shortcut | Action |
| -------- | --------------------------------------- |
| `Ctrl+N` | Create new session |
| `Ctrl+X` | Cancel current operation/generation |
| `i` | Focus editor (when not in writing mode) |
| `Esc` | Exit writing mode and focus messages |
## Editor view
| Shortcut | Action |
| ------------------- | ----------------------------------------- |
| `Ctrl+S` | Send message (when editor is focused) |
| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
| `Ctrl+E` | Open external editor |
| `Esc` | Blur editor and focus messages |
## Session dialog
| Shortcut | Action |
| ---------- | ---------------- |
| `↑` or `k` | Previous session |
| `↓` or `j` | Next session |
| `Enter` | Select session |
| `Esc` | Close dialog |
## Model dialog
| Shortcut | Action |
| ---------- | ----------------- |
| `↑` or `k` | Move up |
| `↓` or `j` | Move down |
| `←` or `h` | Previous provider |
| `→` or `l` | Next provider |
| `Esc` | Close dialog |
## Permission dialog
| Shortcut | Action |
| ----------------------- | ---------------------------- |
| `←` or `left` | Switch options left |
| `→` or `right` or `tab` | Switch options right |
| `Enter` or `space` | Confirm selection |
| `a` | Allow permission |
| `A` | Allow permission for session |
| `d` | Deny permission |

83
packages/web/src/content/docs/docs/themes.mdx
View File

@@ -2,74 +2,47 @@
title: Themes
---
OpenCode supports most common terminal themes and you can create your own custom theme.
opencode will support most common terminal themes and you'll soon be able to create your own custom theme.
## Built-in themes
---
The following predefined themes are available:
## Built-in
The following built-in themes are available:
- `opencode`
- `catppuccin`
- `dracula`
- `flexoki`
- `gruvbox`
- `monokai`
- `onedark`
![opencode theme](../../../assets/themes/opencode.png)
- `ayu`
![ayu theme](../../../assets/themes/ayu.png)
- `everforest`
![everforest theme](../../../assets/themes/everforest.png)
- `tokyonight`
- `tron`
- `custom`
Where `opencode` is the default theme and `custom` let's you define your own theme.
![tokyonight theme](../../../assets/themes/tokyonight.png)
## Setting a theme
---
You can set your theme in your OpenCode config.
## Configure
```json title=".opencode.json"
{
"tui": {
"theme": "monokai"
}
}
To select a theme, type in:
```bash frame="none"
/themes
```
## Create a theme
Your selected theme will be used the next time you start opencode.
You can create your own custom theme by setting the `theme: custom` and providing color definitions through the `customTheme`.
You can also configure it in your opencode config.
```json title=".opencode.json"
```json title="opencode.json" {3}
{
"tui": {
"theme": "custom",
"customTheme": {
"primary": "#ffcc00",
"secondary": "#00ccff",
"accent": { "dark": "#aa00ff", "light": "#ddccff" },
"error": "#ff0000"
}
}
"$schema": "https://opencode.ai/config.json",
"theme": "tokyonight"
}
```
#### Color keys
You can define any of the following color keys in your `customTheme`.
| Type | Color keys |
| ----------------- | ------------------------------------------------------- |
| Base colors | `primary`, `secondary`, `accent` |
| Status colors | `error`, `warning`, `success`, `info` |
| Text colors | `text`, `textMuted` |
| Background colors | `background`, `backgroundSubtle`, `backgroundElement` |
| Border colors | `border`, `borderActive`, `borderSubtle` |
| Diff view colors | `diffAdded`, `diffRemoved`, `diffContext`, etc. |
You don't need to define all the color keys. Any undefined colors will fall back to the default `opencode` theme colors.
#### Color definitions
Color keys can take:
1. **Hex string**: A single hex color string, like `"#aabbcc"`, that'll be used for both light and dark terminal backgrounds.
2. **Light and dark colors**: An object with `dark` and `light` hex colors that'll be set based on the terminal's background.

4
packages/web/src/content/docs/index.mdx
View File

@@ -1,5 +1,5 @@
---
title: OpenCode
title: opencode
description: The AI coding agent built for the terminal.
template: splash
hero:
@@ -8,5 +8,5 @@ hero:
image:
dark: ../../assets/logo-dark.svg
light: ../../assets/logo-light.svg
alt: OpenCode logo
alt: opencode logo
---