3> **⚠️ Early Development Notice:** This project is in early development and is not yet ready for production use. Features may change, break, or be incomplete. Use at your own risk.
5A powerful terminal-based AI assistant for developers, providing intelligent coding assistance directly in your terminal.
9OpenCode is a Go-based CLI application that brings AI assistance to your terminal. It provides a TUI (Terminal User Interface) for interacting with various AI models to help with coding tasks, debugging, and more.
13- **Interactive TUI**: Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) for a smooth terminal experience
14- **Multiple AI Providers**: Support for OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, Groq, Azure OpenAI, and OpenRouter
15- **Session Management**: Save and manage multiple conversation sessions
16- **Tool Integration**: AI can execute commands, search files, and modify code
17- **Vim-like Editor**: Integrated editor with text input capabilities
18- **Persistent Storage**: SQLite database for storing conversations and sessions
19- **LSP Integration**: Language Server Protocol support for code intelligence
20- **File Change Tracking**: Track and visualize file changes during sessions
21- **External Editor Support**: Open your preferred editor for composing messages
25### Using the Install Script
28# Install the latest version
29curl -fsSL https://opencode.ai/install | bash
31# Install a specific version
32curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash
35### Using Homebrew (macOS and Linux)
38brew install opencode-ai/tap/opencode
41### Using AUR (Arch Linux)
54go install github.com/opencode-ai/opencode@latest
59OpenCode looks for configuration in the following locations:
61- `$HOME/.opencode.json`
62- `$XDG_CONFIG_HOME/opencode/.opencode.json`
63- `./.opencode.json` (local directory)
65### Environment Variables
67You can configure OpenCode using environment variables:
69| Environment Variable | Purpose |
70|----------------------------|--------------------------------------------------------|
71| `ANTHROPIC_API_KEY` | For Claude models |
72| `OPENAI_API_KEY` | For OpenAI models |
73| `GEMINI_API_KEY` | For Google Gemini models |
74| `GROQ_API_KEY` | For Groq models |
75| `AWS_ACCESS_KEY_ID` | For AWS Bedrock (Claude) |
76| `AWS_SECRET_ACCESS_KEY` | For AWS Bedrock (Claude) |
77| `AWS_REGION` | For AWS Bedrock (Claude) |
78| `AZURE_OPENAI_ENDPOINT` | For Azure OpenAI models |
79| `AZURE_OPENAI_API_KEY` | For Azure OpenAI models (optional when using Entra ID) |
80| `AZURE_OPENAI_API_VERSION` | For Azure OpenAI models |
83### Configuration File Structure
88 "directory": ".opencode"
92 "apiKey": "your-api-key",
96 "apiKey": "your-api-key",
100 "apiKey": "your-api-key",
104 "apiKey": "your-api-key",
110 "model": "claude-3.7-sonnet",
114 "model": "claude-3.7-sonnet",
118 "model": "claude-3.7-sonnet",
125 "command": "path/to/mcp-server",
141## Supported AI Models
143OpenCode supports a variety of AI models from different providers:
147- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
149- GPT-4o family (gpt-4o, gpt-4o-mini)
150- O1 family (o1, o1-pro, o1-mini)
151- O3 family (o3, o3-mini)
167- Gemini 2.0 Flash Lite
175- Llama 4 Maverick (17b-128e-instruct)
176- Llama 4 Scout (17b-16e-instruct)
178- Deepseek R1 distill Llama 70b
179- Llama 3.3 70b Versatile
183- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
185- GPT-4o family (gpt-4o, gpt-4o-mini)
186- O1 family (o1, o1-mini)
187- O3 family (o3, o3-mini)
196# Start with debug logging
199# Start with a specific working directory
200opencode -c /path/to/project
205| Flag | Short | Description |
206| --------- | ----- | ----------------------------- |
207| `--help` | `-h` | Display help information |
208| `--debug` | `-d` | Enable debug mode |
209| `--cwd` | `-c` | Set current working directory |
216| -------- | ------------------------------------------------------- |
217| `Ctrl+C` | Quit application |
218| `Ctrl+?` | Toggle help dialog |
219| `?` | Toggle help dialog (when not in editing mode) |
220| `Ctrl+L` | View logs |
221| `Ctrl+A` | Switch session |
222| `Ctrl+K` | Command dialog |
223| `Ctrl+O` | Toggle model selection dialog |
224| `Esc` | Close current overlay/dialog or return to previous mode |
226### Chat Page Shortcuts
229| -------- | --------------------------------------- |
230| `Ctrl+N` | Create new session |
231| `Ctrl+X` | Cancel current operation/generation |
232| `i` | Focus editor (when not in writing mode) |
233| `Esc` | Exit writing mode and focus messages |
238| ------------------- | ----------------------------------------- |
239| `Ctrl+S` | Send message (when editor is focused) |
240| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
241| `Ctrl+E` | Open external editor |
242| `Esc` | Blur editor and focus messages |
244### Session Dialog Shortcuts
247| ---------- | ---------------- |
248| `↑` or `k` | Previous session |
249| `↓` or `j` | Next session |
250| `Enter` | Select session |
251| `Esc` | Close dialog |
253### Model Dialog Shortcuts
256| ---------- | ----------------- |
257| `↑` or `k` | Move up |
258| `↓` or `j` | Move down |
259| `←` or `h` | Previous provider |
260| `→` or `l` | Next provider |
261| `Esc` | Close dialog |
263### Permission Dialog Shortcuts
266| ----------------------- | ---------------------------- |
267| `←` or `left` | Switch options left |
268| `→` or `right` or `tab` | Switch options right |
269| `Enter` or `space` | Confirm selection |
270| `a` | Allow permission |
271| `A` | Allow permission for session |
272| `d` | Deny permission |
274### Logs Page Shortcuts
277| ------------------ | ------------------- |
278| `Backspace` or `q` | Return to chat page |
282OpenCode's AI assistant has access to various tools to help with coding tasks:
284### File and Code Tools
286| Tool | Description | Parameters |
287| ------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
288| `glob` | Find files by pattern | `pattern` (required), `path` (optional) |
289| `grep` | Search file contents | `pattern` (required), `path` (optional), `include` (optional), `literal_text` (optional) |
290| `ls` | List directory contents | `path` (optional), `ignore` (optional array of patterns) |
291| `view` | View file contents | `file_path` (required), `offset` (optional), `limit` (optional) |
292| `write` | Write to files | `file_path` (required), `content` (required) |
293| `edit` | Edit files | Various parameters for file editing |
294| `patch` | Apply patches to files | `file_path` (required), `diff` (required) |
295| `diagnostics` | Get diagnostics information | `file_path` (optional) |
299| Tool | Description | Parameters |
300| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
301| `bash` | Execute shell commands | `command` (required), `timeout` (optional) |
302| `fetch` | Fetch data from URLs | `url` (required), `format` (required), `timeout` (optional) |
303| `sourcegraph` | Search code across public repositories | `query` (required), `count` (optional), `context_window` (optional), `timeout` (optional) |
304| `agent` | Run sub-tasks with the AI agent | `prompt` (required) |
308OpenCode is built with a modular architecture:
310- **cmd**: Command-line interface using Cobra
311- **internal/app**: Core application services
312- **internal/config**: Configuration management
313- **internal/db**: Database operations and migrations
314- **internal/llm**: LLM providers and tools integration
315- **internal/tui**: Terminal UI components and layouts
316- **internal/logging**: Logging infrastructure
317- **internal/message**: Message handling
318- **internal/session**: Session management
319- **internal/lsp**: Language Server Protocol integration
323OpenCode supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.
325### Creating Custom Commands
327Custom commands are predefined prompts stored as Markdown files in one of three locations:
3291. **User Commands** (prefixed with `user:`):
331 $XDG_CONFIG_HOME/opencode/commands/
333 (typically `~/.config/opencode/commands/` on Linux/macOS)
338 $HOME/.opencode/commands/
3412. **Project Commands** (prefixed with `project:`):
343 <PROJECT DIR>/.opencode/commands/
346Each `.md` file in these directories becomes a custom command. The file name (without extension) becomes the command ID.
348For example, creating a file at `~/.config/opencode/commands/prime-context.md` with content:
355This creates a command called `user:prime-context`.
359You can create commands that accept arguments by including the `$ARGUMENTS` placeholder in your command file:
362RUN git show $ARGUMENTS
365When you run this command, OpenCode will prompt you to enter the text that should replace `$ARGUMENTS`.
367### Organizing Commands
369You can organize commands in subdirectories:
372~/.config/opencode/commands/git/commit.md
375This creates a command with ID `user:git:commit`.
377### Using Custom Commands
3791. Press `Ctrl+K` to open the command dialog
3802. Select your custom command (prefixed with either `user:` or `project:`)
3813. Press Enter to execute the command
383The content of the command file will be sent as a message to the AI assistant.
385## MCP (Model Context Protocol)
387OpenCode 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.
391- **External Tool Integration**: Connect to external tools and services via a standardized protocol
392- **Tool Discovery**: Automatically discover available tools from MCP servers
393- **Multiple Connection Types**:
394 - **Stdio**: Communicate with tools via standard input/output
395 - **SSE**: Communicate with tools via Server-Sent Events
396- **Security**: Permission system for controlling access to MCP tools
398### Configuring MCP Servers
400MCP servers are defined in the configuration file under the `mcpServers` section:
407 "command": "path/to/mcp-server",
413 "url": "https://example.com/mcp",
415 "Authorization": "Bearer token"
424Once 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.
426## LSP (Language Server Protocol)
428OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
432- **Multi-language Support**: Connect to language servers for different programming languages
433- **Diagnostics**: Receive error checking and linting information
434- **File Watching**: Automatically notify language servers of file changes
438Language servers are configured in the configuration file under the `lsp` section:
449 "command": "typescript-language-server",
456### LSP Integration with AI
458The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
460- Check for errors in your code
461- Suggest fixes based on diagnostics
463While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
471### Building from Source
474# Clone the repository
475git clone https://github.com/opencode-ai/opencode.git
487OpenCode gratefully acknowledges the contributions and support from these key individuals:
489- [@isaacphi](https://github.com/isaacphi) - For the [mcp-language-server](https://github.com/isaacphi/mcp-language-server) project which provided the foundation for our LSP client implementation
490- [@adamdottv](https://github.com/adamdottv) - For the design direction and UI/UX architecture
492Special thanks to the broader open source community whose tools and libraries have made this project possible.
496OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
500Contributions are welcome! Here's how you can contribute:
5021. Fork the repository
5032. Create a feature branch (`git checkout -b feature/amazing-feature`)
5043. Commit your changes (`git commit -m 'Add some amazing feature'`)
5054. Push to the branch (`git push origin feature/amazing-feature`)
5065. Open a Pull Request
508Please make sure to update tests as appropriate and follow the existing code style.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list