1 line
15 KiB
JSON
1 line
15 KiB
JSON
{"repo": "babico/teslacanmodder", "files": {"docs/guides/opencode-setup.md": {"2bc62a68dda3544a80c481469b3ecea5294e653d": {"t": 1785846942.5860734, "n": 14556, "h": "3d46aac74b66aa36", "c": "---\ntitle: OpenCode Setup\ntitle_tr: OpenCode Kurulumu\ndescription: Complete guide to OpenCode AI agent setup, MCP servers, skills, and GitHub integration for TeslaCANModder\ncategory: guides\nfolder: guides\ntags: [opencode, ai, agents, mcp, skills, github]\norder: 20\nicon: 🤖\n---\n\n# OpenCode Setup Guide\n\n```mermaid\nflowchart LR\n OC[\"OpenCode\"] --> Skills[\".opencode/skills/<br/>(load project skills)\"]\n OC --> MCP[\"MCP servers<br/>(github, etc.)\"]\n OC --> Agent[\"Subagents<br/>(code, general, etc.)\"]\n Skills --> Help[\"In-context guidance<br/>(can-protocol-safety,<br/>refactor-over-duplication, …)\"]\n MCP --> Ext[\"External tools<br/>(gh, playwright)\"]\n Agent --> Tasks[\"Multi-step task delegation\"]\n classDef oc fill:#1e3a5f,stroke:#4a7fb5,color:#fff\n class OC,Skills,MCP,Agent oc\n```\n\nThis project uses [OpenCode](https://opencode.ai) for AI-powered development assistance. This guide covers local setup, MCP servers, agent skills, GitHub integration, and usage.\n\n---\n\n## Table of Contents\n\n1. [Quick Start](#quick-start)\n2. [Configuration](#configuration)\n3. [MCP Servers](#mcp-servers)\n4. [Agent Skills](#agent-skills)\n5. [Custom Commands](#custom-commands)\n6. [GitHub Integration](#github-integration)\n7. [Agents](#agents)\n8. [LSP & Formatters](#lsp--formatters)\n9. [Troubleshooting](#troubleshooting)\n\n---\n\n## Quick Start\n\n### 1. Install OpenCode\n\nDownload from [opencode.ai](https://opencode.ai) or install via package manager:\n\n```bash\n# macOS (Homebrew)\nbrew install opencode\n\n# Windows (Winget)\nwinget install Anomaly.OpenCode\n\n# Or download directly from https://opencode.ai\n```\n\n### 2. Get API Key\n\nThis project is configured to use **OpenCode Go** ($5 first month, then $10/month):\n\n1. Sign in at [opencode.ai/auth](https://opencode.ai/auth)\n2. Subscribe to **OpenCode Go**\n3. Copy your API key\n\n### 3. Connect\n\n```bash\n# In the TUI, run:\n/connect\n# Select \"OpenCode Go\" and paste your API key\n```\n\nOr set the environment variable:\n\n```bash\n# Windows (PowerShell)\n$env:OPENCODE_GO_API_KEY = \"your-key-here\"\n\n# macOS/Linux\nexport OPENCODE_GO_API_KEY=\"your-key-here\"\n```\n\n### 4. Navigate to Project\n\n```bash\ncd path/to/TeslaCANModder\nopencode\n```\n\nOpenCode will auto-load `opencode.json` and discover skills in `.opencode/skills/`.\n\n---\n\n## Configuration\n\nThe project config lives in [`opencode.json`](../../opencode.json) at the repository root.\n\n### Key Settings\n\n| Setting | Value | Description |\n| ------------- | -------------------------- | ---------------------------------------- |\n| `model` | `opencode-go/kimi-k2.6` | Main coding model |\n| `small_model` | `opencode-go/qwen3.5-plus` | Fast tasks (titles, etc.) |\n| `shell` | `pwsh` | Default shell on Windows |\n| `share` | `manual` | Conversations shared only when requested |\n\n### Instructions\n\nOpenCode reads these files for project context:\n\n- `AGENTS.md` - Project overview and rules\n- `CONTRIBUTING.md` - Contribution guidelines\n- `docs/reference/commands.md` - Command reference\n- `docs/reference/can-protocol.md` - CAN protocol reference\n\n### Provider Setup\n\n```json\n{\n \"provider\": {\n \"opencode-go\": {\n \"options\": {\n \"apiKey\": \"{env:OPENCODE_GO_API_KEY}\"\n }\n }\n }\n}\n```\n\nUses environment variable substitution. The `{env:VAR}` syntax reads from your shell environment.\n\n---\n\n## MCP Servers\n\n[MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers extend OpenCode with additional tools.\n\n### Available Servers\n\n| Server | Package | Purpose | When to Enable |\n| ---------------------- | ------------------------------------------------- | ------------------------- | ------------------------------------- |\n| **github** | `@github/github-mcp-server` | GitHub issues, PRs, repos | When managing GitHub issues/PRs |\n| **playwright** | `@playwright/mcp` | Browser automation | When testing web client UI |\n| **memory** | `@modelcontextprotocol/server-memory` | Persistent memory | When you want context across sessions |\n| **sequentialthinking** | `@modelcontextprotocol/server-sequentialthinking` | Step-by-step reasoning | Complex CAN analysis, debugging |\n| **time** | `@modelcontextprotocol/server-time` | Time utilities | Scheduling, timestamps |\n| **superpowers** | `superpowers-mcp` | General utilities | Enhanced capabilities |\n\nAll servers are **disabled by default** to save context tokens.\n\n### Enable a Server\n\n**In TUI:**\n\n```\n/opencode mcp enable github\n```\n\n**In config (`opencode.json`):**\n\n```json\n{\n \"mcp\": {\n \"github\": {\n \"enabled\": true\n }\n }\n}\n```\n\n**Per-agent:**\n\n```json\n{\n \"tools\": {\n \"github*\": false\n },\n \"agent\": {\n \"my-agent\": {\n \"tools\": {\n \"github*\": true\n }\n }\n }\n}\n```\n\n### Environment Variables\n\n| Server | Variable | Required |\n| ------ | -------------- | -------- |\n| github | `GITHUB_TOKEN` | Yes |\n\nSet before starting OpenCode:\n\n```bash\n$env:GITHUB_TOKEN = \"ghp_xxxxxxxxxxxx\"\n```\n\n### Usage Examples\n\n**GitHub MCP:**\n\n```\nCreate an issue for the missing DLC guard in fsd.h\nList open pull requests\n```\n\n**Playwright MCP:**\n\n```\nOpen the client dashboard and screenshot the CAN frame viewer\nTest the flasher page in the browser\n```\n\n**Memory MCP:**\n\n```\nRemember my test board uses 16MHz crystal\nWhat did we decide about the Vehicle CAN bus wiring?\n```\n\n**Sequential Thinking MCP:**\n\n```\nUse sequential thinking to trace the FSD command from UI to CAN TX\nAnalyze the checksum calculation flow step by step\n```\n\n### Troubleshooting MCP\n\n```bash\n# List all MCP servers and status\nopencode mcp list\n\n# Debug a specific server\nopencode mcp debug github\n\n# View auth status\nopencode mcp auth list\n\n# Remove stored credentials\nopencode mcp logout github\n```\n\n---\n\n## Agent Skills\n\nSkills are reusable instruction sets stored in `.opencode/skills/<name>/SKILL.md`. OpenCode auto-discovers them and loads them on-demand.\n\n### Available Skills\n\n| Skill | Description | When to Load |\n| ---------------------- | --------------------------------------------------------- | ------------------------------- |\n| `firmware-development` | PlatformIO ESP32, build envs, CAN buses, feature patterns | Working in `firmware/` |\n| `can-protocol-safety` | DLC guards, checksums, variant behavior, bus routing | Changing CAN frame logic |\n| `client-development` | Expo React Native, state mgmt, hardware connections | Working in `client/` |\n| `protocol-package` | TypeScript ESM, commands, decoder data | Working in `packages/protocol/` |\n| `tools-development` | Debug CLI, serial bridge, validation scripts | Working in `tools/` |\n| `testing-validation` | Test matrix, CI checks, validation workflow | Running tests or QA |\n| `release-qa` | Release checklist, version alignment, rollback | Preparing releases |\n\n### Using Skills\n\nOpenCode lists available skills in the `skill` tool. The agent can load them automatically or you can prompt it:\n\n```\nUse the firmware-development skill to help me add a new CAN feature handler\n```\n\nOr let the agent detect and load the right skill based on what you're working on.\n\n### Skill Permissions\n\nAll skills are allowed globally. You can restrict per-agent in `opencode.json`:\n\n```json\n{\n \"agent\": {\n \"github-reviewer\": {\n \"permission\": {\n \"skill\": {\n \"can-protocol-safety\": \"allow\",\n \"firmware-development\": \"allow\",\n \"release-qa\": \"deny\"\n }\n }\n }\n }\n}\n```\n\n---\n\n## Custom Commands\n\nSlash commands are defined in `opencode.json` under the `command` key.\n\n### Available Commands\n\n| Command | Description |\n| ----------------- | --------------------------------------------------------------------------- |\n| `/test` | Run full test suite (`npm run test:all`) |\n| `/lint` | Run lint and format checks (`npm run lint:all`) |\n| `/build-firmware` | Build full firmware (`pio run -e esp32_wifi_ble_chassis_vehicle_body_8mhz`) |\n| `/test-firmware` | Run firmware native tests (`pio test -e native`) |\n\n### Usage\n\nIn the TUI:\n\n```\n/test\n```\n\nOr create your own:\n\n```json\n{\n \"command\": {\n \"flash\": {\n \"template\": \"Flash the firmware to COM4 using `cd firmware && .\\\\pio.ps1 run -e esp32_chassis_8mhz -t upload`. Report success or errors.\",\n \"description\": \"Flash firmware to device\"\n }\n }\n}\n```\n\n---\n\n## GitHub Integration\n\nOpenCode integrates with GitHub via the [OpenCode GitHub App](https://github.com/apps/opencode-agent) and GitHub Actions workflows.\n\n### Workflows\n\n| Workflow | Trigger | Purpose |\n| --------------------- | -------------------------------- | --------------------------------- |\n| `opencode.yml` | `/oc` or `/opencode` in comments | Fix issues, implement features |\n| `opencode-review.yml` | PR opened/updated | Automated code review |\n| `opencode-triage.yml` | New issue opened | Categorize and route issues |\n| `opencode-audit.yml` | Mondays 6am UTC | Weekly security/code health audit |\n\n### Setup\n\n1. **Install the app**: [github.com/apps/opencode-agent](https://github.com/apps/opencode-agent)\n2. **Add secret**: `OPENCODE_GO_API_KEY` in **Settings → Secrets → Actions**\n3. (Optional) Add `GITHUB_TOKEN` for enhanced GitHub operations\n\n### Usage in GitHub\n\n**Issues:**\n\n```\n/oc explain this issue\n/oc fix this\n```\n\n**PR Comments:**\n\n```\n/opencode review the CAN mutation logic\n/oc check if DLC guards are present\n```\n\n**Code Lines (Files tab):**\n\n```\n/oc add error handling here\n```\n\n### GitHub Model\n\nThe GitHub Action uses `opencode-go/kimi-k2.6` from your OpenCode Go subscription. This is cheaper than using Anthropic directly for automated reviews.\n\n---\n\n## Agents\n\n### Built-in Agents\n\n| Agent | Purpose | Tools |\n| ------- | ------------------------- | ----------- |\n| `code` | General coding tasks | Full access |\n| `plan` | Planning and architecture | Full access |\n| `build` | Build and compilation | Full access |\n\n### Custom Agents\n\n#### `github-reviewer`\n\nRead-only PR reviewer focused on CAN safety:\n\n```json\n{\n \"agent\": {\n \"github-reviewer\": {\n \"description\": \"Automated PR reviewer for TeslaCANModder\",\n \"model\": \"opencode-go/kimi-k2.6\",\n \"prompt\": \"You are a TeslaCANModder code reviewer. Focus on: CAN frame safety...\",\n \"tools\": {\n \"write\": false,\n \"edit\": false\n }\n }\n }\n}\n```\n\n### Creating Custom Agents\n\nAdd markdown files to `.opencode/agents/`:\n\n```markdown\n---\nname: can-expert\ndescription: CAN protocol expert for TeslaCANModder\nmodel: opencode-go/kimi-k2.6\n---\n\n## What I do\n\nSpecialize in Tesla CAN bus protocol analysis, frame decoding, and mutation logic.\n\n## When to use me\n\n- Analyzing CAN frame structures\n- Debugging bus routing issues\n- Reviewing checksum calculations\n```\n\n### Agent Permissions\n\nControl tool access per-agent:\n\n```json\n{\n \"agent\": {\n \"safe-mode\": {\n \"tools\": {\n \"bash\": false,\n \"write\": false\n }\n }\n }\n}\n```\n\n---\n\n## LSP & Formatters\n\n### LSP Servers\n\n| Server | Files | Purpose |\n| ---------- | -------------------- | -------------------------------- |\n| TypeScript | `.ts`, `.tsx` | Type checking, IntelliSense |\n| ESLint | `.ts`, `.tsx`, `.js` | Lint diagnostics |\n| clangd | `.cpp`, `.h`, `.c` | C++ code navigation, diagnostics |\n| Python | `.py` | Python support |\n| YAML | `.yml`, `.yaml` | YAML validation |\n| Bash | `.sh`, `.ps1` | Shell script support |\n\n### Formatters\n\n| Formatter | Files | Command |\n| ------------ | ------------------ | ---------------------- |\n| Prettier | JS/TS/JSON/MD/YAML | `npx prettier --write` |\n| clang-format | C/C++ | `clang-format -i` |\n\nFormat on save is supported via the TUI. Run `opencode` and use the formatter keybind.\n\n---\n\n## Troubleshooting\n\n### OpenCode doesn't load project config\n\n```bash\n# Verify config is valid\nopencode debug config\n\n# Check if skills are discovered\nopencode debug skills\n```\n\n### MCP server fails to start\n\n```bash\n# Check Node.js version (>= 18 required)\nnode --version\n\n# Debug the server\nopencode mcp debug <server-name>\n\n# Check if npx works\nnpx -y @github/github-mcp-server --help\n```\n\n### Skills not showing up\n\n- Verify `SKILL.md` is in all caps\n- Check frontmatter has `name` and `description`\n- Ensure skill name matches directory name exactly\n- Run `opencode debug skills` to see discovered skills\n\n### Model not responding\n\n```bash\n# Check provider connection\nopencode debug provider\n\n# Verify API key is set\necho $env:OPENCODE_GO_API_KEY # PowerShell\necho $OPENCODE_GO_API_KEY # bash\n```\n\n### Context too long\n\nIf you hit token limits:\n\n- Disable unused MCP servers\n- Use `compaction` settings (already configured with `reserved: 15000`)\n- Break tasks into smaller chunks\n\n---\n\n## Resources\n\n- [OpenCode Docs](https://opencode.ai/docs)\n- [OpenCode Go Models](https://opencode.ai/docs/go/)\n- [Agent Skills](https://opencode.ai/docs/skills/)\n- [MCP Servers](https://opencode.ai/docs/mcp-servers/)\n- [GitHub Integration](https://opencode.ai/docs/github/)\n- [Config Schema](https://opencode.ai/config.json)\n- [Project Config (`opencode.json`)](../../opencode.json)\n"}}}} |