summaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authorKujtim Hoxha <[email protected]>2025-04-18 20:17:38 +0200
committerKujtim Hoxha <[email protected]>2025-04-21 13:42:27 +0200
commit333ea6ec4b2abfc2c1a9c3f6b0918ca5d296347f (patch)
treee0d456417368e8716c81ee43b82be3d6ed39c59e /README.md
parent05d0e86f10369fd0e51a924ac88029fb92591499 (diff)
downloadopencode-333ea6ec4b2abfc2c1a9c3f6b0918ca5d296347f.tar.gz
opencode-333ea6ec4b2abfc2c1a9c3f6b0918ca5d296347f.zip
implement patch, update ui, improve rendering
Diffstat (limited to 'README.md')
-rw-r--r--README.md301
1 files changed, 271 insertions, 30 deletions
diff --git a/README.md b/README.md
index 564284c7f..ef55b6929 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,6 @@
A powerful terminal-based AI assistant for developers, providing intelligent coding assistance directly in your terminal.
-[![OpenCode Demo](https://asciinema.org/a/dtc4nJyGSZX79HRUmFLY3gmoy.svg)](https://asciinema.org/a/dtc4nJyGSZX79HRUmFLY3gmoy)
-
## Overview
OpenCode 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.
@@ -13,11 +11,13 @@ OpenCode is a Go-based CLI application that brings AI assistance to your termina
## Features
- **Interactive TUI**: Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) for a smooth terminal experience
-- **Multiple AI Providers**: Support for OpenAI, Anthropic Claude, and Google Gemini models
+- **Multiple AI Providers**: Support for OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, and Groq
- **Session Management**: Save and manage multiple conversation sessions
- **Tool Integration**: AI can execute commands, search files, and modify code
-- **Vim-like Editor**: Integrated editor with Vim keybindings for text input
+- **Vim-like Editor**: Integrated editor with text input capabilities
- **Persistent Storage**: SQLite database for storing conversations and sessions
+- **LSP Integration**: Language Server Protocol support for code intelligence
+- **File Change Tracking**: Track and visualize file changes during sessions
## Installation
@@ -34,11 +34,107 @@ OpenCode looks for configuration in the following locations:
- `$XDG_CONFIG_HOME/opencode/.opencode.json`
- `./.opencode.json` (local directory)
-You can also use environment variables:
+### Environment Variables
+
+You can configure OpenCode using environment variables:
+
+| Environment Variable | Purpose |
+| ----------------------- | ------------------------ |
+| `ANTHROPIC_API_KEY` | For Claude models |
+| `OPENAI_API_KEY` | For OpenAI models |
+| `GEMINI_API_KEY` | For Google Gemini models |
+| `GROQ_API_KEY` | For Groq models |
+| `AWS_ACCESS_KEY_ID` | For AWS Bedrock (Claude) |
+| `AWS_SECRET_ACCESS_KEY` | For AWS Bedrock (Claude) |
+| `AWS_REGION` | For AWS Bedrock (Claude) |
+
+### Configuration File Structure
+
+```json
+{
+ "data": {
+ "directory": ".opencode"
+ },
+ "providers": {
+ "openai": {
+ "apiKey": "your-api-key",
+ "disabled": false
+ },
+ "anthropic": {
+ "apiKey": "your-api-key",
+ "disabled": false
+ }
+ },
+ "agents": {
+ "coder": {
+ "model": "claude-3.7-sonnet",
+ "maxTokens": 5000
+ },
+ "task": {
+ "model": "claude-3.7-sonnet",
+ "maxTokens": 5000
+ },
+ "title": {
+ "model": "claude-3.7-sonnet",
+ "maxTokens": 80
+ }
+ },
+ "mcpServers": {
+ "example": {
+ "type": "stdio",
+ "command": "path/to/mcp-server",
+ "env": [],
+ "args": []
+ }
+ },
+ "lsp": {
+ "go": {
+ "disabled": false,
+ "command": "gopls"
+ }
+ },
+ "debug": false,
+ "debugLSP": false
+}
+```
-- `ANTHROPIC_API_KEY`: For Claude models
-- `OPENAI_API_KEY`: For OpenAI models
-- `GEMINI_API_KEY`: For Google Gemini models
+## Supported AI Models
+
+### OpenAI Models
+
+| Model ID | Name | Context Window |
+| ----------------- | --------------- | ---------------- |
+| `gpt-4.1` | GPT 4.1 | 1,047,576 tokens |
+| `gpt-4.1-mini` | GPT 4.1 Mini | 200,000 tokens |
+| `gpt-4.1-nano` | GPT 4.1 Nano | 1,047,576 tokens |
+| `gpt-4.5-preview` | GPT 4.5 Preview | 128,000 tokens |
+| `gpt-4o` | GPT-4o | 128,000 tokens |
+| `gpt-4o-mini` | GPT-4o Mini | 128,000 tokens |
+| `o1` | O1 | 200,000 tokens |
+| `o1-pro` | O1 Pro | 200,000 tokens |
+| `o1-mini` | O1 Mini | 128,000 tokens |
+| `o3` | O3 | 200,000 tokens |
+| `o3-mini` | O3 Mini | 200,000 tokens |
+| `o4-mini` | O4 Mini | 128,000 tokens |
+
+### Anthropic Models
+
+| Model ID | Name | Context Window |
+| ------------------- | ----------------- | -------------- |
+| `claude-3.5-sonnet` | Claude 3.5 Sonnet | 200,000 tokens |
+| `claude-3-haiku` | Claude 3 Haiku | 200,000 tokens |
+| `claude-3.7-sonnet` | Claude 3.7 Sonnet | 200,000 tokens |
+| `claude-3.5-haiku` | Claude 3.5 Haiku | 200,000 tokens |
+| `claude-3-opus` | Claude 3 Opus | 200,000 tokens |
+
+### Other Models
+
+| Model ID | Provider | Name | Context Window |
+| --------------------------- | ----------- | ----------------- | -------------- |
+| `gemini-2.5` | Google | Gemini 2.5 Pro | - |
+| `gemini-2.0-flash` | Google | Gemini 2.0 Flash | - |
+| `qwen-qwq` | Groq | Qwen Qwq | - |
+| `bedrock.claude-3.7-sonnet` | AWS Bedrock | Claude 3.7 Sonnet | - |
## Usage
@@ -48,36 +144,78 @@ opencode
# Start with debug logging
opencode -d
+
+# Start with a specific working directory
+opencode -c /path/to/project
```
-### Keyboard Shortcuts
+## Command-line Flags
+
+| Flag | Short | Description |
+| --------- | ----- | ----------------------------- |
+| `--help` | `-h` | Display help information |
+| `--debug` | `-d` | Enable debug mode |
+| `--cwd` | `-c` | Set current working directory |
+
+## Keyboard Shortcuts
+
+### Global Shortcuts
+
+| Shortcut | Action |
+| -------- | ------------------------------------------------------- |
+| `Ctrl+C` | Quit application |
+| `Ctrl+?` | Toggle help dialog |
+| `Ctrl+L` | View logs |
+| `Esc` | Close current overlay/dialog or return to previous mode |
+
+### Chat Page Shortcuts
+
+| Shortcut | Action |
+| -------- | --------------------------------------- |
+| `Ctrl+N` | Create new session |
+| `Ctrl+X` | Cancel current operation/generation |
+| `i` | Focus editor (when not in writing mode) |
+| `Esc` | Exit writing mode and focus messages |
+
+### Editor Shortcuts
-#### Global Shortcuts
+| Shortcut | Action |
+| ------------------- | ----------------------------------------- |
+| `Ctrl+S` | Send message (when editor is focused) |
+| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
+| `Esc` | Blur editor and focus messages |
-- `?`: Toggle help panel
-- `Ctrl+C` or `q`: Quit application
-- `L`: View logs
-- `Backspace`: Go back to previous page
-- `Esc`: Close current view/dialog or return to normal mode
+### Logs Page Shortcuts
-#### Session Management
+| Shortcut | Action |
+| ----------- | ------------------- |
+| `Backspace` | Return to chat page |
-- `N`: Create new session
-- `Enter` or `Space`: Select session (in sessions list)
+## AI Assistant Tools
-#### Editor Shortcuts (Vim-like)
+OpenCode's AI assistant has access to various tools to help with coding tasks:
-- `i`: Enter insert mode
-- `Esc`: Enter normal mode
-- `v`: Enter visual mode
-- `V`: Enter visual line mode
-- `Enter`: Send message (in normal mode)
-- `Ctrl+S`: Send message (in insert mode)
+### File and Code Tools
-#### Navigation
+| Tool | Description | Parameters |
+| ------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `glob` | Find files by pattern | `pattern` (required), `path` (optional) |
+| `grep` | Search file contents | `pattern` (required), `path` (optional), `include` (optional), `literal_text` (optional) |
+| `ls` | List directory contents | `path` (optional), `ignore` (optional array of patterns) |
+| `view` | View file contents | `file_path` (required), `offset` (optional), `limit` (optional) |
+| `write` | Write to files | `file_path` (required), `content` (required) |
+| `edit` | Edit files | Various parameters for file editing |
+| `patch` | Apply patches to files | `file_path` (required), `diff` (required) |
+| `diagnostics` | Get diagnostics information | `file_path` (optional) |
-- Arrow keys: Navigate through lists and content
-- Page Up/Down: Scroll through content
+### Other Tools
+
+| Tool | Description | Parameters |
+| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `bash` | Execute shell commands | `command` (required), `timeout` (optional) |
+| `fetch` | Fetch data from URLs | `url` (required), `format` (required), `timeout` (optional) |
+| `sourcegraph` | Search code across public repositories | `query` (required), `count` (optional), `context_window` (optional), `timeout` (optional) |
+| `agent` | Run sub-tasks with the AI agent | `prompt` (required) |
## Architecture
@@ -92,6 +230,101 @@ OpenCode is built with a modular architecture:
- **internal/logging**: Logging infrastructure
- **internal/message**: Message handling
- **internal/session**: Session management
+- **internal/lsp**: Language Server Protocol integration
+
+## MCP (Model Context Protocol)
+
+OpenCode 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.
+
+### MCP Features
+
+- **External Tool Integration**: Connect to external tools and services via a standardized protocol
+- **Tool Discovery**: Automatically discover available tools from MCP servers
+- **Multiple Connection Types**:
+ - **Stdio**: Communicate with tools via standard input/output
+ - **SSE**: Communicate with tools via Server-Sent Events
+- **Security**: Permission system for controlling access to MCP tools
+
+### Configuring MCP Servers
+
+MCP servers are defined in the configuration file under the `mcpServers` section:
+
+```json
+{
+ "mcpServers": {
+ "example": {
+ "type": "stdio",
+ "command": "path/to/mcp-server",
+ "env": [],
+ "args": []
+ },
+ "web-example": {
+ "type": "sse",
+ "url": "https://example.com/mcp",
+ "headers": {
+ "Authorization": "Bearer token"
+ }
+ }
+ }
+}
+```
+
+### MCP Tool Usage
+
+Once 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.
+
+## LSP (Language Server Protocol)
+
+OpenCode integrates with Language Server Protocol to provide rich code intelligence features across multiple programming languages.
+
+### LSP Features
+
+- **Multi-language Support**: Connect to language servers for different programming languages
+- **Code Intelligence**: Get diagnostics, completions, and navigation assistance
+- **File Watching**: Automatically notify language servers of file changes
+- **Diagnostics**: Display errors, warnings, and hints in your code
+
+### Supported LSP Features
+
+| Feature | Description |
+| ----------------- | ----------------------------------- |
+| Diagnostics | Error checking and linting |
+| Completions | Code suggestions and autocompletion |
+| Hover | Documentation on hover |
+| Definition | Go to definition |
+| References | Find all references |
+| Document Symbols | Navigate symbols in current file |
+| Workspace Symbols | Search symbols across workspace |
+| Formatting | Code formatting |
+| Code Actions | Quick fixes and refactorings |
+
+### Configuring LSP
+
+Language servers are configured in the configuration file under the `lsp` section:
+
+```json
+{
+ "lsp": {
+ "go": {
+ "disabled": false,
+ "command": "gopls"
+ },
+ "typescript": {
+ "disabled": false,
+ "command": "typescript-language-server",
+ "args": ["--stdio"]
+ }
+ }
+}
+```
+
+### LSP Integration with AI
+
+The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
+
+- Check for errors in your code
+- Suggest fixes based on diagnostics
+- Provide intelligent code assistance
## Development
@@ -124,8 +357,16 @@ OpenCode builds upon the work of several open source projects and developers:
## License
-[License information coming soon]
+OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Contributing
-[Contribution guidelines coming soon]
+Contributions are welcome! Here's how you can contribute:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please make sure to update tests as appropriate and follow the existing code style.