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