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, and Groq
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
79### Configuration File Structure
80
81```json
82{
83 "data": {
84 "directory": ".opencode"
85 },
86 "providers": {
87 "openai": {
88 "apiKey": "your-api-key",
89 "disabled": false
90 },
91 "anthropic": {
92 "apiKey": "your-api-key",
93 "disabled": false
94 },
95 "groq": {
96 "apiKey": "your-api-key",
97 "disabled": false
98 }
99 },
100 "agents": {
101 "coder": {
102 "model": "claude-3.7-sonnet",
103 "maxTokens": 5000
104 },
105 "task": {
106 "model": "claude-3.7-sonnet",
107 "maxTokens": 5000
108 },
109 "title": {
110 "model": "claude-3.7-sonnet",
111 "maxTokens": 80
112 }
113 },
114 "mcpServers": {
115 "example": {
116 "type": "stdio",
117 "command": "path/to/mcp-server",
118 "env": [],
119 "args": []
120 }
121 },
122 "lsp": {
123 "go": {
124 "disabled": false,
125 "command": "gopls"
126 }
127 },
128 "debug": false,
129 "debugLSP": false
130}
131```
132
133## Supported AI Models
134
135OpenCode supports a variety of AI models from different providers:
136
137### OpenAI
138
139- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
140- GPT-4.5 Preview
141- GPT-4o family (gpt-4o, gpt-4o-mini)
142- O1 family (o1, o1-pro, o1-mini)
143- O3 family (o3, o3-mini)
144- O4 Mini
145
146### Anthropic
147
148- Claude 3.5 Sonnet
149- Claude 3.5 Haiku
150- Claude 3.7 Sonnet
151- Claude 3 Haiku
152- Claude 3 Opus
153
154### Google
155
156- Gemini 2.5
157- Gemini 2.5 Flash
158- Gemini 2.0 Flash
159- Gemini 2.0 Flash Lite
160
161### AWS Bedrock
162
163- Claude 3.7 Sonnet
164
165### Groq
166
167- Llama 4 Maverick (17b-128e-instruct)
168- Llama 4 Scout (17b-16e-instruct)
169- QWEN QWQ-32b
170- Deepseek R1 distill Llama 70b
171- Llama 3.3 70b Versatile
172
173## Usage
174
175```bash
176# Start OpenCode
177opencode
178
179# Start with debug logging
180opencode -d
181
182# Start with a specific working directory
183opencode -c /path/to/project
184```
185
186## Command-line Flags
187
188| Flag | Short | Description |
189| --------- | ----- | ----------------------------- |
190| `--help` | `-h` | Display help information |
191| `--debug` | `-d` | Enable debug mode |
192| `--cwd` | `-c` | Set current working directory |
193
194## Keyboard Shortcuts
195
196### Global Shortcuts
197
198| Shortcut | Action |
199| -------- | ------------------------------------------------------- |
200| `Ctrl+C` | Quit application |
201| `Ctrl+?` | Toggle help dialog |
202| `?` | Toggle help dialog (when not in editing mode) |
203| `Ctrl+L` | View logs |
204| `Ctrl+A` | Switch session |
205| `Ctrl+K` | Command dialog |
206| `Esc` | Close current overlay/dialog or return to previous mode |
207
208### Chat Page Shortcuts
209
210| Shortcut | Action |
211| -------- | --------------------------------------- |
212| `Ctrl+N` | Create new session |
213| `Ctrl+X` | Cancel current operation/generation |
214| `i` | Focus editor (when not in writing mode) |
215| `Esc` | Exit writing mode and focus messages |
216
217### Editor Shortcuts
218
219| Shortcut | Action |
220| ------------------- | ----------------------------------------- |
221| `Ctrl+S` | Send message (when editor is focused) |
222| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
223| `Ctrl+E` | Open external editor |
224| `Esc` | Blur editor and focus messages |
225
226### Session Dialog Shortcuts
227
228| Shortcut | Action |
229| ---------- | ---------------- |
230| `↑` or `k` | Previous session |
231| `↓` or `j` | Next session |
232| `Enter` | Select session |
233| `Esc` | Close dialog |
234
235### Permission Dialog Shortcuts
236
237| Shortcut | Action |
238| ----------------------- | ---------------------------- |
239| `←` or `left` | Switch options left |
240| `→` or `right` or `tab` | Switch options right |
241| `Enter` or `space` | Confirm selection |
242| `a` | Allow permission |
243| `A` | Allow permission for session |
244| `d` | Deny permission |
245
246### Logs Page Shortcuts
247
248| Shortcut | Action |
249| ------------------ | ------------------- |
250| `Backspace` or `q` | Return to chat page |
251
252## AI Assistant Tools
253
254OpenCode's AI assistant has access to various tools to help with coding tasks:
255
256### File and Code Tools
257
258| Tool | Description | Parameters |
259| ------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
260| `glob` | Find files by pattern | `pattern` (required), `path` (optional) |
261| `grep` | Search file contents | `pattern` (required), `path` (optional), `include` (optional), `literal_text` (optional) |
262| `ls` | List directory contents | `path` (optional), `ignore` (optional array of patterns) |
263| `view` | View file contents | `file_path` (required), `offset` (optional), `limit` (optional) |
264| `write` | Write to files | `file_path` (required), `content` (required) |
265| `edit` | Edit files | Various parameters for file editing |
266| `patch` | Apply patches to files | `file_path` (required), `diff` (required) |
267| `diagnostics` | Get diagnostics information | `file_path` (optional) |
268
269### Other Tools
270
271| Tool | Description | Parameters |
272| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
273| `bash` | Execute shell commands | `command` (required), `timeout` (optional) |
274| `fetch` | Fetch data from URLs | `url` (required), `format` (required), `timeout` (optional) |
275| `sourcegraph` | Search code across public repositories | `query` (required), `count` (optional), `context_window` (optional), `timeout` (optional) |
276| `agent` | Run sub-tasks with the AI agent | `prompt` (required) |
277
278## Architecture
279
280OpenCode is built with a modular architecture:
281
282- **cmd**: Command-line interface using Cobra
283- **internal/app**: Core application services
284- **internal/config**: Configuration management
285- **internal/db**: Database operations and migrations
286- **internal/llm**: LLM providers and tools integration
287- **internal/tui**: Terminal UI components and layouts
288- **internal/logging**: Logging infrastructure
289- **internal/message**: Message handling
290- **internal/session**: Session management
291- **internal/lsp**: Language Server Protocol integration
292
293## MCP (Model Context Protocol)
294
295OpenCode 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.
296
297### MCP Features
298
299- **External Tool Integration**: Connect to external tools and services via a standardized protocol
300- **Tool Discovery**: Automatically discover available tools from MCP servers
301- **Multiple Connection Types**:
302 - **Stdio**: Communicate with tools via standard input/output
303 - **SSE**: Communicate with tools via Server-Sent Events
304- **Security**: Permission system for controlling access to MCP tools
305
306### Configuring MCP Servers
307
308MCP servers are defined in the configuration file under the `mcpServers` section:
309
310```json
311{
312 "mcpServers": {
313 "example": {
314 "type": "stdio",
315 "command": "path/to/mcp-server",
316 "env": [],
317 "args": []
318 },
319 "web-example": {
320 "type": "sse",
321 "url": "https://example.com/mcp",
322 "headers": {
323 "Authorization": "Bearer token"
324 }
325 }
326 }
327}
328```
329
330### MCP Tool Usage
331
332Once 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.
333
334## LSP (Language Server Protocol)
335
336OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
337
338### LSP Features
339
340- **Multi-language Support**: Connect to language servers for different programming languages
341- **Diagnostics**: Receive error checking and linting information
342- **File Watching**: Automatically notify language servers of file changes
343
344### Configuring LSP
345
346Language servers are configured in the configuration file under the `lsp` section:
347
348```json
349{
350 "lsp": {
351 "go": {
352 "disabled": false,
353 "command": "gopls"
354 },
355 "typescript": {
356 "disabled": false,
357 "command": "typescript-language-server",
358 "args": ["--stdio"]
359 }
360 }
361}
362```
363
364### LSP Integration with AI
365
366The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
367
368- Check for errors in your code
369- Suggest fixes based on diagnostics
370
371While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
372
373## Development
374
375### Prerequisites
376
377- Go 1.24.0 or higher
378
379### Building from Source
380
381```bash
382# Clone the repository
383git clone https://github.com/opencode-ai/opencode.git
384cd opencode
385
386# Build
387go build -o opencode
388
389# Run
390./opencode
391```
392
393## Acknowledgments
394
395OpenCode gratefully acknowledges the contributions and support from these key individuals:
396
397- [@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
398- [@adamdottv](https://github.com/adamdottv) - For the design direction and UI/UX architecture
399
400Special thanks to the broader open source community whose tools and libraries have made this project possible.
401
402## License
403
404OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
405
406## Contributing
407
408Contributions are welcome! Here's how you can contribute:
409
4101. Fork the repository
4112. Create a feature branch (`git checkout -b feature/amazing-feature`)
4123. Commit your changes (`git commit -m 'Add some amazing feature'`)
4134. Push to the branch (`git push origin feature/amazing-feature`)
4145. Open a Pull Request
415
416Please make sure to update tests as appropriate and follow the existing code style.