| # OpenCode Harness — Referenz-Guide |
|
|
| > Für Samuel: Du kennst Claude Code in- und auswendig. Dieser Guide erklärt OpenCode im direkten Vergleich. |
|
|
| --- |
|
|
| ## 1. Architektur |
|
|
| OpenCode ist ein autonomer Coding-Agent mit TUI-Frontend und headless-fähigem Backend. |
|
|
| ``` |
| opencode (CLI) |
| ├── TUI — interaktive Terminal-UI (Standard bei `opencode`) |
| ├── opencode run — one-shot Execution (kein TUI) |
| ├── opencode serve — headless HTTP-Server |
| ├── opencode web — Web-UI |
| └── opencode acp — ACP-Protocol für Editor-Integration |
| ``` |
|
|
| **Config-Schichten** (von global nach lokal): |
|
|
| | Layer | Pfad | Scope | |
| |-------|------|-------| |
| | Credentials | `~/.local/share/opencode/auth.json` | Provider-Auth | |
| | Globale Config | `~/.config/opencode/` | User-weit | |
| | Projekt-Config | `./opencode.json` | Per-Project (override) | |
| | Plugins | `./plugins/*.ts` | Per-Project TypeScript Hooks | |
| | Commands | `./commands/` | Custom Slash-Commands | |
|
|
| **Agent-System:** 5 Built-in Agents (`build`, `plan`, `summary`, `title`, `compaction`) + Subagents (`explore`, `general`). Kein Equivalent zu Claude Codes 21 Markdown-Agenten — OpenCode-Agents sind codebasiert, nicht deklarativ konfigurierbar (außer via `opencode agent create`). |
|
|
| **Storage:** SQLite DB unter `~/.local/share/opencode/opencode.db` + JSON-Snapshots. Sessions persistieren lokal, aber **kein Gedächtnis zwischen `opencode run`-Aufrufen**. |
|
|
| --- |
|
|
| ## 2. Konfiguration |
|
|
| **Minimale `opencode.json`:** |
|
|
| ```json |
| { |
| "$schema": "https://opencode.ai/schema/config.json", |
| "provider": { |
| "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" } |
| }, |
| "model": { |
| "default": { "provider": "anthropic", "model": "claude-sonnet-4-5" }, |
| "fast": { "provider": "anthropic", "model": "claude-haiku-4-5-20251001" } |
| }, |
| "permission": "allow" |
| } |
| ``` |
|
|
| **Permission-Modi** (`"permission"` Key): |
|
|
| | Modus | Verhalten | Empfohlen für | |
| |-------|-----------|---------------| |
| | `ask` | Fragt bei unbekannten Ops (Default) | Interaktiv/TUI | |
| | `auto-edit` | Edits erlaubt, Shell-Ops werden gefragt | Semi-automatisch | |
| | `allow` | Alles erlaubt ohne Rückfrage | Headless/CI | |
|
|
| > Wichtig: Ohne `"permission": "allow"` in headless-Szenarien können Sessions blockieren — OpenCode wartet auf manuelle Bestätigung. |
|
|
| **MCP-Server einbinden:** |
|
|
| ```json |
| { |
| "mcp": { |
| "filesystem": { |
| "command": "npx", |
| "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/smlflg/Projekte"] |
| } |
| } |
| } |
| ``` |
|
|
| **Experimental Plugins** (TypeScript Hooks): |
|
|
| ```json |
| { |
| "experimental": { |
| "chat": { |
| "system": { "transform": "plugins/context-injection.ts" } |
| } |
| } |
| } |
| ``` |
|
|
| --- |
|
|
| ## 3. Tuning |
|
|
| ### Modell wählen |
|
|
| ```bash |
| # CLI-Flag (override für einzelnen Lauf) |
| opencode run "prompt" -m anthropic/claude-opus-4-6 |
| |
| # Reasoning-Varianten (für Modelle mit Extended Thinking) |
| opencode run --variant high "..." # 16K Reasoning Tokens |
| opencode run --variant max "..." # 31.9K Reasoning Tokens |
| opencode run --variant minimal "..." # kein Reasoning |
| ``` |
|
|
| ### Multi-Provider — der echte Vorteil gegenüber Claude Code |
|
|
| ```json |
| { |
| "provider": { |
| "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" }, |
| "openai": { "apiKey": "${OPENAI_API_KEY}" }, |
| "minimax": { "apiKey": "${MINIMAX_API_KEY}" } |
| } |
| } |
| ``` |
|
|
| MiniMax kostet ca. $0.10/1M Tokens — ~150x günstiger als Opus. Sinnvoll für Batch-Tasks ohne Qualitätsanspruch. |
|
|
| ### Agent auswählen |
|
|
| ```bash |
| opencode run --agent explore "..." # Explore-Agent (darf fragen, kein Edit) |
| opencode run --agent build "..." # Build-Agent (volle Rechte) |
| opencode agent create # Custom Agent anlegen |
| opencode agent list # Verfügbare Agents zeigen |
| ``` |
|
|
| **Agent-Permissions im Überblick:** |
|
|
| | Permission | build | plan | explore | general | |
| |-----------|-------|------|---------|---------| |
| | bash | allow | allow | allow | allow | |
| | edit | context | context | deny | deny | |
| | external_dir | ask | ask | ask | ask | |
| | question | deny | deny | allow | allow | |
| |
| ### Context-Injection via Plugin |
| |
| Kein CLAUDE.md-Equivalent — Kontext muss über TypeScript-Hook injiziert werden: |
| |
| ```typescript |
| // plugins/context-injection.ts |
| export default function transform(system: string): string { |
| return system + "\n\n# Projekt-Regeln\n- Kein apt ohne Rückfrage\n- Tests vor Commit"; |
| } |
| ``` |
| |
| ### Parallele Runs |
| |
| ```bash |
| # Mehrere one-shot Tasks gleichzeitig — OpenCode unterstützt parallele Instanzen |
| opencode run "Task A" & |
| opencode run "Task B" & |
| wait |
| ``` |
| |
| ### Debug |
| |
| ```bash |
| opencode debug config # Resolved Config anzeigen (inkl. Env-Var-Expansion) |
| opencode debug paths # Alle relevanten Dateipfade |
| opencode debug agent build # Agent-Details: System-Prompt, Permissions |
| opencode debug lsp # LSP-Status |
| ``` |
| |
| --- |
| |
| ## 4. Vor- und Nachteile |
| |
| ### Vorteile |
| |
| | Feature | Bewertung | |
| |---------|-----------| |
| | Multi-Provider | Nicht auf Anthropic locked — OpenAI, MiniMax, Custom-Endpoints möglich | |
| | Kosten | MiniMax ~$0.10/1M Tokens für Batch-Tasks | |
| | One-shot | `opencode run` ideal für skriptbare Pipelines | |
| | Parallele Instanzen | Mehrere Runs gleichzeitig ohne Konflikte | |
| | Server-Mode | `opencode serve` für API-basierte Integration | |
| | Debug-Tools | `opencode debug` deckt Config, Paths, Agents ab | |
| | MCP native | CLI-Management von MCP Servern ohne JSON-Editierung | |
| | Reasoning-Varianten | high/max/minimal direkt als Flag | |
| |
| ### Nachteile — ehrliche Einschätzung |
| |
| | Problem | Konsequenz | |
| |---------|------------| |
| | Fragt NICHT nach | Unvollständiges Briefing → falsches Produkt. OpenCode baut, was es versteht — nicht was du meinst. | |
| | Schwache Feedback-Annahme | Korrekturen werden bestätigt, nicht wirklich integriert ("Verstanden, soll ich nochmal?") | |
| | Scope-Drift | Ohne explizites Scope-Statement erweitert OpenCode selbstständig den Auftrag | |
| | Kein Session-Gedächtnis | `opencode run` startet jedes Mal blank — kein Kontext aus Vorläufen | |
| | Plugins experimental | Hooks weniger mächtig als Claude Codes 5-Punkt-Lifecycle (PreToolUse, PostToolUse etc.) | |
| | Kein deklaratives Regelwerk | Kein CLAUDE.md-Equivalent — Regeln müssen per Hook injiziert werden | |
| | Keine Subagent-Orchestrierung | Agents sind intern; kein paralleles Agent-Spawning wie in Claude Code möglich | |
| |
| **Fazit:** OpenCode ist stark für gut-spezifizierte one-shot Tasks, Multi-Provider-Flexibilität und headless Pipelines. Für komplexe, iterative Arbeit mit Kontext-Aufbau bleibt Claude Code überlegen. |
| |
| --- |
| |
| ## 5. Referenz |
| |
| ### Dateipfade |
| |
| | Pfad | Inhalt | |
| |------|--------| |
| | `./opencode.json` | Projekt-Config (per-project override) | |
| | `~/.config/opencode/` | Globale Config | |
| | `~/.local/share/opencode/` | Data-Root | |
| | `~/.local/share/opencode/auth.json` | Provider-Credentials | |
| | `~/.local/share/opencode/opencode.db` | SQLite Session-DB | |
| | `./plugins/` | TypeScript Hooks (per-project) | |
| | `./commands/` | Custom Slash-Commands (per-project) | |
| |
| ### Wichtige Befehle |
| |
| ```bash |
| # Starten |
| opencode # TUI |
| opencode run "prompt" # One-shot |
| opencode run "prompt" -m provider/model # Mit Modell-Auswahl |
| opencode run --variant max "prompt" # Max Reasoning |
| opencode serve --port 4096 # Headless Server |
| |
| # Provider & Modelle |
| opencode providers list # Konfigurierte Provider |
| opencode providers login anthropic # Auth-Flow |
| opencode models anthropic # Verfügbare Modelle für Provider |
| |
| # MCP |
| opencode mcp list # Konfigurierte MCP Server |
| opencode mcp add name -- command # MCP Server hinzufügen |
| opencode mcp remove name # MCP Server entfernen |
| |
| # Agents |
| opencode agent list # Verfügbare Agents |
| opencode agent create # Custom Agent anlegen |
| |
| # Debug |
| opencode debug config # Resolved Config |
| opencode debug paths # Alle Pfade |
| opencode debug agent <name> # Agent-Details |
| opencode debug lsp # LSP-Status |
| opencode debug skill # Skill-Status |
| ``` |
| |
| --- |
| |
| *Stand: 2026-03 — Getestet gegen OpenCode MCP-Server und Harness-Evals im harness-tutorials Projekt.* |
| |
