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