From 4f0ae8a5086342bc5b1b87a38ad433bd799f2a55 Mon Sep 17 00:00:00 2001 From: Fechin Date: Fri, 3 Apr 2026 18:39:16 +0800 Subject: [PATCH] feat: add OpenCode post with comprehensive usage instructions, --- source/_posts/opencode.md | 501 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 501 insertions(+) create mode 100644 source/_posts/opencode.md diff --git a/source/_posts/opencode.md b/source/_posts/opencode.md new file mode 100644 index 0000000..efd75fd --- /dev/null +++ b/source/_posts/opencode.md @@ -0,0 +1,501 @@ +--- +title: OpenCode +date: 2026-04-03 14:00:00 +background: bg-[#7c3aed] +tags: + - AI + - CLI + - TUI + - agent + - coding +categories: + - AI +intro: | + [OpenCode](https://opencode.ai) is an open-source AI coding agent with a TUI, CLI, and desktop app — supports any LLM provider, fully extensible via config, plugins, and MCP. +plugins: + - copyCode +--- + +## Getting Started + +### Basic Usage {.row-span-2} + +```bash +# Start TUI for current directory +$ opencode + +# Start TUI for a specific project +$ opencode /path/to/project + +# Run non-interactively (headless) +$ opencode run "Explain how closures work in JS" + +# Continue last session +$ opencode run -c "Fix the failing tests" + +# Pipe input into opencode +$ cat error.log | opencode run "Explain this error" +``` + +Inside the TUI: + +``` +/init # analyze project, create AGENTS.md +@src/api.ts # fuzzy-reference a file +!ls -la # run a shell command inline +Tab # switch agent (Build / Plan / Ask) +``` + +### Introduction + +- [Official Docs](https://opencode.ai/docs) _(opencode.ai)_ +- [GitHub](https://github.com/anomalyco/opencode) _(github.com)_ +- [Discord](https://discord.gg/opencode) _(discord.gg)_ + +### Install + +#### Script (recommended) + +```bash +$ curl -fsSL https://opencode.ai/install | bash +``` + +#### Node.js + +```bash +$ npm install -g opencode-ai +``` + +#### macOS / Linux + +```bash +$ brew install anomalyco/tap/opencode +``` + +#### Windows + +```bash +choco install opencode # Chocolatey +scoop install opencode # Scoop +``` + +#### Docker + +```bash {.wrap} +$ docker run -it --rm ghcr.io/anomalyco/opencode +``` + +### Key Concepts + +| Term | Description | +| -------------- | --------------------------- | +| TUI | Interactive terminal UI | +| `opencode run` | Headless / scripting mode | +| Session | Saved conversation history | +| AGENTS.md | Project context for the AI | +| Snapshot | Git-based undo/redo state | +| Compaction | Auto-summarize full context | +| Agent | Task-specific AI persona | +| MCP | External tool integrations | + +## TUI Slash Commands {.cols-3} + +### All Commands {.row-span-2} + +| Command | Keybind | Description | +| ----------- | ------- | ----------------------------- | +| `/connect` | | Add provider API key | +| `/init` | `i` | Create / update AGENTS.md | +| `/new` | `n` | New session (alias: `/clear`) | +| `/sessions` | `l` | List & switch sessions | +| `/models` | `m` | List available models | +| `/themes` | `t` | List & change themes | +| `/compact` | `c` | Compact session context | +| `/undo` | `u` | Undo last message + edits | +| `/redo` | `r` | Redo undone message | +| `/share` | `s` | Share session (get URL) | +| `/unshare` | | Remove shared session | +| `/export` | `x` | Export to Markdown | +| `/editor` | `e` | Open `$EDITOR` for input | +| `/details` | `d` | Toggle tool details | +| `/thinking` | | Toggle reasoning blocks | +| `/help` | `h` | Show help dialog | +| `/exit` | `q` | Exit (alias: `/quit`, `/q`) | + +{.show-header} + +`` = leader key (default `ctrl+x`) + +### Input Tips + +| Syntax | Effect | +| ------------- | -------------------------- | +| `@filename` | Fuzzy file reference | +| `!command` | Run shell command inline | +| `Tab` | Cycle agent mode | +| `Shift+Tab` | Reverse cycle agent | +| `Drag & drop` | Attach image to prompt | +| `Ctrl+P` | Command palette | +| `Ctrl+T` | Cycle model variant | +| `F2` | Cycle recent model | +| `Escape` | Interrupt running response | + +### Editor Setup + +```bash +# For terminal editors +export EDITOR=nvim +export EDITOR=vim + +# For GUI editors (need --wait) +export EDITOR="code --wait" +export EDITOR="cursor --wait" +export EDITOR="zed --wait" +``` + +Add to `~/.zshrc` or `~/.bashrc` to persist. + +## Keyboard Shortcuts {.cols-3} + +### Session Controls {.row-span-2} + +| Shortcut | Action | +| ------------ | ---------------------- | +| `Ctrl+X` `N` | New session | +| `Ctrl+X` `L` | Sessions list | +| `Ctrl+X` `C` | Compact session | +| `Ctrl+X` `U` | Undo last message | +| `Ctrl+X` `R` | Redo message | +| `Ctrl+X` `S` | Share session | +| `Ctrl+X` `X` | Export to Markdown | +| `Ctrl+X` `E` | Open editor | +| `Ctrl+X` `M` | Model picker | +| `Ctrl+X` `A` | Agent picker | +| `Ctrl+X` `T` | Theme picker | +| `Ctrl+X` `H` | Help / command palette | +| `Ctrl+X` `Q` | Exit | +| `Ctrl+X` `D` | Toggle tool details | +| `Ctrl+X` `B` | Toggle sidebar | +| `Ctrl+X` `G` | Session timeline | +| `Ctrl+X` `Y` | Copy messages | +| `Escape` | Interrupt response | +| `Ctrl+P` | Command palette | +| `Ctrl+T` | Cycle model variant | +| `F2` | Next recent model | +| `Shift+F2` | Prev recent model | +| `Tab` | Cycle agent forward | +| `Shift+Tab` | Cycle agent backward | + +{.shortcuts} + +### Scroll Navigation + +| Shortcut | Action | +| -------------------- | ---------------- | +| `Page Up` | Scroll page up | +| `Page Down` | Scroll page down | +| `Ctrl+Alt+Y` | Scroll line up | +| `Ctrl+Alt+E` | Scroll line down | +| `Ctrl+Alt+U` | Half page up | +| `Ctrl+Alt+D` | Half page down | +| `Ctrl+G` / `Home` | Jump to top | +| `Ctrl+Alt+G` / `End` | Jump to bottom | + +{.shortcuts} + +### Input Editing + +| Shortcut | Action | +| -------------- | ------------------ | +| `Ctrl+A` | Start of line | +| `Ctrl+E` | End of line | +| `Alt+B` | Word backward | +| `Alt+F` | Word forward | +| `Ctrl+K` | Kill to line end | +| `Ctrl+U` | Kill to line start | +| `Ctrl+W` | Kill prev word | +| `Alt+D` | Kill next word | +| `Ctrl+V` | Paste | +| `Return` | Submit message | +| `Shift+Return` | New line in input | + +{.shortcuts} + +## CLI Commands {.cols-2} + +### All Commands {.row-span-3} + +| Command | Description | +| ---------------------------- | ----------------------------- | +| `opencode` | Start TUI | +| `opencode [path]` | Start TUI in directory | +| `opencode run [msg]` | Headless/non-interactive run | +| `opencode serve` | Headless HTTP API server | +| `opencode web` | HTTP server + web UI | +| `opencode attach [url]` | Attach TUI to remote server | +| `opencode acp` | Start ACP (JSON-RPC) server | +| `opencode agent create` | Create new agent | +| `opencode agent list` | List agents | +| `opencode auth login` | Configure provider API key | +| `opencode auth list` | List authenticated providers | +| `opencode auth logout` | Remove provider credentials | +| `opencode mcp add` | Add MCP server | +| `opencode mcp list` | List MCP servers | +| `opencode mcp auth [name]` | Authenticate OAuth MCP server | +| `opencode mcp logout [name]` | Remove MCP OAuth credentials | +| `opencode mcp debug ` | Debug MCP connection | +| `opencode models [provider]` | List available models | +| `opencode models --refresh` | Refresh models cache | +| `opencode session list` | List all sessions | +| `opencode stats` | Show token & cost stats | +| `opencode export [id]` | Export session as JSON | +| `opencode import ` | Import session / share URL | +| `opencode github install` | Set up GitHub Actions agent | +| `opencode github run` | Run GitHub agent | +| `opencode upgrade [ver]` | Upgrade to latest / specific | +| `opencode uninstall` | Uninstall opencode | + +{.bold-first} + +### Headless Mode + +```bash +# Basic print/run +$ opencode run "Summarize this codebase" + +# Continue last session +$ opencode run -c "Fix the lint errors" + +# Specific session +$ opencode run -s "Add tests" + +# Fork a session +$ opencode run -s --fork "Try different approach" + +# Attach files +$ opencode run -f diagram.png "Implement this" + +# JSON output +$ opencode run "List all TODOs" --format json + +# Share the session +$ opencode run --share "Refactor auth module" + +# Attach to running server +$ opencode serve & +$ opencode run --attach http://localhost:4096 "task" +``` + +### Server & Remote + +```bash +# Headless API server +$ opencode serve --port 4096 + +# Web UI server +$ opencode web --port 4096 --hostname 0.0.0.0 + +# Enable mDNS discovery +$ opencode serve --mdns + +# Enable basic auth +$ OPENCODE_SERVER_PASSWORD=secret opencode serve + +# ACP server (JSON-RPC over stdio) +$ opencode acp --cwd /my/project + +# Attach TUI to remote server +$ opencode attach http://10.20.30.40:4096 +``` + +## CLI Flags {.cols-3} + +### TUI Flags + +| Flag | Short | Description | +| ------------ | ----- | ------------------------ | +| `--continue` | `-c` | Continue last session | +| `--session` | `-s` | Session ID to use | +| `--fork` | | Fork on continue | +| `--prompt` | | Initial prompt | +| `--model` | `-m` | Model (`provider/model`) | +| `--agent` | | Agent to use | +| `--port` | | Port to listen on | +| `--hostname` | | Hostname to listen on | + +{.show-header} + +### Run Flags + +| Flag | Short | Description | +| ------------ | ----- | --------------------- | +| `--continue` | `-c` | Continue last session | +| `--session` | `-s` | Session ID to use | +| `--fork` | | Fork on continue | +| `--model` | `-m` | Model to use | +| `--agent` | | Agent to use | +| `--file` | `-f` | Attach file(s) | +| `--format` | | `default` or `json` | +| `--share` | | Share the session | +| `--title` | | Set session title | +| `--attach` | | Attach to server URL | +| `--port` | | Local server port | + +{.show-header} + +### Global Flags + +| Flag | Short | Description | +| -------------- | ----- | --------------------- | +| `--help` | `-h` | Display help | +| `--version` | `-v` | Print version | +| `--print-logs` | | Print logs to stderr | +| `--log-level` | | DEBUG/INFO/WARN/ERROR | + +{.show-header} + +## Configuration {.cols-2} + +### opencode.json {.row-span-2} + +Main config at `~/.config/opencode/opencode.json` or `./opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "model": "anthropic/claude-sonnet-4-5", + "small_model": "anthropic/claude-haiku-4-5", + "default_agent": "build", + "autoupdate": true, + "snapshot": true, + "share": "manual", + "instructions": ["AGENTS.md", "docs/*.md"], + "provider": { + "anthropic": { + "options": { "timeout": 600000 } + } + }, + "permission": { + "edit": "ask", + "bash": "ask" + }, + "compaction": { + "auto": true, + "prune": true, + "reserved": 10000 + }, + "server": { + "port": 4096, + "mdns": true + }, + "tools": { + "write": false, + "bash": false + }, + "disabled_providers": ["openai"], + "enabled_providers": ["anthropic"] +} +``` + +### tui.json + +TUI config at `~/.config/opencode/tui.json`: + +```json +{ + "$schema": "https://opencode.ai/tui.json", + "theme": "tokyonight", + "scroll_speed": 3, + "scroll_acceleration": { + "enabled": true + }, + "diff_style": "auto", + "keybinds": { + "leader": "ctrl+x", + "session_compact": "none" + } +} +``` + +### Config Locations + +| Source | Path | Priority | +| ------------ | ---------------------------------- | ----------- | +| Remote | `.well-known/opencode` | 1 (lowest) | +| Global | `~/.config/opencode/opencode.json` | 2 | +| Custom | `$OPENCODE_CONFIG` path | 3 | +| Project | `./opencode.json` | 4 | +| `.opencode/` | agents/, commands/, plugins/ | 5 | +| Inline | `OPENCODE_CONFIG_CONTENT` | 6 (highest) | + +{.show-header} + +Configs **merge** — later sources override conflicting keys only. + +### Variable Substitution + +```json +{ + "model": "{env:OPENCODE_MODEL}", + "provider": { + "openai": { + "options": { + "apiKey": "{env:OPENAI_API_KEY}" + } + }, + "anthropic": { + "options": { + "apiKey": "{file:~/.secrets/anthropic}" + } + } + } +} +``` + +## Environment Variables {.cols-2} + +### Core Variables {.row-span-2} + +| Variable | Type | Description | +| ------------------------------- | ------ | --------------------------------- | +| `OPENCODE_CONFIG` | string | Custom config file path | +| `OPENCODE_TUI_CONFIG` | string | Custom TUI config path | +| `OPENCODE_CONFIG_DIR` | string | Custom config directory | +| `OPENCODE_CONFIG_CONTENT` | string | Inline JSON config | +| `OPENCODE_PERMISSION` | string | Inline JSON permissions | +| `OPENCODE_AUTO_SHARE` | bool | Auto-share sessions | +| `OPENCODE_SERVER_PASSWORD` | string | Basic auth for serve/web | +| `OPENCODE_SERVER_USERNAME` | string | Auth username (default: opencode) | +| `OPENCODE_MODELS_URL` | string | Custom models config URL | +| `OPENCODE_ENABLE_EXA` | bool | Enable Exa web search | +| `OPENCODE_DISABLE_AUTOUPDATE` | bool | Disable update checks | +| `OPENCODE_DISABLE_PRUNE` | bool | Disable old data pruning | +| `OPENCODE_DISABLE_AUTOCOMPACT` | bool | Disable auto-compaction | +| `OPENCODE_DISABLE_LSP_DOWNLOAD` | bool | Disable LSP auto-download | +| `OPENCODE_DISABLE_MODELS_FETCH` | bool | Disable remote model fetch | +| `OPENCODE_DISABLE_CLAUDE_CODE` | bool | Disable .claude/ reading | +| `OPENCODE_GIT_BASH_PATH` | string | Git Bash path (Windows) | +| `OPENCODE_CLIENT` | string | Client ID (default: cli) | + +{.show-header} + +### Experimental Variables + +| Variable | Description | +| ----------------------------------------------- | -------------------------------- | +| `OPENCODE_EXPERIMENTAL` | Enable all experimental features | +| `OPENCODE_EXPERIMENTAL_PLAN_MODE` | Enable plan mode | +| `OPENCODE_EXPERIMENTAL_LSP_TOOL` | Enable experimental LSP tool | +| `OPENCODE_EXPERIMENTAL_FILEWATCHER` | Enable full-dir file watcher | +| `OPENCODE_EXPERIMENTAL_MARKDOWN` | Experimental markdown features | +| `OPENCODE_EXPERIMENTAL_EXA` | Experimental Exa features | +| `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` | Max output tokens override | +| `OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | Bash timeout in ms | + +## Also see {.cols-1} + +- [OpenCode Docs](https://opencode.ai/docs) _(opencode.ai)_ +- [CLI Reference](https://opencode.ai/docs/cli/) _(opencode.ai)_ +- [TUI Guide](https://opencode.ai/docs/tui/) _(opencode.ai)_ +- [Config Reference](https://opencode.ai/docs/config) _(opencode.ai)_ +- [GitHub Repository](https://github.com/anomalyco/opencode) _(github.com)_