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