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### Auto Compact Feature
66
67OpenCode includes an auto compact feature that automatically summarizes your conversation when it approaches the model's context window limit. When enabled (default setting), this feature:
68
69- Monitors token usage during your conversation
70- Automatically triggers summarization when usage reaches 95% of the model's context window
71- Creates a new session with the summary, allowing you to continue your work without losing context
72- Helps prevent "out of context" errors that can occur with long conversations
73
74You can enable or disable this feature in your configuration file:
75
76```json
77{
78 "autoCompact": true // default is true
79}
80```
81
82### Environment Variables
83
84You can configure OpenCode using environment variables:
85
86| Environment Variable | Purpose |
87| -------------------------- | ------------------------------------------------------ |
88| `ANTHROPIC_API_KEY` | For Claude models |
89| `OPENAI_API_KEY` | For OpenAI models |
90| `GEMINI_API_KEY` | For Google Gemini models |
91| `GROQ_API_KEY` | For Groq models |
92| `AWS_ACCESS_KEY_ID` | For AWS Bedrock (Claude) |
93| `AWS_SECRET_ACCESS_KEY` | For AWS Bedrock (Claude) |
94| `AWS_REGION` | For AWS Bedrock (Claude) |
95| `AZURE_OPENAI_ENDPOINT` | For Azure OpenAI models |
96| `AZURE_OPENAI_API_KEY` | For Azure OpenAI models (optional when using Entra ID) |
97| `AZURE_OPENAI_API_VERSION` | For Azure OpenAI models |
98
99### Configuration File Structure
100
101```json
102{
103 "data": {
104 "directory": ".opencode"
105 },
106 "providers": {
107 "openai": {
108 "apiKey": "your-api-key",
109 "disabled": false
110 },
111 "anthropic": {
112 "apiKey": "your-api-key",
113 "disabled": false
114 },
115 "groq": {
116 "apiKey": "your-api-key",
117 "disabled": false
118 },
119 "openrouter": {
120 "apiKey": "your-api-key",
121 "disabled": false
122 }
123 },
124 "agents": {
125 "coder": {
126 "model": "claude-3.7-sonnet",
127 "maxTokens": 5000
128 },
129 "task": {
130 "model": "claude-3.7-sonnet",
131 "maxTokens": 5000
132 },
133 "title": {
134 "model": "claude-3.7-sonnet",
135 "maxTokens": 80
136 }
137 },
138 "mcpServers": {
139 "example": {
140 "type": "stdio",
141 "command": "path/to/mcp-server",
142 "env": [],
143 "args": []
144 }
145 },
146 "lsp": {
147 "go": {
148 "disabled": false,
149 "command": "gopls"
150 }
151 },
152 "debug": false,
153 "debugLSP": false,
154 "autoCompact": true
155}
156```
157
158## Supported AI Models
159
160OpenCode supports a variety of AI models from different providers:
161
162### OpenAI
163
164- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
165- GPT-4.5 Preview
166- GPT-4o family (gpt-4o, gpt-4o-mini)
167- O1 family (o1, o1-pro, o1-mini)
168- O3 family (o3, o3-mini)
169- O4 Mini
170
171### Anthropic
172
173- Claude 3.5 Sonnet
174- Claude 3.5 Haiku
175- Claude 3.7 Sonnet
176- Claude 3 Haiku
177- Claude 3 Opus
178
179### Google
180
181- Gemini 2.5
182- Gemini 2.5 Flash
183- Gemini 2.0 Flash
184- Gemini 2.0 Flash Lite
185
186### AWS Bedrock
187
188- Claude 3.7 Sonnet
189
190### Groq
191
192- Llama 4 Maverick (17b-128e-instruct)
193- Llama 4 Scout (17b-16e-instruct)
194- QWEN QWQ-32b
195- Deepseek R1 distill Llama 70b
196- Llama 3.3 70b Versatile
197
198### Azure OpenAI
199
200- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
201- GPT-4.5 Preview
202- GPT-4o family (gpt-4o, gpt-4o-mini)
203- O1 family (o1, o1-mini)
204- O3 family (o3, o3-mini)
205- O4 Mini
206
207## Usage
208
209```bash
210# Start OpenCode
211opencode
212
213# Start with debug logging
214opencode -d
215
216# Start with a specific working directory
217opencode -c /path/to/project
218```
219
220## Command-line Flags
221
222| Flag | Short | Description |
223| --------- | ----- | ----------------------------- |
224| `--help` | `-h` | Display help information |
225| `--debug` | `-d` | Enable debug mode |
226| `--cwd` | `-c` | Set current working directory |
227
228## Keyboard Shortcuts
229
230### Global Shortcuts
231
232| Shortcut | Action |
233| -------- | ------------------------------------------------------- |
234| `Ctrl+C` | Quit application |
235| `Ctrl+?` | Toggle help dialog |
236| `?` | Toggle help dialog (when not in editing mode) |
237| `Ctrl+L` | View logs |
238| `Ctrl+A` | Switch session |
239| `Ctrl+K` | Command dialog |
240| `Ctrl+O` | Toggle model selection dialog |
241| `Esc` | Close current overlay/dialog or return to previous mode |
242
243### Chat Page Shortcuts
244
245| Shortcut | Action |
246| -------- | --------------------------------------- |
247| `Ctrl+N` | Create new session |
248| `Ctrl+X` | Cancel current operation/generation |
249| `i` | Focus editor (when not in writing mode) |
250| `Esc` | Exit writing mode and focus messages |
251
252### Editor Shortcuts
253
254| Shortcut | Action |
255| ------------------- | ----------------------------------------- |
256| `Ctrl+S` | Send message (when editor is focused) |
257| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
258| `Ctrl+E` | Open external editor |
259| `Esc` | Blur editor and focus messages |
260
261### Session Dialog Shortcuts
262
263| Shortcut | Action |
264| ---------- | ---------------- |
265| `↑` or `k` | Previous session |
266| `↓` or `j` | Next session |
267| `Enter` | Select session |
268| `Esc` | Close dialog |
269
270### Model Dialog Shortcuts
271
272| Shortcut | Action |
273| ---------- | ----------------- |
274| `↑` or `k` | Move up |
275| `↓` or `j` | Move down |
276| `←` or `h` | Previous provider |
277| `→` or `l` | Next provider |
278| `Esc` | Close dialog |
279
280### Permission Dialog Shortcuts
281
282| Shortcut | Action |
283| ----------------------- | ---------------------------- |
284| `←` or `left` | Switch options left |
285| `→` or `right` or `tab` | Switch options right |
286| `Enter` or `space` | Confirm selection |
287| `a` | Allow permission |
288| `A` | Allow permission for session |
289| `d` | Deny permission |
290
291### Logs Page Shortcuts
292
293| Shortcut | Action |
294| ------------------ | ------------------- |
295| `Backspace` or `q` | Return to chat page |
296
297## AI Assistant Tools
298
299OpenCode's AI assistant has access to various tools to help with coding tasks:
300
301### File and Code Tools
302
303| Tool | Description | Parameters |
304| ------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
305| `glob` | Find files by pattern | `pattern` (required), `path` (optional) |
306| `grep` | Search file contents | `pattern` (required), `path` (optional), `include` (optional), `literal_text` (optional) |
307| `ls` | List directory contents | `path` (optional), `ignore` (optional array of patterns) |
308| `view` | View file contents | `file_path` (required), `offset` (optional), `limit` (optional) |
309| `write` | Write to files | `file_path` (required), `content` (required) |
310| `edit` | Edit files | Various parameters for file editing |
311| `patch` | Apply patches to files | `file_path` (required), `diff` (required) |
312| `diagnostics` | Get diagnostics information | `file_path` (optional) |
313
314### Other Tools
315
316| Tool | Description | Parameters |
317| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
318| `bash` | Execute shell commands | `command` (required), `timeout` (optional) |
319| `fetch` | Fetch data from URLs | `url` (required), `format` (required), `timeout` (optional) |
320| `sourcegraph` | Search code across public repositories | `query` (required), `count` (optional), `context_window` (optional), `timeout` (optional) |
321| `agent` | Run sub-tasks with the AI agent | `prompt` (required) |
322
323## Architecture
324
325OpenCode is built with a modular architecture:
326
327- **cmd**: Command-line interface using Cobra
328- **internal/app**: Core application services
329- **internal/config**: Configuration management
330- **internal/db**: Database operations and migrations
331- **internal/llm**: LLM providers and tools integration
332- **internal/tui**: Terminal UI components and layouts
333- **internal/logging**: Logging infrastructure
334- **internal/message**: Message handling
335- **internal/session**: Session management
336- **internal/lsp**: Language Server Protocol integration
337
338## Custom Commands
339
340OpenCode supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.
341
342### Creating Custom Commands
343
344Custom commands are predefined prompts stored as Markdown files in one of three locations:
345
3461. **User Commands** (prefixed with `user:`):
347
348 ```
349 $XDG_CONFIG_HOME/opencode/commands/
350 ```
351
352 (typically `~/.config/opencode/commands/` on Linux/macOS)
353
354 or
355
356 ```
357 $HOME/.opencode/commands/
358 ```
359
3602. **Project Commands** (prefixed with `project:`):
361 ```
362 <PROJECT DIR>/.opencode/commands/
363 ```
364
365Each `.md` file in these directories becomes a custom command. The file name (without extension) becomes the command ID.
366
367For example, creating a file at `~/.config/opencode/commands/prime-context.md` with content:
368
369```markdown
370RUN git ls-files
371READ README.md
372```
373
374This creates a command called `user:prime-context`.
375
376### Command Arguments
377
378You can create commands that accept arguments by including the `$ARGUMENTS` placeholder in your command file:
379
380```markdown
381RUN git show $ARGUMENTS
382```
383
384When you run this command, OpenCode will prompt you to enter the text that should replace `$ARGUMENTS`.
385
386### Organizing Commands
387
388You can organize commands in subdirectories:
389
390```
391~/.config/opencode/commands/git/commit.md
392```
393
394This creates a command with ID `user:git:commit`.
395
396### Using Custom Commands
397
3981. Press `Ctrl+K` to open the command dialog
3992. Select your custom command (prefixed with either `user:` or `project:`)
4003. Press Enter to execute the command
401
402The content of the command file will be sent as a message to the AI assistant.
403
404### Built-in Commands
405
406OpenCode includes several built-in commands:
407
408| Command | Description |
409| ------------------ | --------------------------------------------------------------------------------------------------- |
410| Initialize Project | Creates or updates the OpenCode.md memory file with project-specific information |
411| Compact Session | Manually triggers the summarization of the current session, creating a new session with the summary |
412
413## MCP (Model Context Protocol)
414
415OpenCode 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.
416
417### MCP Features
418
419- **External Tool Integration**: Connect to external tools and services via a standardized protocol
420- **Tool Discovery**: Automatically discover available tools from MCP servers
421- **Multiple Connection Types**:
422 - **Stdio**: Communicate with tools via standard input/output
423 - **SSE**: Communicate with tools via Server-Sent Events
424- **Security**: Permission system for controlling access to MCP tools
425
426### Configuring MCP Servers
427
428MCP servers are defined in the configuration file under the `mcpServers` section:
429
430```json
431{
432 "mcpServers": {
433 "example": {
434 "type": "stdio",
435 "command": "path/to/mcp-server",
436 "env": [],
437 "args": []
438 },
439 "web-example": {
440 "type": "sse",
441 "url": "https://example.com/mcp",
442 "headers": {
443 "Authorization": "Bearer token"
444 }
445 }
446 }
447}
448```
449
450### MCP Tool Usage
451
452Once 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.
453
454## LSP (Language Server Protocol)
455
456OpenCode integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
457
458### LSP Features
459
460- **Multi-language Support**: Connect to language servers for different programming languages
461- **Diagnostics**: Receive error checking and linting information
462- **File Watching**: Automatically notify language servers of file changes
463
464### Configuring LSP
465
466Language servers are configured in the configuration file under the `lsp` section:
467
468```json
469{
470 "lsp": {
471 "go": {
472 "disabled": false,
473 "command": "gopls"
474 },
475 "typescript": {
476 "disabled": false,
477 "command": "typescript-language-server",
478 "args": ["--stdio"]
479 }
480 }
481}
482```
483
484### LSP Integration with AI
485
486The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
487
488- Check for errors in your code
489- Suggest fixes based on diagnostics
490
491While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
492
493## Development
494
495### Prerequisites
496
497- Go 1.24.0 or higher
498
499### Building from Source
500
501```bash
502# Clone the repository
503git clone https://github.com/opencode-ai/opencode.git
504cd opencode
505
506# Build
507go build -o opencode
508
509# Run
510./opencode
511```
512
513## Acknowledgments
514
515OpenCode gratefully acknowledges the contributions and support from these key individuals:
516
517- [@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
518- [@adamdottv](https://github.com/adamdottv) - For the design direction and UI/UX architecture
519
520Special thanks to the broader open source community whose tools and libraries have made this project possible.
521
522## License
523
524OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
525
526## Contributing
527
528Contributions are welcome! Here's how you can contribute:
529
5301. Fork the repository
5312. Create a feature branch (`git checkout -b feature/amazing-feature`)
5323. Commit your changes (`git commit -m 'Add some amazing feature'`)
5334. Push to the branch (`git push origin feature/amazing-feature`)
5345. Open a Pull Request
535
536Please make sure to update tests as appropriate and follow the existing code style.