diff options
| -rw-r--r-- | www/astro.config.mjs | 3 | ||||
| -rw-r--r-- | www/src/content/docs/docs/cli.mdx | 99 | ||||
| -rw-r--r-- | www/src/content/docs/docs/config.mdx | 42 | ||||
| -rw-r--r-- | www/src/content/docs/docs/index.mdx | 33 | ||||
| -rw-r--r-- | www/src/content/docs/docs/lsp-servers.mdx | 29 | ||||
| -rw-r--r-- | www/src/content/docs/docs/mcp-servers.mdx | 41 | ||||
| -rw-r--r-- | www/src/content/docs/docs/models.mdx | 82 | ||||
| -rw-r--r-- | www/src/content/docs/docs/shortcuts.mdx | 20 | ||||
| -rw-r--r-- | www/src/content/docs/docs/themes.mdx | 50 |
9 files changed, 195 insertions, 204 deletions
diff --git a/www/astro.config.mjs b/www/astro.config.mjs index 9c25d7db8..0edc80af1 100644 --- a/www/astro.config.mjs +++ b/www/astro.config.mjs @@ -29,6 +29,9 @@ export default defineConfig({ editLink: { baseUrl: `${github}/edit/master/www/`, }, + markdown: { + headingLinks: false, + }, logo: { light: "./src/assets/logo-light.svg", dark: "./src/assets/logo-dark.svg", diff --git a/www/src/content/docs/docs/cli.mdx b/www/src/content/docs/docs/cli.mdx index 9e9796abd..44a56e1fb 100644 --- a/www/src/content/docs/docs/cli.mdx +++ b/www/src/content/docs/docs/cli.mdx @@ -2,75 +2,88 @@ title: CLI --- -## Usage +Once installed you can run the OpenCode CLI. ```bash -# Start OpenCode opencode +``` + +Or pass in flags. For example, to start with debug logging: -# Start with debug logging +```bash opencode -d +``` + +Or start with a specific working directory. -# Start with a specific working directory +```bash opencode -c /path/to/project ``` -## Non-interactive Prompt Mode +## Flags -You can 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. +The OpenCode CLI takes the following flags. -```bash -# Run a single prompt and print the AI's response to the terminal +| 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" +``` -# Get response in JSON format -opencode -p "Explain the use of context in Go" -f json +If you want to run without showing the spinner, use `-q`. -# Run without showing the spinner +```bash "-q" opencode -p "Explain the use of context in Go" -q +``` -# Enable verbose logging to stderr -opencode -p "Explain the use of context in Go" --verbose +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. -# Restrict the agent to only use specific tools -opencode -p "Explain the use of context in Go" --allowedTools=view,ls,glob +#### Tool restrictions -# Prevent the agent from using specific tools -opencode -p "Explain the use of context in Go" --excludedTools=bash,edit -``` +You can control which tools the AI assistant has access to in non-interactive mode. -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. +- `--allowedTools` -### Tool Restrictions + A comma-separated list of tools that the agent is allowed to use. Only these tools will be available. -You can control which tools the AI assistant has access to in non-interactive mode: + ```bash "--allowedTools" + opencode -p "Explain the use of context in Go" --allowedTools=view,ls,glob + ``` -- `--allowedTools`: Comma-separated list of tools that the agent is allowed to use. Only these tools will be available. -- `--excludedTools`: Comma-separated list of tools that the agent is not allowed to use. All other tools will be available. +- `--excludedTools` -These flags are mutually exclusive - you can use either `--allowedTools` or `--excludedTools`, but not both at the same time. + Comma-separated list of tools that the agent is not allowed to use. All other tools will be available. -### Output Formats + ```bash "--excludedTools" + opencode -p "Explain the use of context in Go" --excludedTools=bash,edit + ``` -OpenCode supports the following output formats in non-interactive mode: +These flags are mutually exclusive. So you can either use `--allowedTools` or `--excludedTools`, but not both. -| Format | Description | -| ------ | -------------------------------------- | -| `text` | Plain text output (default) | -| `json` | Output wrapped in a JSON object | +#### Output formats -The output format is implemented as a strongly-typed `OutputFormat` in the codebase, ensuring type safety and validation when processing outputs. +In non-interactive mode, you can also set the CLI to return as JSON using `-f`. -## Command-line Flags +```bash "-f json" +opencode -p "Explain the use of context in Go" -f json +``` -| Flag | Short | Description | -| ----------------- | ----- | ---------------------------------------------------------- | -| `--help` | `-h` | Display help information | -| `--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, 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 | +By default, this is set to `text`, to return plain text. diff --git a/www/src/content/docs/docs/config.mdx b/www/src/content/docs/docs/config.mdx index e6628d6c3..288f194c5 100644 --- a/www/src/content/docs/docs/config.mdx +++ b/www/src/content/docs/docs/config.mdx @@ -2,32 +2,18 @@ title: Config --- -OpenCode looks for configuration in the following locations: +You can configure OpenCode using the OpenCode config. It can be places in: - `$HOME/.opencode.json` - `$XDG_CONFIG_HOME/opencode/.opencode.json` -- `./.opencode.json` (local directory) -## Environment variables - -You can configure OpenCode using environment variables: - -| Environment Variable | Purpose | -| -------------------------- | ------------------------------------------------------ | -| `ANTHROPIC_API_KEY` | For Claude models | -| `OPENAI_API_KEY` | For OpenAI models | -| `GEMINI_API_KEY` | For Google Gemini models | -| `GROQ_API_KEY` | For Groq models | -| `AWS_ACCESS_KEY_ID` | For AWS Bedrock (Claude) | -| `AWS_SECRET_ACCESS_KEY` | For AWS Bedrock (Claude) | -| `AWS_REGION` | For AWS Bedrock (Claude) | -| `AZURE_OPENAI_ENDPOINT` | For Azure OpenAI models | -| `AZURE_OPENAI_API_KEY` | For Azure OpenAI models (optional when using Entra ID) | -| `AZURE_OPENAI_API_VERSION` | For Azure OpenAI models | +Or in the current directory, `./.opencode.json`. ## OpenCode config -```json +The config file has the following structure. + +```json title=".opencode.json" { "data": { "directory": ".opencode" @@ -82,3 +68,21 @@ You can configure OpenCode using environment variables: "debugLSP": false } ``` + +## Environment variables + +For the providers, you can also specify the keys using environment variables. + +| 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 | + diff --git a/www/src/content/docs/docs/index.mdx b/www/src/content/docs/docs/index.mdx index 3b7d6db09..e6f71be19 100644 --- a/www/src/content/docs/docs/index.mdx +++ b/www/src/content/docs/docs/index.mdx @@ -1,16 +1,33 @@ --- -title: Get started +title: Intro --- +OpenCode is an AI coding agent built natively for the terminal. It features: + +- 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 + ## Installation +```bash +npm i -g opencode +``` + +If you don't have NPM installed, you can also install the OpenCode binary through the following. + #### Using the install script ```bash -# Install the latest version curl -fsSL https://opencode.ai/install | bash +``` -# Install a specific version +Or install a specific version. + +```bash curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash ``` @@ -20,13 +37,17 @@ curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash brew install sst/tap/opencode ``` -#### Using AUR (Arch Linux) +#### Using AUR in Arch Linux + +With yay. ```bash -# Using yay yay -S opencode-bin +``` + +Or with paru. -# Using paru +```bash paru -S opencode-bin ``` diff --git a/www/src/content/docs/docs/lsp-servers.mdx b/www/src/content/docs/docs/lsp-servers.mdx index ad6051c5f..cd259dea7 100644 --- a/www/src/content/docs/docs/lsp-servers.mdx +++ b/www/src/content/docs/docs/lsp-servers.mdx @@ -2,19 +2,22 @@ title: LSP servers --- -OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages. +OpenCode integrates with _Language Server Protocol_, or LSP to improve how the LLM interacts with your codebase. -### LSP Features +LSP servers for different languages give the LLM: -- **Multi-language Support**: Connect to language servers for different programming languages -- **Diagnostics**: Receive error checking and linting information -- **File Watching**: Automatically notify language servers of file changes +- **Diagnostics**: These include things like errors and lint warnings. So the LLM can generate code that has fewer mistakes without having to run the code. +- **Quick actions**: The LSP can allow the LLM to better navigate the codebase through features like _go-to-definition_ and _find references_. -### Configuring LSP +## Auto-detection -Language servers are configured in the configuration file under the `lsp` section: +By default, OpenCode will **automatically detect** the languages used in your project and add the right LSP servers. -```json +## Manual configuration + +You can also manually configure LSP servers by adding them under the `lsp` section in your OpenCode config. + +```json title=".opencode.json" { "lsp": { "go": { @@ -28,12 +31,4 @@ Language servers are configured in the configuration file under the `lsp` sectio } } } - -### LSP Integration with AI - -The AI assistant can access LSP features through the `diagnostics` tool, allowing it to: - -- Check for errors in your code -- Suggest fixes based on diagnostics - -While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant. +``` diff --git a/www/src/content/docs/docs/mcp-servers.mdx b/www/src/content/docs/docs/mcp-servers.mdx index 429082ba4..28c6d2ab2 100644 --- a/www/src/content/docs/docs/mcp-servers.mdx +++ b/www/src/content/docs/docs/mcp-servers.mdx @@ -2,31 +2,40 @@ title: MCP servers --- -OpenCode implements the Model Context Protocol (MCP) to extend its capabilities through external tools. MCP provides a standardized way for the AI assistant to interact with external services and tools. +You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both: -### MCP Features +- Local servers that use standard input/output, `stdio` +- Remote servers that use server-sent events `sse` -- **External Tool Integration**: Connect to external tools and services via a standardized protocol -- **Tool Discovery**: Automatically discover available tools from MCP servers -- **Multiple Connection Types**: - - **Stdio**: Communicate with tools via standard input/output - - **SSE**: Communicate with tools via Server-Sent Events -- **Security**: Permission system for controlling access to MCP tools +## Add MCP servers -### Configuring MCP Servers +You can define MCP servers in your OpenCode config under the `mcpServers` section: -MCP servers are defined in the configuration file under the `mcpServers` section: +### Local -```json +To add a local or `stdio` MCP server. + +```json title=".opencode.json" {4} { "mcpServers": { - "example": { + "local-example": { "type": "stdio", "command": "path/to/mcp-server", "env": [], "args": [] - }, - "web-example": { + } + } +} +``` + +### Remote + +To add a remote or `sse` MCP server. + +```json title=".opencode.json" {4} +{ + "mcpServers": { + "remote-example": { "type": "sse", "url": "https://example.com/mcp", "headers": { @@ -37,6 +46,6 @@ MCP servers are defined in the configuration file under the `mcpServers` section } ``` -### MCP Tool Usage +## Usage -Once configured, MCP tools are automatically available to the AI assistant alongside built-in tools. They follow the same permission model as other tools, requiring user approval before execution. +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. diff --git a/www/src/content/docs/docs/models.mdx b/www/src/content/docs/docs/models.mdx index 83ca69916..c40216695 100644 --- a/www/src/content/docs/docs/models.mdx +++ b/www/src/content/docs/docs/models.mdx @@ -2,87 +2,33 @@ title: Models --- -## Supported AI Models +OpenCode uses the [AI SDK](https://ai-sdk.dev/) to have the support for **all the AI models**. -OpenCode supports a variety of AI models from different providers: +Start by setting the [keys for the providers](/docs/config) you want to use in your OpenCode config. -### OpenAI +## Model select -- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano) -- GPT-4.5 Preview -- GPT-4o family (gpt-4o, gpt-4o-mini) -- O1 family (o1, o1-pro, o1-mini) -- O3 family (o3, o3-mini) -- O4 Mini +You can now select the model you want from the menu by hitting `Ctrl+O`. -### Anthropic +## Multiple models -- Claude 3.5 Sonnet -- Claude 3.5 Haiku -- Claude 3.7 Sonnet -- Claude 3 Haiku -- Claude 3 Opus +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. -### Google - -- Gemini 2.5 -- Gemini 2.5 Flash -- Gemini 2.0 Flash -- Gemini 2.0 Flash Lite - -### AWS Bedrock - -- Claude 3.7 Sonnet - -### Groq - -- Llama 4 Maverick (17b-128e-instruct) -- Llama 4 Scout (17b-16e-instruct) -- QWEN QWQ-32b -- Deepseek R1 distill Llama 70b -- Llama 3.3 70b Versatile - -### Azure OpenAI - -- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano) -- GPT-4.5 Preview -- GPT-4o family (gpt-4o, gpt-4o-mini) -- O1 family (o1, o1-mini) -- O3 family (o3, o3-mini) -- O4 Mini - -### Google Cloud VertexAI - -- Gemini 2.5 -- Gemini 2.5 Flash - -## Using Bedrock Models - -To use bedrock models with OpenCode you need three things. - -1. Valid AWS credentials (the env vars: `AWS_SECRET_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_REGION`) -2. Access to the corresponding model in AWS Bedrock in your region. - a. You can request access in the AWS console on the Bedrock -> "Model access" page. -3. A correct configuration file. You don't need the `providers` key. Instead you have to prefix your models per agent with `bedrock.` and then a valid model. For now only Claude 3.7 is supported. - -```json +```json title=".opencode.json" { "agents": { "primary": { - "model": "bedrock.claude-3.7-sonnet", - "maxTokens": 5000, - "reasoningEffort": "" + "model": "gpt-4", + "maxTokens": 5000 }, "task": { - "model": "bedrock.claude-3.7-sonnet", - "maxTokens": 5000, - "reasoningEffort": "" + "model": "gpt-3.5-turbo", + "maxTokens": 5000 }, "title": { - "model": "bedrock.claude-3.7-sonnet", - "maxTokens": 80, - "reasoningEffort": "" + "model": "gpt-3.5-turbo", + "maxTokens": 80 } - }, + } } ``` diff --git a/www/src/content/docs/docs/shortcuts.mdx b/www/src/content/docs/docs/shortcuts.mdx index ece9542c0..dd866e0f3 100644 --- a/www/src/content/docs/docs/shortcuts.mdx +++ b/www/src/content/docs/docs/shortcuts.mdx @@ -4,7 +4,9 @@ sidebar: label: Shortcuts --- -### Global Shortcuts +Below are a list of keyboard shortcuts that OpenCode supports. + +## Global | Shortcut | Action | | -------- | ------------------------------------------------------- | @@ -17,7 +19,7 @@ sidebar: | `Ctrl+O` | Toggle model selection dialog | | `Esc` | Close current overlay/dialog or return to previous mode | -### Chat Page Shortcuts +## Chat pane | Shortcut | Action | | -------- | --------------------------------------- | @@ -26,7 +28,7 @@ sidebar: | `i` | Focus editor (when not in writing mode) | | `Esc` | Exit writing mode and focus messages | -### Editor Shortcuts +## Editor view | Shortcut | Action | | ------------------- | ----------------------------------------- | @@ -35,7 +37,7 @@ sidebar: | `Ctrl+E` | Open external editor | | `Esc` | Blur editor and focus messages | -### Session Dialog Shortcuts +## Session dialog | Shortcut | Action | | ---------- | ---------------- | @@ -44,7 +46,7 @@ sidebar: | `Enter` | Select session | | `Esc` | Close dialog | -### Model Dialog Shortcuts +## Model dialog | Shortcut | Action | | ---------- | ----------------- | @@ -54,7 +56,7 @@ sidebar: | `→` or `l` | Next provider | | `Esc` | Close dialog | -### Permission Dialog Shortcuts +## Permission dialog | Shortcut | Action | | ----------------------- | ---------------------------- | @@ -64,9 +66,3 @@ sidebar: | `a` | Allow permission | | `A` | Allow permission for session | | `d` | Deny permission | - -### Logs Page Shortcuts - -| Shortcut | Action | -| ------------------ | ------------------- | -| `Backspace` or `q` | Return to chat page | diff --git a/www/src/content/docs/docs/themes.mdx b/www/src/content/docs/docs/themes.mdx index 38c7a15fb..e691a22e7 100644 --- a/www/src/content/docs/docs/themes.mdx +++ b/www/src/content/docs/docs/themes.mdx @@ -2,13 +2,13 @@ title: Themes --- -OpenCode supports multiple themes for customizing the appearance of the terminal interface. +OpenCode supports most common terminal themes and you can create your own custom theme. -### Available Themes +## Built-in themes The following predefined themes are available: -- `opencode` (default) +- `opencode` - `catppuccin` - `dracula` - `flexoki` @@ -17,13 +17,15 @@ The following predefined themes are available: - `onedark` - `tokyonight` - `tron` -- `custom` (user-defined) +- `custom` -### Setting a Theme +Where `opencode` is the default theme and `custom` let's you define your own theme. -You can set a theme in your `.opencode.json` configuration file: +## Setting a theme -```json +You can set your theme in your OpenCode config. + +```json title=".opencode.json" { "tui": { "theme": "monokai" @@ -31,11 +33,11 @@ You can set a theme in your `.opencode.json` configuration file: } ``` -### Custom Themes +## Create a theme -You can define your own custom theme by setting the `theme` to `"custom"` and providing color definitions in the `customTheme` map: +You can create your own custom theme by setting the `theme: custom` and providing color definitions through the `customTheme`. -```json +```json title=".opencode.json" { "tui": { "theme": "custom", @@ -49,23 +51,25 @@ You can define your own custom theme by setting the `theme` to `"custom"` and pr } ``` -#### Color Definition Formats +#### Color keys -Custom theme colors support two formats: +You can define any of the following color keys in your `customTheme`. -1. **Simple Hex String**: A single hex color string (e.g., `"#aabbcc"`) that will be used for both light and dark terminal backgrounds. +| Type | Color keys | +| --- | --- | +| Base colors | `primary`, `secondary`, `accent` | +| Status colors | `error`, `warning`, `success`, `info` | +| Text colors | `text`, `textMuted`, `textEmphasized` | +| Background colors | `background`, `backgroundSecondary`, `backgroundDarker` | +| Border colors | `borderNormal`, `borderFocused`, `borderDim` | +| Diff view colors | `diffAdded`, `diffRemoved`, `diffContext`, etc. | -2. **Adaptive Object**: An object with `dark` and `light` keys, each holding a hex color string. This allows for adaptive colors based on the terminal's background. +You don't need to define all the color keys. Any undefined colors will fall back to the default `opencode` theme colors. -#### Available Color Keys +#### Color definitions -You can define any of the following color keys in your `customTheme`: +Color keys can take: -- Base colors: `primary`, `secondary`, `accent` -- Status colors: `error`, `warning`, `success`, `info` -- Text colors: `text`, `textMuted`, `textEmphasized` -- Background colors: `background`, `backgroundSecondary`, `backgroundDarker` -- Border colors: `borderNormal`, `borderFocused`, `borderDim` -- Diff view colors: `diffAdded`, `diffRemoved`, `diffContext`, etc. +1. **Hex string**: A single hex color string, like `"#aabbcc"`, that'll be used for both light and dark terminal backgrounds. -You don't need to define all colors. Any undefined colors will fall back to the default "opencode" theme colors. +2. **Light and dark colors**: An object with `dark` and `light` hex colors that'll be set based on the terminal's background. |