+
+
+
The AI coding agent built for the terminal.
+ + +[](https://opencode.ai) + +--- + +### Installation ```bash -# Coming soon -go install github.com/kujtimiihoxha/opencode@latest -``` - -## Configuration - -OpenCode looks for configuration in the following locations: - -- `$HOME/.opencode.json` -- `$XDG_CONFIG_HOME/opencode/.opencode.json` -- `./.opencode.json` (local directory) - -### 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 -} +# YOLO +curl -fsSL https://opencode.ai/install | bash + +# Package managers +npm i -g opencode-ai@latest # or bun/pnpm/yarn +scoop bucket add extras; scoop install extras/opencode # Windows +choco install opencode # Windows +brew install opencode # macOS and Linux +paru -S opencode-bin # Arch Linux +mise use --pin -g ubi:sst/opencode # Any OS +nix run nixpkgs#opencode # or github:sst/opencode for latest dev branch ``` -## Supported AI Models - -OpenCode supports a variety of AI models from different providers: - -### OpenAI +> [!TIP] +> Remove versions older than 0.1.x before installing. -- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano) -- GPT-4.5 Preview -- GPT-4o family (gpt-4o, gpt-4o-mini) -- O1 family (o1, o1-pro, o1-mini) -- O3 family (o3, o3-mini) -- O4 Mini +#### Installation Directory -### Anthropic +The install script respects the following priority order for the installation path: -- Claude 3.5 Sonnet -- Claude 3.5 Haiku -- Claude 3.7 Sonnet -- Claude 3 Haiku -- Claude 3 Opus - -### Google - -- Gemini 2.5 -- Gemini 2.5 Flash -- Gemini 2.0 Flash -- Gemini 2.0 Flash Lite - -### AWS Bedrock - -- Claude 3.7 Sonnet - -## Usage +1. `$OPENCODE_INSTALL_DIR` - Custom installation directory +2. `$XDG_BIN_DIR` - XDG Base Directory Specification compliant path +3. `$HOME/bin` - Standard user binary directory (if exists or can be created) +4. `$HOME/.opencode/bin` - Default fallback ```bash -# Start OpenCode -opencode - -# Start with debug logging -opencode -d - -# Start with a specific working directory -opencode -c /path/to/project +# Examples +OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash +XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash ``` -## 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 | -| `?` | Toggle help dialog (when not in editing mode) | -| `Ctrl+L` | View logs | -| `Ctrl+A` | Switch session | -| `Ctrl+K` | Command dialog | -| `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 - -| Shortcut | Action | -| ------------------- | ----------------------------------------- | -| `Ctrl+S` | Send message (when editor is focused) | -| `Enter` or `Ctrl+S` | Send message (when editor is not focused) | -| `Ctrl+E` | Open external editor | -| `Esc` | Blur editor and focus messages | - -### Session Dialog Shortcuts - -| Shortcut | Action | -| ---------- | ---------------- | -| `↑` or `k` | Previous session | -| `↓` or `j` | Next session | -| `Enter` | Select session | -| `Esc` | Close dialog | - -### Permission Dialog Shortcuts +### Agents -| Shortcut | Action | -| ----------------------- | ---------------------------- | -| `←` or `left` | Switch options left | -| `→` or `right` or `tab` | Switch options right | -| `Enter` or `space` | Confirm selection | -| `a` | Allow permission | -| `A` | Allow permission for session | -| `d` | Deny permission | +OpenCode includes two built-in agents you can switch between, +you can switch between these using the `Tab` key. -### Logs Page Shortcuts +- **build** - Default, full access agent for development work +- **plan** - Read-only agent for analysis and code exploration + - Denies file edits by default + - Asks permission before running bash commands + - Ideal for exploring unfamiliar codebases or planning changes -| Shortcut | Action | -| ------------------ | ------------------- | -| `Backspace` or `q` | Return to chat page | +Also, included is a **general** subagent for complex searches and multi-step tasks. +This is used internally and can be invoked using `@general` in messages. -## AI Assistant Tools +Learn more about [agents](https://opencode.ai/docs/agents). -OpenCode's AI assistant has access to various tools to help with coding tasks: +### Documentation -### File and Code Tools +For more info on how to configure OpenCode [**head over to our docs**](https://opencode.ai/docs). -| 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) | +### Contributing -### 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 - -OpenCode is built with a modular architecture: - -- **cmd**: Command-line interface using Cobra -- **internal/app**: Core application services -- **internal/config**: Configuration management -- **internal/db**: Database operations and migrations -- **internal/llm**: LLM providers and tools integration -- **internal/tui**: Terminal UI components and layouts -- **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 code intelligence features across multiple programming languages. - -### LSP Features - -- **Multi-language Support**: Connect to language servers for different programming languages -- **Diagnostics**: Receive error checking and linting information -- **File Watching**: Automatically notify language servers of file changes - -### 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 - -While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant. - -## Development - -### Prerequisites - -- Go 1.24.0 or higher - -### Building from Source - -```bash -# Clone the repository -git clone https://github.com/kujtimiihoxha/opencode.git -cd opencode - -# Build -go build -o opencode - -# Run -./opencode -``` +If you're interested in contributing to OpenCode, please read our [contributing docs](./CONTRIBUTING.md) before submitting a pull request. -## Acknowledgments +### Building on OpenCode -OpenCode gratefully acknowledges the contributions and support from these key individuals: +If you are working on a project that's related to OpenCode and is using "opencode" as a part of its name; for example, "opencode-dashboard" or "opencode-mobile", please add a note to your README to clarify that it is not built by the OpenCode team and is not affiliated with us in anyway. -- [@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 -- [@adamdottv](https://github.com/adamdottv) - For the design direction and UI/UX architecture +### FAQ -Special thanks to the broader open source community whose tools and libraries have made this project possible. +#### How is this different than Claude Code? -## License +It's very similar to Claude Code in terms of capability. Here are the key differences: -OpenCode is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. +- 100% open source +- Not coupled to any provider. Although we recommend the models we provide through [OpenCode Zen](https://opencode.ai/zen); OpenCode can be used with Claude, OpenAI, Google or even local models. As models evolve the gaps between them will close and pricing will drop so being provider-agnostic is important. +- Out of the box LSP support +- A focus on TUI. OpenCode is built by neovim users and the creators of [terminal.shop](https://terminal.shop); we are going to push the limits of what's possible in the terminal. +- A client/server architecture. This for example can allow OpenCode to run on your computer, while you can drive it remotely from a mobile app. Meaning that the TUI frontend is just one of the possible clients. -## Contributing +#### What's the other repo? -Contributions are welcome! Here's how you can contribute: +The other confusingly named repo has no relation to this one. You can [read the story behind it here](https://x.com/thdxr/status/1933561254481666466). -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. +**Join our community** [Discord](https://discord.gg/opencode) | [X.com](https://x.com/opencode) diff --git a/STATS.md b/STATS.md new file mode 100644 index 00000000000..b58a8f1c5d4 --- /dev/null +++ b/STATS.md @@ -0,0 +1,154 @@ +# Download Stats + +| Date | GitHub Downloads | npm Downloads | Total | +| ---------- | ----------------- | ----------------- | ------------------- | +| 2025-06-29 | 18,789 (+0) | 39,420 (+0) | 58,209 (+0) | +| 2025-06-30 | 20,127 (+1,338) | 41,059 (+1,639) | 61,186 (+2,977) | +| 2025-07-01 | 22,108 (+1,981) | 43,745 (+2,686) | 65,853 (+4,667) | +| 2025-07-02 | 24,814 (+2,706) | 46,168 (+2,423) | 70,982 (+5,129) | +| 2025-07-03 | 27,834 (+3,020) | 49,955 (+3,787) | 77,789 (+6,807) | +| 2025-07-04 | 30,608 (+2,774) | 54,758 (+4,803) | 85,366 (+7,577) | +| 2025-07-05 | 32,524 (+1,916) | 58,371 (+3,613) | 90,895 (+5,529) | +| 2025-07-06 | 33,766 (+1,242) | 59,694 (+1,323) | 93,460 (+2,565) | +| 2025-07-08 | 38,052 (+4,286) | 64,468 (+4,774) | 102,520 (+9,060) | +| 2025-07-09 | 40,924 (+2,872) | 67,935 (+3,467) | 108,859 (+6,339) | +| 2025-07-10 | 43,796 (+2,872) | 71,402 (+3,467) | 115,198 (+6,339) | +| 2025-07-11 | 46,982 (+3,186) | 77,462 (+6,060) | 124,444 (+9,246) | +| 2025-07-12 | 49,302 (+2,320) | 82,177 (+4,715) | 131,479 (+7,035) | +| 2025-07-13 | 50,803 (+1,501) | 86,394 (+4,217) | 137,197 (+5,718) | +| 2025-07-14 | 53,283 (+2,480) | 87,860 (+1,466) | 141,143 (+3,946) | +| 2025-07-15 | 57,590 (+4,307) | 91,036 (+3,176) | 148,626 (+7,483) | +| 2025-07-16 | 62,313 (+4,723) | 95,258 (+4,222) | 157,571 (+8,945) | +| 2025-07-17 | 66,684 (+4,371) | 100,048 (+4,790) | 166,732 (+9,161) | +| 2025-07-18 | 70,379 (+3,695) | 102,587 (+2,539) | 172,966 (+6,234) | +| 2025-07-19 | 73,497 (+3,117) | 105,904 (+3,317) | 179,401 (+6,434) | +| 2025-07-20 | 76,453 (+2,956) | 109,044 (+3,140) | 185,497 (+6,096) | +| 2025-07-21 | 80,197 (+3,744) | 113,537 (+4,493) | 193,734 (+8,237) | +| 2025-07-22 | 84,251 (+4,054) | 118,073 (+4,536) | 202,324 (+8,590) | +| 2025-07-23 | 88,589 (+4,338) | 121,436 (+3,363) | 210,025 (+7,701) | +| 2025-07-24 | 92,469 (+3,880) | 124,091 (+2,655) | 216,560 (+6,535) | +| 2025-07-25 | 96,417 (+3,948) | 126,985 (+2,894) | 223,402 (+6,842) | +| 2025-07-26 | 100,646 (+4,229) | 131,411 (+4,426) | 232,057 (+8,655) | +| 2025-07-27 | 102,644 (+1,998) | 134,736 (+3,325) | 237,380 (+5,323) | +| 2025-07-28 | 105,446 (+2,802) | 136,016 (+1,280) | 241,462 (+4,082) | +| 2025-07-29 | 108,998 (+3,552) | 137,542 (+1,526) | 246,540 (+5,078) | +| 2025-07-30 | 113,544 (+4,546) | 140,317 (+2,775) | 253,861 (+7,321) | +| 2025-07-31 | 118,339 (+4,795) | 143,344 (+3,027) | 261,683 (+7,822) | +| 2025-08-01 | 123,539 (+5,200) | 146,680 (+3,336) | 270,219 (+8,536) | +| 2025-08-02 | 127,864 (+4,325) | 149,236 (+2,556) | 277,100 (+6,881) | +| 2025-08-03 | 131,397 (+3,533) | 150,451 (+1,215) | 281,848 (+4,748) | +| 2025-08-04 | 136,266 (+4,869) | 153,260 (+2,809) | 289,526 (+7,678) | +| 2025-08-05 | 141,596 (+5,330) | 155,752 (+2,492) | 297,348 (+7,822) | +| 2025-08-06 | 147,067 (+5,471) | 158,309 (+2,557) | 305,376 (+8,028) | +| 2025-08-07 | 152,591 (+5,524) | 160,889 (+2,580) | 313,480 (+8,104) | +| 2025-08-08 | 158,187 (+5,596) | 163,448 (+2,559) | 321,635 (+8,155) | +| 2025-08-09 | 162,770 (+4,583) | 165,721 (+2,273) | 328,491 (+6,856) | +| 2025-08-10 | 165,695 (+2,925) | 167,109 (+1,388) | 332,804 (+4,313) | +| 2025-08-11 | 169,297 (+3,602) | 167,953 (+844) | 337,250 (+4,446) | +| 2025-08-12 | 176,307 (+7,010) | 171,876 (+3,923) | 348,183 (+10,933) | +| 2025-08-13 | 182,997 (+6,690) | 177,182 (+5,306) | 360,179 (+11,996) | +| 2025-08-14 | 189,063 (+6,066) | 179,741 (+2,559) | 368,804 (+8,625) | +| 2025-08-15 | 193,608 (+4,545) | 181,792 (+2,051) | 375,400 (+6,596) | +| 2025-08-16 | 198,118 (+4,510) | 184,558 (+2,766) | 382,676 (+7,276) | +| 2025-08-17 | 201,299 (+3,181) | 186,269 (+1,711) | 387,568 (+4,892) | +| 2025-08-18 | 204,559 (+3,260) | 187,399 (+1,130) | 391,958 (+4,390) | +| 2025-08-19 | 209,814 (+5,255) | 189,668 (+2,269) | 399,482 (+7,524) | +| 2025-08-20 | 214,497 (+4,683) | 191,481 (+1,813) | 405,978 (+6,496) | +| 2025-08-21 | 220,465 (+5,968) | 194,784 (+3,303) | 415,249 (+9,271) | +| 2025-08-22 | 225,899 (+5,434) | 197,204 (+2,420) | 423,103 (+7,854) | +| 2025-08-23 | 229,005 (+3,106) | 199,238 (+2,034) | 428,243 (+5,140) | +| 2025-08-24 | 232,098 (+3,093) | 201,157 (+1,919) | 433,255 (+5,012) | +| 2025-08-25 | 236,607 (+4,509) | 202,650 (+1,493) | 439,257 (+6,002) | +| 2025-08-26 | 242,783 (+6,176) | 205,242 (+2,592) | 448,025 (+8,768) | +| 2025-08-27 | 248,409 (+5,626) | 205,242 (+0) | 453,651 (+5,626) | +| 2025-08-28 | 252,796 (+4,387) | 205,242 (+0) | 458,038 (+4,387) | +| 2025-08-29 | 256,045 (+3,249) | 211,075 (+5,833) | 467,120 (+9,082) | +| 2025-08-30 | 258,863 (+2,818) | 212,397 (+1,322) | 471,260 (+4,140) | +| 2025-08-31 | 262,004 (+3,141) | 213,944 (+1,547) | 475,948 (+4,688) | +| 2025-09-01 | 265,359 (+3,355) | 215,115 (+1,171) | 480,474 (+4,526) | +| 2025-09-02 | 270,483 (+5,124) | 217,075 (+1,960) | 487,558 (+7,084) | +| 2025-09-03 | 274,793 (+4,310) | 219,755 (+2,680) | 494,548 (+6,990) | +| 2025-09-04 | 280,430 (+5,637) | 222,103 (+2,348) | 502,533 (+7,985) | +| 2025-09-05 | 283,769 (+3,339) | 223,793 (+1,690) | 507,562 (+5,029) | +| 2025-09-06 | 286,245 (+2,476) | 225,036 (+1,243) | 511,281 (+3,719) | +| 2025-09-07 | 288,623 (+2,378) | 225,866 (+830) | 514,489 (+3,208) | +| 2025-09-08 | 293,341 (+4,718) | 227,073 (+1,207) | 520,414 (+5,925) | +| 2025-09-09 | 300,036 (+6,695) | 229,788 (+2,715) | 529,824 (+9,410) | +| 2025-09-10 | 307,287 (+7,251) | 233,435 (+3,647) | 540,722 (+10,898) | +| 2025-09-11 | 314,083 (+6,796) | 237,356 (+3,921) | 551,439 (+10,717) | +| 2025-09-12 | 321,046 (+6,963) | 240,728 (+3,372) | 561,774 (+10,335) | +| 2025-09-13 | 324,894 (+3,848) | 245,539 (+4,811) | 570,433 (+8,659) | +| 2025-09-14 | 328,876 (+3,982) | 248,245 (+2,706) | 577,121 (+6,688) | +| 2025-09-15 | 334,201 (+5,325) | 250,983 (+2,738) | 585,184 (+8,063) | +| 2025-09-16 | 342,609 (+8,408) | 255,264 (+4,281) | 597,873 (+12,689) | +| 2025-09-17 | 351,117 (+8,508) | 260,970 (+5,706) | 612,087 (+14,214) | +| 2025-09-18 | 358,717 (+7,600) | 266,922 (+5,952) | 625,639 (+13,552) | +| 2025-09-19 | 365,401 (+6,684) | 271,859 (+4,937) | 637,260 (+11,621) | +| 2025-09-20 | 372,092 (+6,691) | 276,917 (+5,058) | 649,009 (+11,749) | +| 2025-09-21 | 377,079 (+4,987) | 280,261 (+3,344) | 657,340 (+8,331) | +| 2025-09-22 | 382,492 (+5,413) | 284,009 (+3,748) | 666,501 (+9,161) | +| 2025-09-23 | 387,008 (+4,516) | 289,129 (+5,120) | 676,137 (+9,636) | +| 2025-09-24 | 393,325 (+6,317) | 294,927 (+5,798) | 688,252 (+12,115) | +| 2025-09-25 | 398,879 (+5,554) | 301,663 (+6,736) | 700,542 (+12,290) | +| 2025-09-26 | 404,334 (+5,455) | 306,713 (+5,050) | 711,047 (+10,505) | +| 2025-09-27 | 411,618 (+7,284) | 317,763 (+11,050) | 729,381 (+18,334) | +| 2025-09-28 | 414,910 (+3,292) | 322,522 (+4,759) | 737,432 (+8,051) | +| 2025-09-29 | 419,919 (+5,009) | 328,033 (+5,511) | 747,952 (+10,520) | +| 2025-09-30 | 427,991 (+8,072) | 336,472 (+8,439) | 764,463 (+16,511) | +| 2025-10-01 | 433,591 (+5,600) | 341,742 (+5,270) | 775,333 (+10,870) | +| 2025-10-02 | 440,852 (+7,261) | 348,099 (+6,357) | 788,951 (+13,618) | +| 2025-10-03 | 446,829 (+5,977) | 359,937 (+11,838) | 806,766 (+17,815) | +| 2025-10-04 | 452,561 (+5,732) | 370,386 (+10,449) | 822,947 (+16,181) | +| 2025-10-05 | 455,559 (+2,998) | 374,745 (+4,359) | 830,304 (+7,357) | +| 2025-10-06 | 460,927 (+5,368) | 379,489 (+4,744) | 840,416 (+10,112) | +| 2025-10-07 | 467,336 (+6,409) | 385,438 (+5,949) | 852,774 (+12,358) | +| 2025-10-08 | 474,643 (+7,307) | 394,139 (+8,701) | 868,782 (+16,008) | +| 2025-10-09 | 479,203 (+4,560) | 400,526 (+6,387) | 879,729 (+10,947) | +| 2025-10-10 | 484,374 (+5,171) | 406,015 (+5,489) | 890,389 (+10,660) | +| 2025-10-11 | 488,427 (+4,053) | 414,699 (+8,684) | 903,126 (+12,737) | +| 2025-10-12 | 492,125 (+3,698) | 418,745 (+4,046) | 910,870 (+7,744) | +| 2025-10-14 | 505,130 (+13,005) | 429,286 (+10,541) | 934,416 (+23,546) | +| 2025-10-15 | 512,717 (+7,587) | 439,290 (+10,004) | 952,007 (+17,591) | +| 2025-10-16 | 517,719 (+5,002) | 447,137 (+7,847) | 964,856 (+12,849) | +| 2025-10-17 | 526,239 (+8,520) | 457,467 (+10,330) | 983,706 (+18,850) | +| 2025-10-18 | 531,564 (+5,325) | 465,272 (+7,805) | 996,836 (+13,130) | +| 2025-10-19 | 536,209 (+4,645) | 469,078 (+3,806) | 1,005,287 (+8,451) | +| 2025-10-20 | 541,264 (+5,055) | 472,952 (+3,874) | 1,014,216 (+8,929) | +| 2025-10-21 | 548,721 (+7,457) | 479,703 (+6,751) | 1,028,424 (+14,208) | +| 2025-10-22 | 557,949 (+9,228) | 491,395 (+11,692) | 1,049,344 (+20,920) | +| 2025-10-23 | 564,716 (+6,767) | 498,736 (+7,341) | 1,063,452 (+14,108) | +| 2025-10-24 | 572,692 (+7,976) | 506,905 (+8,169) | 1,079,597 (+16,145) | +| 2025-10-25 | 578,927 (+6,235) | 516,129 (+9,224) | 1,095,056 (+15,459) | +| 2025-10-26 | 584,409 (+5,482) | 521,179 (+5,050) | 1,105,588 (+10,532) | +| 2025-10-27 | 589,999 (+5,590) | 526,001 (+4,822) | 1,116,000 (+10,412) | +| 2025-10-28 | 595,776 (+5,777) | 532,438 (+6,437) | 1,128,214 (+12,214) | +| 2025-10-29 | 606,259 (+10,483) | 542,064 (+9,626) | 1,148,323 (+20,109) | +| 2025-10-30 | 613,746 (+7,487) | 542,064 (+0) | 1,155,810 (+7,487) | +| 2025-10-30 | 617,846 (+4,100) | 555,026 (+12,962) | 1,172,872 (+17,062) | +| 2025-10-31 | 626,612 (+8,766) | 564,579 (+9,553) | 1,191,191 (+18,319) | +| 2025-11-01 | 636,100 (+9,488) | 581,806 (+17,227) | 1,217,906 (+26,715) | +| 2025-11-02 | 644,067 (+7,967) | 590,004 (+8,198) | 1,234,071 (+16,165) | +| 2025-11-03 | 653,130 (+9,063) | 597,139 (+7,135) | 1,250,269 (+16,198) | +| 2025-11-04 | 663,912 (+10,782) | 608,056 (+10,917) | 1,271,968 (+21,699) | +| 2025-11-05 | 675,074 (+11,162) | 619,690 (+11,634) | 1,294,764 (+22,796) | +| 2025-11-06 | 686,252 (+11,178) | 630,885 (+11,195) | 1,317,137 (+22,373) | +| 2025-11-07 | 696,646 (+10,394) | 642,146 (+11,261) | 1,338,792 (+21,655) | +| 2025-11-08 | 706,035 (+9,389) | 653,489 (+11,343) | 1,359,524 (+20,732) | +| 2025-11-09 | 713,462 (+7,427) | 660,459 (+6,970) | 1,373,921 (+14,397) | +| 2025-11-10 | 722,288 (+8,826) | 668,225 (+7,766) | 1,390,513 (+16,592) | +| 2025-11-11 | 729,769 (+7,481) | 677,501 (+9,276) | 1,407,270 (+16,757) | +| 2025-11-12 | 740,180 (+10,411) | 686,454 (+8,953) | 1,426,634 (+19,364) | +| 2025-11-13 | 749,905 (+9,725) | 696,157 (+9,703) | 1,446,062 (+19,428) | +| 2025-11-14 | 759,928 (+10,023) | 705,237 (+9,080) | 1,465,165 (+19,103) | +| 2025-11-15 | 765,955 (+6,027) | 712,870 (+7,633) | 1,478,825 (+13,660) | +| 2025-11-16 | 771,069 (+5,114) | 716,596 (+3,726) | 1,487,665 (+8,840) | +| 2025-11-17 | 780,161 (+9,092) | 723,339 (+6,743) | 1,503,500 (+15,835) | +| 2025-11-18 | 791,563 (+11,402) | 732,544 (+9,205) | 1,524,107 (+20,607) | +| 2025-11-19 | 804,409 (+12,846) | 747,624 (+15,080) | 1,552,033 (+27,926) | +| 2025-11-20 | 814,620 (+10,211) | 757,907 (+10,283) | 1,572,527 (+20,494) | +| 2025-11-21 | 826,309 (+11,689) | 769,307 (+11,400) | 1,595,616 (+23,089) | +| 2025-11-22 | 837,269 (+10,960) | 780,996 (+11,689) | 1,618,265 (+22,649) | +| 2025-11-23 | 846,609 (+9,340) | 795,069 (+14,073) | 1,641,678 (+23,413) | +| 2025-11-24 | 856,733 (+10,124) | 804,033 (+8,964) | 1,660,766 (+19,088) | +| 2025-11-25 | 869,423 (+12,690) | 817,339 (+13,306) | 1,686,762 (+25,996) | +| 2025-11-26 | 881,414 (+11,991) | 832,518 (+15,179) | 1,713,932 (+27,170) | diff --git a/TODO.md b/TODO.md new file mode 100644 index 00000000000..01e47d7a2ea --- /dev/null +++ b/TODO.md @@ -0,0 +1,149 @@ +# OpenCode Gym Implementation Status + +## Overview + +The gym command provides sandboxed development environments for safe testing and experimentation with OpenCode. + +## Current Implementation Status ✅ + +### ✅ Completed Features + +- **SandboxFilesystem**: Creates isolated temp directories, copies project files (excluding node_modules/.git) +- **CommandValidator**: Comprehensive command blocking patterns for dangerous operations +- **ProcessSandbox**: Support for bubblewrap (Linux) and sandbox-exec (macOS) process isolation +- **Gym CLI Command**: Full command-line interface with options for mode, network, persist, timeout +- **Server Integration**: Launches OpenCode server and attaches TUI to sandboxed environment +- **Unit Tests**: 34 passing tests covering filesystem and command validation +- **TypeScript Compilation**: All modules compile without errors + +### ⚠️ Known Issues & Missing Integrations + +#### Critical Issues + +1. **CommandValidator NOT integrated with bash tool** + - Location: `packages/opencode/src/sandbox/commands.ts` + - Issue: Dangerous commands are validated but NOT blocked during execution + - Impact: Sandbox provides filesystem isolation but doesn't prevent dangerous commands + +2. **SandboxInstance context not used by tools** + - Location: `packages/opencode/src/sandbox/instance.ts` + - Issue: Tools like `bash.ts`, `write.ts` don't call `SandboxInstance.rewritePath()` + - Impact: File operations may not be properly redirected to sandbox + +3. **ProcessSandbox not integrated** + - Location: `packages/opencode/src/sandbox/process.ts` + - Issue: `ProcessSandbox.wrapWithBwrap()` exists but isn't used in command execution + - Impact: Only filesystem isolation, no process-level isolation + +#### Minor Issues + +4. **Potential context disposal issue** + - Location: `packages/opencode/src/cli/cmd/gym.ts:137` + - Issue: `SandboxInstance.getRoot()` called after `provide()` block may return null + - Impact: Persist path display may fail + +## Architecture + +### Core Components + +``` +packages/opencode/src/sandbox/ +├── index.ts # Exports and types +├── config.ts # GymConfig with Zod schemas +├── instance.ts # SandboxInstance context management +├── filesystem.ts # SandboxFilesystem for directory isolation +├── commands.ts # CommandValidator for command blocking +└── process.ts # ProcessSandbox for process isolation +``` + +### CLI Integration + +``` +packages/opencode/src/cli/cmd/gym.ts +├── Command definition with yargs +├── SandboxInstance.provide() wrapper +├── Server.listen() for TUI attachment +└── Process spawning with attach command +``` + +## Testing Status + +### ✅ Passing Tests + +- **34/34 unit tests pass** in `packages/opencode/test/sandbox/` +- **CommandValidator**: All dangerous command patterns blocked +- **SandboxFilesystem**: Directory creation, copying, path rewriting +- **TypeScript compilation**: No errors + +### ❌ Integration Testing + +- **Interactive gym command**: Not fully tested due to tool execution limits +- **TUI attachment**: Server integration untested +- **Command blocking**: Not integrated with bash tool + +## Build & Deployment + +### ✅ Build Status + +- **Built successfully** for all platforms (darwin-arm64, linux-x64, etc.) +- **Linked locally** via `bun link` +- **CLI accessible** via built binary + +### Usage Options + +```bash +# Direct execution +/Users/johnferguson/Github/opencode/packages/opencode/dist/opencode-darwin-arm64/bin/opencode gym /path/to/project + +# Environment variable +export OPENCODE_BIN_PATH=/path/to/built/opencode +opencode gym /path/to/project + +# Development mode +cd packages/opencode && bun dev gym /path/to/project +``` + +## Next Steps + +### High Priority + +1. **Integrate CommandValidator into bash.ts** + - Add validation before command execution + - Return appropriate error messages + +2. **Integrate SandboxInstance.rewritePath()** + - Update bash.ts, write.ts, read.ts tools + - Ensure all file operations use sandbox paths + +3. **Fix context disposal issue** + - Move persist path logging inside provide() block + +### Medium Priority + +4. **Integrate ProcessSandbox** + - Wrap commands with bubblewrap/sandbox-exec + - Add process-level isolation + +5. **Add comprehensive integration tests** + - Test full gym workflow + - Test command blocking in practice + +### Low Priority + +6. **Add Docker mode support** + - Implement docker-based isolation + - Add docker-compose support + +## Files Modified/Created + +- `packages/opencode/src/cli/cmd/gym.ts` - Main gym command +- `packages/opencode/src/sandbox/` - Complete sandbox implementation +- `packages/opencode/test/sandbox/` - Unit tests +- `packages/opencode/src/index.ts` - Command registration + +## Branch Information + +- **Branch**: `fork/copilot/add-opencode-sandbox-environment` +- **Commit**: `d08d36006` - Add sandbox/gym environment implementation +- **Status**: Ready for integration testing +
\n`
+ })()
+ const shareUrl = shareId ? `[opencode session](${useShareUrl()}/s/${shareId}) | ` : ""
+ return `\n\n${image}${shareUrl}[github run](${useEnvRunUrl()})`
+}
+
+async function fetchRepo() {
+ const { repo } = useContext()
+ return await octoRest.rest.repos.get({ owner: repo.owner, repo: repo.repo })
+}
+
+async function fetchIssue() {
+ console.log("Fetching prompt data for issue...")
+ const { repo } = useContext()
+ const issueResult = await octoGraphJoin the waitlist for early access.
+Resources and assets to help you work with the OpenCode brand.
+ + ++ OpenCode operates securely inside your organization with no data or context stored and no licensing + restrictions or ownership claims. Start a trial with your team, then deploy it across your + organization by integrating it with your SSO and internal AI gateway. +
+Let us know and how we can help.
+ ++ OpenCode is fully open source, giving you control and freedom to use any provider, any model, and any + editor. +
+ + Read docs + + +OpenCode is an open source agent that helps you write and run code directly from the terminal.
++ With over {config.github.starsFormatted.full} GitHub stars,{" "} + {config.stats.contributors} contributors, and almost{" "} + {config.stats.commits} commits, OpenCode is used and trusted by over{" "} + {config.stats.monthlyUsers} developers every month. +
++ OpenCode does not store any of your code or context data, so that it can operate in privacy sensitive + environments. Learn more about privacy. +
++ Zen gives you access to a handpicked set of AI models that OpenCode has tested and benchmarked + specifically for coding agents. No need to worry about inconsistent performance and quality across + providers, use validated models that work. +
++ Manage payments methods. Contact us if you have any questions. +
+Set a monthly usage limit for your account.
++ Current usage for {new Date().toLocaleDateString("en-US", { month: "long", timeZone: "UTC" })} is $ + {(() => { + const dateLastUsed = billingInfo()?.timeMonthlyUsageUpdated + if (!dateLastUsed) return "0" + + const current = new Date().toLocaleDateString("en-US", { + year: "numeric", + month: "long", + timeZone: "UTC", + }) + const lastUsed = dateLastUsed.toLocaleDateString("en-US", { + year: "numeric", + month: "long", + timeZone: "UTC", + }) + if (current !== lastUsed) return "0" + return ((billingInfo()?.monthlyUsage ?? 0) / 100000000).toFixed(2) + })()} + . +
+Recent payment transactions.
+| Date | +Payment ID | +Amount | +Receipt | +
|---|---|---|---|
| + {formatDateForTable(date)} + | +{payment.id} | ++ ${((payment.amount ?? 0) / 100000000).toFixed(2)} + | ++ + | +
+ Auto reload is enabled. We'll reload ${billingInfo()?.reloadAmount} (+$1.23 processing fee) + when balance reaches ${billingInfo()?.reloadTrigger}. +
++ Reload failed at{" "} + {billingInfo()?.timeReloadError!.toLocaleString("en-US", { + month: "short", + day: "numeric", + hour: "numeric", + minute: "2-digit", + second: "2-digit", + })} + . Reason: {billingInfo()?.reloadError?.replace(/\.$/, "")}. Please update your payment method and try + again. +
+ +Usage costs broken down by model.
+No usage data available for the selected period.
+ + } + > +
+
+ Reliable optimized models for coding agents.{" "}
+
+ Learn more
+
+ .
+
+
Manage your API keys for accessing opencode services.
+ +Create an opencode Gateway API key
+| Name | +Key | +Created By | +Last Used | ++ |
|---|---|---|---|---|
| {key.name} | +
+ |
+ {key.email} | ++ {key.timeUsed ? formatDateForTable(key.timeUsed) : "-"} + | ++ + | +
Manage workspace members and their permissions.
+| Role | +Month limit | ++ | + |
|---|
+ Manage which models workspace members can access. Learn more. +
+| Model | ++ | Enabled | +
|---|---|---|
|
+
+ {(() => {
+ switch (lab) {
+ case "OpenAI":
+ return
+ |
+ {lab} | ++ + | +
We've benchmarked and tested models specifically for coding agents to ensure the best performance.
+Access models configured for optimal performance - no downgrades or routing to cheaper providers.
+Use Zen with any coding agent, and continue using other providers with opencode whenever you want.
+{defaultKey()?.masked}
+
+ opencode auth login and select opencode
+ /models to select a model
+ Configure your own API keys from AI providers.
+| Provider | +API Key | ++ |
|---|
Update your workspace name and preferences.
+Workspace name
+{workspaceInfo()?.name}
+ +Recent API usage and costs.
+Make your first API call to get started.
+| Date | +Model | +Input | +Output | +Cost | +
|---|---|---|---|---|
| + {formatDateForTable(date())} + | +{usage.model} | +
+ e.stopPropagation()}>
+
+ setOpenBreakdownId(null)}>{totalInputTokens()}
+
+ e.stopPropagation()}>
+
+
+ Input
+ {usage.inputTokens}
+
+
+ Cache Read
+ {usage.cacheReadTokens ?? 0}
+
+
+ Cache Write
+ {usage.cacheWrite5mTokens ?? 0}
+
+ |
+
+ e.stopPropagation()}>
+
+ setOpenBreakdownId(null)}>{totalOutputTokens()}
+
+ e.stopPropagation()}>
+
+
+ Output
+ {usage.outputTokens}
+
+
+ Reasoning
+ {usage.reasoningTokens ?? 0}
+
+ |
+ ${((usage.cost ?? 0) / 100000000).toFixed(4)} | +
+ Zen gives you access to a curated set of AI models that OpenCode has tested and benchmarked specifically + for coding agents. No need to worry about inconsistent performance and quality, use validated models + that work. +
++ Add $20 Pay as you go balance (+$1.23 card processing fee) +
+Use with any agent. Set monthly spend limits. Cancel any time.
++ There are so many models available, but only a few work well with coding agents. Most providers + configure them differently with varying results. +
+We're fixing this for everyone, not just OpenCode users.
+While we suggest you use Zen with OpenCode, you can use Zen with any agent.
++ All Zen models are hosted in the US. Providers follow a zero-retention policy and do not use your data + for model training, with the following exceptions. +
++ Visit{" "} + + solidjs.com + {" "} + to learn how to build Solid apps. +
++ + Home + + {" - "} + + About Page + +
+
\n`
+ })()
+ const shareUrl = shareId ? `[opencode session](${shareBaseUrl}/s/${shareId}) | ` : ""
+ return `\n\n${image}${shareUrl}[github run](${runUrl})`
+ }
+
+ async function fetchRepo() {
+ return await octoRest.rest.repos.get({ owner, repo })
+ }
+
+ async function fetchIssue() {
+ console.log("Fetching prompt data for issue...")
+ const issueResult = await octoGraph