1# ⌬ OpenCode
2
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.
4
5A powerful terminal-based AI assistant for developers, providing intelligent coding assistance directly in your terminal.
6
7## Overview
8
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.
10
11## Features
12
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
22
23## Installation
24
25### Using the Install Script
26
27```bash
28# Install the latest version
29curl -fsSL https://opencode.ai/install | bash
30
31# Install a specific version
32curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash
33```
34
35### Using Homebrew (macOS and Linux)
36
37```bash
38brew install opencode-ai/tap/opencode
39```
40
41### Using AUR (Arch Linux)
42
43```bash
44# Using yay
45yay -S opencode-bin
46
47# Using paru
48paru -S opencode-bin
49```
50
51### Using Go
52
53```bash
54go install github.com/opencode-ai/opencode@latest
55```
56
57## Configuration
58
59OpenCode looks for configuration in the following locations:
60
61- `$HOME/.opencode.json`
62- `$XDG_CONFIG_HOME/opencode/.opencode.json`
63- `./.opencode.json` (local directory)
64
65### Environment Variables
66
67You can configure OpenCode using environment variables:
68
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 |
81
82
83### Configuration File Structure
84
85```json
86{
87 "data": {
88 "directory": ".opencode"
89 },
90 "providers": {
91 "openai": {
92 "apiKey": "your-api-key",
93 "disabled": false
94 },
95 "anthropic": {
96 "apiKey": "your-api-key",
97 "disabled": false
98 },
99 "groq": {
100 "apiKey": "your-api-key",
101 "disabled": false
102 },
103 "openrouter": {
104 "apiKey": "your-api-key",
105 "disabled": false
106 }
107 },
108 "agents": {
109 "coder": {
110 "model": "claude-3.7-sonnet",
111 "maxTokens": 5000
112 },
113 "task": {
114 "model": "claude-3.7-sonnet",
115 "maxTokens": 5000
116 },
117 "title": {
118 "model": "claude-3.7-sonnet",
119 "maxTokens": 80
120 }
121 },
122 "mcpServers": {
123 "example": {
124 "type": "stdio",
125 "command": "path/to/mcp-server",
126 "env": [],
127 "args": []
128 }
129 },
130 "lsp": {
131 "go": {
132 "disabled": false,
133 "command": "gopls"
134 }
135 },
136 "debug": false,
137 "debugLSP": false
138}
139```
140
141## Supported AI Models
142
143OpenCode supports a variety of AI models from different providers:
144
145### OpenAI
146
147- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
148- GPT-4.5 Preview
149- GPT-4o family (gpt-4o, gpt-4o-mini)
150- O1 family (o1, o1-pro, o1-mini)
151- O3 family (o3, o3-mini)
152- O4 Mini
153
154### Anthropic
155
156- Claude 3.5 Sonnet
157- Claude 3.5 Haiku
158- Claude 3.7 Sonnet
159- Claude 3 Haiku
160- Claude 3 Opus
161
162### Google
163
164- Gemini 2.5
165- Gemini 2.5 Flash
166- Gemini 2.0 Flash
167- Gemini 2.0 Flash Lite
168
169### AWS Bedrock
170
171- Claude 3.7 Sonnet
172
173### Groq
174
175- Llama 4 Maverick (17b-128e-instruct)
176- Llama 4 Scout (17b-16e-instruct)
177- QWEN QWQ-32b
178- Deepseek R1 distill Llama 70b
179- Llama 3.3 70b Versatile
180
181### Azure OpenAI
182
183- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
184- GPT-4.5 Preview
185- GPT-4o family (gpt-4o, gpt-4o-mini)
186- O1 family (o1, o1-mini)
187- O3 family (o3, o3-mini)
188- O4 Mini
189
190## Usage
191
192```bash
193# Start OpenCode
194opencode
195
196# Start with debug logging
197opencode -d
198
199# Start with a specific working directory
200opencode -c /path/to/project
201```
202
203## Command-line Flags
204
205| Flag | Short | Description |
206| --------- | ----- | ----------------------------- |
207| `--help` | `-h` | Display help information |
208| `--debug` | `-d` | Enable debug mode |
209| `--cwd` | `-c` | Set current working directory |
210
211## Keyboard Shortcuts
212
213### Global Shortcuts
214
215| Shortcut | Action |
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 |
225
226### Chat Page Shortcuts
227
228| Shortcut | Action |
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 |
234
235### Editor Shortcuts
236
237| Shortcut | Action |
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 |
243
244### Session Dialog Shortcuts
245
246| Shortcut | Action |
247| ---------- | ---------------- |
248| `↑` or `k` | Previous session |
249| `↓` or `j` | Next session |
250| `Enter` | Select session |
251| `Esc` | Close dialog |
252
253### Model Dialog Shortcuts
254
255| Shortcut | Action |
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 |
262
263### Permission Dialog Shortcuts
264
265| Shortcut | Action |
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 |
273
274### Logs Page Shortcuts
275
276| Shortcut | Action |
277| ------------------ | ------------------- |
278| `Backspace` or `q` | Return to chat page |
279
280## AI Assistant Tools
281
282OpenCode's AI assistant has access to various tools to help with coding tasks:
283
284### File and Code Tools
285
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) |
296
297### Other Tools
298
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) |
305
306## Architecture
307
308OpenCode is built with a modular architecture:
309
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
320
321## Custom Commands
322
323OpenCode supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.
324
325### Creating Custom Commands
326
327Custom commands are predefined prompts stored as Markdown files in one of three locations:
328
3291. **User Commands** (prefixed with `user:`):
330 ```
331 $XDG_CONFIG_HOME/opencode/commands/
332 ```
333 (typically `~/.config/opencode/commands/` on Linux/macOS)
334
335 or
336
337 ```
338 $HOME/.opencode/commands/
339 ```
340
3412. **Project Commands** (prefixed with `project:`):
342 ```
343 <PROJECT DIR>/.opencode/commands/
344 ```
345
346Each `.md` file in these directories becomes a custom command. The file name (without extension) becomes the command ID.
347
348For example, creating a file at `~/.config/opencode/commands/prime-context.md` with content:
349
350```markdown
351RUN git ls-files
352READ README.md
353```
354
355This creates a command called `user:prime-context`.
356
357### Command Arguments
358
359You can create commands that accept arguments by including the `$ARGUMENTS` placeholder in your command file:
360
361```markdown
362RUN git show $ARGUMENTS
363```
364
365When you run this command, OpenCode will prompt you to enter the text that should replace `$ARGUMENTS`.
366
367### Organizing Commands
368
369You can organize commands in subdirectories:
370
371```
372~/.config/opencode/commands/git/commit.md
373```
374
375This creates a command with ID `user:git:commit`.
376
377### Using Custom Commands
378
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
382
383The content of the command file will be sent as a message to the AI assistant.
384
385## MCP (Model Context Protocol)
386
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.
388
389### MCP Features
390
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
397
398### Configuring MCP Servers
399
400MCP servers are defined in the configuration file under the `mcpServers` section:
401
402```json
403{
404 "mcpServers": {
405 "example": {
406 "type": "stdio",
407 "command": "path/to/mcp-server",
408 "env": [],
409 "args": []
410 },
411 "web-example": {
412 "type": "sse",
413 "url": "https://example.com/mcp",
414 "headers": {
415 "Authorization": "Bearer token"
416 }
417 }
418 }
419}
420```
421
422### MCP Tool Usage
423
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.
425
426## LSP (Language Server Protocol)
427
428OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
429
430### LSP Features
431
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
435
436### Configuring LSP
437
438Language servers are configured in the configuration file under the `lsp` section:
439
440```json
441{
442 "lsp": {
443 "go": {
444 "disabled": false,
445 "command": "gopls"
446 },
447 "typescript": {
448 "disabled": false,
449 "command": "typescript-language-server",
450 "args": ["--stdio"]
451 }
452 }
453}
454```
455
456### LSP Integration with AI
457
458The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
459
460- Check for errors in your code
461- Suggest fixes based on diagnostics
462
463While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
464
465## Development
466
467### Prerequisites
468
469- Go 1.24.0 or higher
470
471### Building from Source
472
473```bash
474# Clone the repository
475git clone https://github.com/opencode-ai/opencode.git
476cd opencode
477
478# Build
479go build -o opencode
480
481# Run
482./opencode
483```
484
485## Acknowledgments
486
487OpenCode gratefully acknowledges the contributions and support from these key individuals:
488
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
491
492Special thanks to the broader open source community whose tools and libraries have made this project possible.
493
494## License
495
496OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
497
498## Contributing
499
500Contributions are welcome! Here's how you can contribute:
501
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
507
508Please make sure to update tests as appropriate and follow the existing code style.