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## MCP (Model Context Protocol)
322
323OpenCode 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.
324
325### MCP Features
326
327- **External Tool Integration**: Connect to external tools and services via a standardized protocol
328- **Tool Discovery**: Automatically discover available tools from MCP servers
329- **Multiple Connection Types**:
330 - **Stdio**: Communicate with tools via standard input/output
331 - **SSE**: Communicate with tools via Server-Sent Events
332- **Security**: Permission system for controlling access to MCP tools
333
334### Configuring MCP Servers
335
336MCP servers are defined in the configuration file under the `mcpServers` section:
337
338```json
339{
340 "mcpServers": {
341 "example": {
342 "type": "stdio",
343 "command": "path/to/mcp-server",
344 "env": [],
345 "args": []
346 },
347 "web-example": {
348 "type": "sse",
349 "url": "https://example.com/mcp",
350 "headers": {
351 "Authorization": "Bearer token"
352 }
353 }
354 }
355}
356```
357
358### MCP Tool Usage
359
360Once 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.
361
362## LSP (Language Server Protocol)
363
364OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
365
366### LSP Features
367
368- **Multi-language Support**: Connect to language servers for different programming languages
369- **Diagnostics**: Receive error checking and linting information
370- **File Watching**: Automatically notify language servers of file changes
371
372### Configuring LSP
373
374Language servers are configured in the configuration file under the `lsp` section:
375
376```json
377{
378 "lsp": {
379 "go": {
380 "disabled": false,
381 "command": "gopls"
382 },
383 "typescript": {
384 "disabled": false,
385 "command": "typescript-language-server",
386 "args": ["--stdio"]
387 }
388 }
389}
390```
391
392### LSP Integration with AI
393
394The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
395
396- Check for errors in your code
397- Suggest fixes based on diagnostics
398
399While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
400
401## Development
402
403### Prerequisites
404
405- Go 1.24.0 or higher
406
407### Building from Source
408
409```bash
410# Clone the repository
411git clone https://github.com/opencode-ai/opencode.git
412cd opencode
413
414# Build
415go build -o opencode
416
417# Run
418./opencode
419```
420
421## Acknowledgments
422
423OpenCode gratefully acknowledges the contributions and support from these key individuals:
424
425- [@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
426- [@adamdottv](https://github.com/adamdottv) - For the design direction and UI/UX architecture
427
428Special thanks to the broader open source community whose tools and libraries have made this project possible.
429
430## License
431
432OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
433
434## Contributing
435
436Contributions are welcome! Here's how you can contribute:
437
4381. Fork the repository
4392. Create a feature branch (`git checkout -b feature/amazing-feature`)
4403. Commit your changes (`git commit -m 'Add some amazing feature'`)
4414. Push to the branch (`git push origin feature/amazing-feature`)
4425. Open a Pull Request
443
444Please make sure to update tests as appropriate and follow the existing code style.