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