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