tutorials/HowToUse_HarnessOpenCode.md

# 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.*