opencode

# OpenCode Skill **OpenCode** is an open-source AI coding agent designed for terminal, IDE, and headless automation use. It features a unique multi-agent architecture with specialized modes for planning vs execution, native MCP server support, and an ACP server for A2A communication. ## Why OpenCode? - **Multi-agent system**: Separate \`plan\` (analysis) and \`build\` (execution) agents - **Provider agnostic**: Works with Kimi, Claude, GPT, Gemini, and 75+ providers - **MCP native**: Built-in MCP server support via \`opencode mcp\` - **ACP native**: Built-in ACP server for A2A via \`opencode acp\` - **Headless automation**: Server mode (\`serve\`) for programmatic access - **Local first**: Privacy-focused, no code sent to external servers - **Default model**: Pre-configured to use \`kimi-for-coding/k2p5\` --- ## ⚠️ PTY Mode Required OpenCode requires a pseudo-terminal (PTY) for proper interaction. Without PTY, output breaks or the session hangs. \`\`\`bash # ✅ Correct - with PTY bash pty:true command:"opencode run 'Your task'" # ❌ Wrong - will break or hang bash command:"opencode run 'Your task'" \`\`\` ### Bash Parameters for OpenCode | Parameter | Type | Description | | ------------ | ------- | ----------------------------------------------------- | | \`command\` | string | The opencode command to run | | \`pty\` | boolean | **REQUIRED** for interactive TUI mode | | \`workdir\` | string | Working directory (agent context) | | \`background\` | boolean | Run in background, returns sessionId for monitoring | | \`timeout\` | number | Timeout in seconds (kills process on expiry) | | \`elevated\` | boolean | Run on host instead of sandbox | ### Process Tool Actions (for background sessions) | Action | Description | | -------- | ---------------------------------------------------- | | \`list\` | List all running sessions | | \`poll\` | Check if session is still running | | \`log\` | Get session output (with optional offset/limit) | | \`write\` | Send raw data to stdin | | \`submit\` | Send data + newline (like typing and pressing Enter) | | \`kill\` | Terminate the session | --- ## Core Concepts: Agent Architecture OpenCode has **Primary Agents** and **Subagents**: ### Primary Agents (switch with Tab or \`--prompt\`) | Agent | Mode | Tools | Use Case | | ------ | -------- | --------------------------- | -------------------------------------- | | \`build\` | primary | ALL (write, edit, bash) | **Default** - implementation & changes | | \`plan\` | primary | READ-ONLY | Analysis and planning (no changes) | **Switch agents:** \`\`\`bash # Plan mode (analysis only) bash pty:true command:"opencode run --prompt plan 'Analyze this codebase'" # Build mode (makes changes) - default bash pty:true command:"opencode run --prompt build 'Implement the feature'" \`\`\` ### Subagents (invoke with @mention) | Agent | Mode | Purpose | | ------------- | -------- | ----------------------------------- | | \`@explore\` | subagent | Fast codebase exploration (read-only) | | \`@general\` | subagent | Research and multi-step tasks | | \`@compaction\` | system | Context compaction (auto-invoked) | --- ## MCP (Model Context Protocol) OpenCode has native MCP server support. MCP lets OpenCode connect to external tools and data sources. ### Manage MCP Servers \`\`\`bash # List available MCP servers opencode mcp list # Add an MCP server opencode mcp add <server-name> <command> [args...] # Remove an MCP server opencode mcp remove <server-name> # Start an MCP server and use it in a session bash pty:true command:"opencode run 'Use the filesystem MCP to list all files in /project'" \`\`\` ### Common MCP Configurations \`\`\`bash # Filesystem MCP opencode mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/directory # GitHub MCP opencode mcp add git npx -y @modelcontextprotocol/server-github --token \$GITHUB_TOKEN # Brave Search MCP opencode mcp add search npx -y @modelcontextprotocol/server-brave-search --api-key \$BRAVE_API_KEY \`\`\` ### Using MCP in OpenCode Sessions Once an MCP server is configured, it is available in all OpenCode sessions. Just refer to it in your prompt: \`\`\`bash bash pty:true command:"opencode run 'Search the web using MCP to find the latest OpenCode release notes'" \`\`\` --- ## ACP (Agent Client Protocol) — A2A Communication ACP enables OpenCode to act as an A2A agent — exposed as a server that other agents or tools can communicate with programmatically. ### Start ACP Server \`\`\`bash # Start ACP server (background) bash pty:true background:true command:"opencode acp" # ACP server on custom port/host bash pty:true background:true command:"opencode acp --port 8080 --hostname 0.0.0.0" \`\`\` ### ACP Session Interaction \`\`\`bash # Create a new session curl -X POST http://localhost:8080/api/session -H 'Content-Type: application/json' -d '{"title": "My task"}' # Send a prompt to a session curl -X POST http://localhost:8080/api/session/{sessionId}/prompt -H 'Content-Type: application/json' -d '{"parts": [{"type": "text", "text": "Implement auth"}]}' # List sessions curl http://localhost:8080/api/sessions # Get session status curl http://localhost:8080/api/session/{sessionId} \`\`\` ### SDK Usage (JavaScript/TypeScript) \`\`\`javascript import { createOpencodeClient } from "@opencode-ai/sdk" const client = createOpencodeClient({ baseUrl: "http://localhost:8080" }) // Create session const session = await client.session.create({ body: { title: "My task" }}) // Send prompt const result = await client.session.prompt({ path: { id: session.id }, body: { parts: [{ type: "text", text: "Implement auth" }] } }) console.log(result) \`\`\` ### Editor Integration (Zed, JetBrains, Neovim) ACP is compatible with: - **Zed** — via CodeCompanion or native ACP client - **JetBrains IDEs** — via ACP plugin - **Neovim** — via Avante or CodeCompanion \`\`\`bash # Start ACP server for IDE integration bash pty:true background:true command:"opencode acp" \`\`\` --- ## Serve Mode (Headless Server) For programmatic integration without ACP: \`\`\`bash # Start headless server bash pty:true background:true command:"opencode serve --port 8080 --hostname 127.0.0.1" # Interact via curl curl -X POST http://localhost:8080/api/session -H 'Content-Type: application/json' -d '{"message":"Hello"}' \`\`\` --- ## Configuration OpenCode is pre-configured in \`~/.config/opencode/opencode.json\`: \`\`\`json { "\$schema": "https://opencode.ai/config.json", "model": "kimi-for-coding/k2p5" } \`\`\` **Override per command:** \`\`\`bash bash pty:true command:"opencode run -m kimi-for-coding/kimi-k2-thinking 'Complex task'" \`\`\` ### Project Configuration Create \`.opencode/opencode.json\` in your project: \`\`\`json { "\$schema": "https://opencode.ai/config.json", "model": "kimi-for-coding/k2p5", "agent": { "build": { "temperature": 0.1, "permission": { "edit": "allow", "bash": "ask" } } } } \`\`\` Initialize project analysis: \`\`\`bash # Creates AGENTS.md with project context bash pty:true workdir:~/project command:"opencode run '/init'" \`\`\` --- ## Usage Patterns ### Pattern 1: Planning → Execution (Recommended) \`\`\`bash # Step 1: Planning (read-only) bash pty:true workdir:~/project background:true command:"opencode run --prompt plan 'Design a user authentication system with JWT tokens'" # Returns sessionId: PLAN_SESSION # Monitor plan process action:log sessionId:PLAN_SESSION # Step 2: Execution (with the plan) bash pty:true workdir:~/project background:true command:"opencode run --prompt build 'Implement the authentication system based on the plan'" \`\`\` ### Pattern 2: One-Shot Tasks \`\`\`bash # Direct execution with default build agent bash pty:true workdir:~/project command:"opencode run 'Add error handling to the API routes'" # With specific model bash pty:true workdir:~/project command:"opencode run -m kimi-for-coding/k2p5 'Refactor the auth module'" \`\`\` ### Pattern 3: Background Long-Running Tasks \`\`\`bash # Start in background with PTY bash pty:true workdir:~/project background:true command:"opencode run --prompt build 'Refactor the entire codebase to TypeScript'" # Returns: sessionId # Check progress process action:log sessionId:XXX offset:0 limit:50 # Check if still running process action:poll sessionId:XXX # Kill if needed process action:kill sessionId:XXX \`\`\` ### Pattern 4: Code Review \`\`\`bash # Review PR in temp directory (never in live project!) REVIEW_DIR=\$(mktemp -d) git clone https://github.com/user/repo.git \$REVIEW_DIR cd \$REVIEW_DIR && gh pr checkout 123 bash pty:true workdir:\$REVIEW_DIR command:"opencode run --prompt plan 'Review this PR for bugs, security issues, and best practices'" # Cleanup bash command:"rm -rf \$REVIEW_DIR" \`\`\` --- ## Lead Dev → Coding Agent Integration ### 1. Lead Dev Planning Phase \`\`\`bash # Lead dev spawns OpenCode in plan mode for analysis bash pty:true workdir:~/project background:true command:"opencode run --prompt plan 'Analyze requirements and create implementation plan for [FEATURE]'" # Returns: PLAN_SESSION # Lead dev monitors and extracts plan process action:log sessionId:PLAN_SESSION # Lead dev updates project management with plan \`\`\` ### 2. Coding Agent Execution Phase \`\`\`bash # Coding agent receives plan from Lead Dev bash pty:true workdir:~/project background:true command:"opencode run --prompt build 'Implement [FEATURE] according to the approved plan. Plan: [PASTE_PLAN_HERE]'" # Returns: BUILD_SESSION # Monitor implementation process action:log sessionId:BUILD_SESSION # Report completion to Lead Dev \`\`\` ### 3. Parallel Execution (Multiple Features) \`\`\`bash # Multiple coding agents working in parallel bash pty:true workdir:/tmp/feature-a background:true command:"opencode run --prompt build 'Implement feature A'" bash pty:true workdir:/tmp/feature-b background:true command:"opencode run --prompt build 'Implement feature B'"