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