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