Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat: add first-class OpenCode support (wrap, learn, mcp install) (#559)

T. P.91cd2102d7e9
diff --git a/docs/content/docs/failure-learning.mdx b/docs/content/docs/failure-learning.mdx
index 2dd1f0be2..15a4f58e1 100644
--- a/docs/content/docs/failure-learning.mdx
+++ b/docs/content/docs/failure-learning.mdx
@@ -139,7 +139,7 @@ Options:
--apply Write recommendations (default: dry-run)
--target TEXT Context file to write to, Claude Code only (default:
CLAUDE.local.md). Relative to project root, or absolute.
- --agent TEXT Agent to analyze (e.g. claude, codex, gemini)
+ --agent TEXT Agent to analyze (e.g. claude, codex, gemini, opencode)
--model TEXT LLM model to use for analysis
--workers INT Number of parallel workers
```
diff --git a/docs/content/docs/opencode.mdx b/docs/content/docs/opencode.mdx
index d82981a7b..a5df0fc3a 100644
--- a/docs/content/docs/opencode.mdx
+++ b/docs/content/docs/opencode.mdx
@@ -72,6 +72,16 @@ The default model is `headroom/claude-sonnet-4-6`. Change it in `opencode.json`
| `HEADROOM_PROXY_URL` | Proxy URL passed to the native `headroom-opencode` plugin. Defaults to `http://127.0.0.1:8787` inside the plugin |
| `HEADROOM_CONTEXT_TOOL` | Set to `lean-ctx` to use lean-ctx instead of RTK |
+## Failure Learning
+
+`headroom learn` supports OpenCode as a scan target. It reads past sessions from `~/.local/share/opencode/opencode.db` and writes corrections to your project's `AGENTS.md`.
+
+```bash
+headroom learn --agent opencode --apply
+```
+
+See [Failure Learning](/docs/failure-learning) for details on the learn system.
+
## Persistent Installs
`headroom install` supports OpenCode as a target for persistent provider wiring:
diff --git a/headroom/learn/plugins/opencode.py b/headroom/learn/plugins/opencode.py
new file mode 100644
index 000000000..ef16b56a4
--- /dev/null
+++ b/headroom/learn/plugins/opencode.py
@@ -0,0 +1,273 @@
+"""OpenCode plugin for headroom learn.
+
+Reads conversation data from the OpenCode SQLite database at
+``~/.local/share/opencode/opencode.db``.
+
+OpenCode stores messages and tool parts in two tables:
+- ``message``: one row per turn (user/assistant), with JSON ``data``
+- ``part``: one row per content part; tool parts have ``data.type == "tool"``
+
+A tool part looks like::
+
+ {
+ "type": "tool",
+ "tool": "bash",
+ "callID": "toolu_01...",
+ "state": {
+ "status": "completed" | "error",
+ "input": { ... },
+ "output": "..."
+ }
+ }
+
+``headroom learn opencode`` mines these for errors and writes corrections to
+the project's ``AGENTS.md`` file (OpenCode's native rules file).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .._shared import classify_error, is_error_content, normalize_tool_name
+from ..base import ConversationScanner, LearnPlugin
+from ..models import (
+ ErrorCategory,
+ ProjectInfo,
+ SessionData,
+ SessionEvent,
+ ToolCall,
+)
+from ..writer import CodexWriter, ContextWriter
+
+logger = logging.getLogger(__name__)
+
+_OPENCODE_DB = Path.home() / ".local" / "share" / "opencode" / "opencode.db"
+
+# Tool part status values that indicate failure.
+_ERROR_STATUSES = {"error", "failed", "aborted"}
+
+
+class OpenCodePlugin(LearnPlugin, ConversationScanner):
+ """Read OpenCode sessions from the SQLite database.
+
+ OpenCode stores all conversation data in a single SQLite file which makes
+ discovery fast — one file, many projects.
+ """
+
+ def __init__(self, db_path: Path | None = None) -> None:
+ self._db_path = db_path or _OPENCODE_DB
+
+ # ------------------------------------------------------------------
+ # LearnPlugin identity
+ # ------------------------------------------------------------------
+
+ @property
+ def name(self) -> str:
+ return "opencode"
+
+ @property
+ def display_name(self) -> str:
+ return "OpenCode"
+
+ @property
+ def description(self) -> str:
+ return "OpenCode (~/.local/share/opencode/opencode.db)"
+
+ def detect(self) -> bool:
+ return self._db_path.exists()
+
+ def create_writer(self) -> ContextWriter:
+ # Re-use CodexWriter — it writes to AGENTS.md, which is exactly what
+ # OpenCode reads.
+ return CodexWriter()
+
+ # ------------------------------------------------------------------
+ # ConversationScanner interface
+ # ------------------------------------------------------------------
+
+ def discover_projects(self) -> list[ProjectInfo]:
+ """Discover all projects that have at least one session."""
+ if not self.detect():
+ return []
+
+ try:
+ conn = sqlite3.connect(str(self._db_path))
+ except sqlite3.Error as exc:
+ logger.warning("Cannot open OpenCode DB %s: %s", self._db_path, exc)
+ return []
+
+ try:
+ cursor = conn.cursor()
+ cursor.execute(
+ "SELECT p.id, p.name, p.worktree "
+ "FROM project p "
+ "WHERE EXISTS (SELECT 1 FROM session s WHERE s.project_id = p.id)"
+ )
+ projects: list[ProjectInfo] = []
+ for row in cursor.fetchall():
+ proj_id, proj_name, worktree = row
+ worktree_path = Path(worktree) if worktree else Path("~").expanduser()
+ agents_md = worktree_path / "AGENTS.md"
+ projects.append(
+ ProjectInfo(
+ name=proj_name or worktree_path.name or proj_id,
+ project_path=worktree_path,
+ data_path=self._db_path.parent,
+ context_file=agents_md if agents_md.exists() else None,
+ )
+ )
+ finally:
+ conn.close()
+
+ return projects
+
+ def scan_project(
+ self, project: ProjectInfo, max_workers: int = 1, include_subagents: bool = True
+ ) -> list[SessionData]:
+ """Scan all sessions for a project and return normalized tool calls."""
+ if not self.detect():
+ return []
+
+ try:
+ conn = sqlite3.connect(str(self._db_path))
+ except sqlite3.Error as exc:
+ logger.warning("Cannot open OpenCode DB: %s", exc)
+ return []
+
+ try:
+ return self._scan_project_sessions(conn, project)
+ finally:
+ conn.close()
+
+ # ------------------------------------------------------------------
+ # Internal helpers
+ # ------------------------------------------------------------------
+
+ def _scan_project_sessions(
+ self, conn: sqlite3.Connection, project: ProjectInfo
+ ) -> list[SessionData]:
+ cursor = conn.cursor()
+
+ # Find the project ID from the worktree path.
+ cursor.execute(
+ "SELECT id FROM project WHERE worktree = ?",
+ (str(project.project_path),),
+ )
+ row = cursor.fetchone()
+ if row is None:
+ return []
+ project_db_id: str = row[0]
+
+ # Get all sessions for this project.
+ cursor.execute(
+ "SELECT id, time_created FROM session WHERE project_id = ? ORDER BY time_created DESC LIMIT 200",
+ (project_db_id,),
+ )
+ session_rows = cursor.fetchall()
+
+ sessions: list[SessionData] = []
+ for session_id, time_created in session_rows:
+ session = self._scan_session(conn, session_id, time_created)
+ if session is not None and session.tool_calls:
+ sessions.append(session)
+
+ return sessions
+
+ def _scan_session(
+ self,
+ conn: sqlite3.Connection,
+ session_id: str,
+ time_created: int | None,
+ ) -> SessionData | None:
+ cursor = conn.cursor()
+
+ # Get all tool parts for this session ordered by creation time.
+ cursor.execute(
+ """
+ SELECT p.data, p.time_created
+ FROM part p
+ JOIN message m ON p.message_id = m.id
+ WHERE m.session_id = ?
+ AND p.data LIKE '%"type"%tool%'
+ ORDER BY p.time_created
+ """,
+ (session_id,),
+ )
+ rows = cursor.fetchall()
+
+ tool_calls: list[ToolCall] = []
+ events: list[SessionEvent] = []
+
+ for idx, (data_raw, part_time) in enumerate(rows):
+ try:
+ data = json.loads(data_raw)
+ except json.JSONDecodeError:
+ continue
+
+ if data.get("type") != "tool":
+ continue
+
+ raw_tool_name = str(data.get("tool") or "unknown")
+ tool_name = (
+ "Bash" if raw_tool_name.lower() == "bash" else normalize_tool_name(raw_tool_name)
+ )
+ call_id = str(data.get("callID") or f"oc_{session_id}_{idx}")
+ state_raw = data.get("state")
+ state: dict = state_raw if isinstance(state_raw, dict) else {}
+ status = str(state.get("status") or "unknown")
+ input_raw = state.get("input")
+ input_data: dict = input_raw if isinstance(input_raw, dict) else {}
+ output: str = str(state.get("output") or "")
+
+ # Detect truncated output pointer.
+ if output == "...output truncated..." or output.startswith("...output truncated"):
+ truncated_ref = state.get("outputRef") or state.get("outputFile")
+ if truncated_ref:
+ try:
+ output = Path(truncated_ref).read_text(errors="replace")
+ except OSError:
+ pass
+
+ is_error = status in _ERROR_STATUSES or is_error_content(output)
+ error_cat = classify_error(output) if is_error else ErrorCategory.UNKNOWN
+
+ tc = ToolCall(
+ name=tool_name,
+ tool_call_id=call_id,
+ input_data=input_data,
+ output=output,
+ is_error=is_error,
+ error_category=error_cat,
+ msg_index=idx,
+ output_bytes=len(output.encode()),
+ )
+ tool_calls.append(tc)
+ part_ts = str(part_time) if part_time is not None else None
+ events.append(
+ SessionEvent(type="tool_call", msg_index=idx, timestamp=part_ts, tool_call=tc)
+ )
+
+ if not tool_calls:
+ return None
+
+ ts: datetime | None = None
+ if time_created is not None:
+ try:
+ ts = datetime.fromtimestamp(time_created / 1000, tz=timezone.utc)
+ except (OSError, OverflowError, ValueError):
+ pass
+
+ return SessionData(
+ session_id=session_id,
+ tool_calls=tool_calls,
+ events=events,
+ timestamp=ts,
+ )
+
+
+# Module-level instance — auto-discovered by the learn plugin registry.
+plugin = OpenCodePlugin()
diff --git a/tests/test_learn/test_opencode_scanner.py b/tests/test_learn/test_opencode_scanner.py
new file mode 100644
index 000000000..96ff2c366
--- /dev/null
+++ b/tests/test_learn/test_opencode_scanner.py
@@ -0,0 +1,119 @@
+"""Tests for the OpenCode learn scanner."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+from headroom.learn.models import ErrorCategory
+from headroom.learn.plugins.opencode import OpenCodePlugin
+from headroom.learn.registry import get_registry, reset_registry
+from headroom.learn.writer import CodexWriter
+
+
+def _create_opencode_db(db_path: Path, project_path: Path) -> None:
+ conn = sqlite3.connect(db_path)
+ try:
+ conn.executescript(
+ """
+ CREATE TABLE project (
+ id TEXT PRIMARY KEY,
+ name TEXT,
+ worktree TEXT
+ );
+ CREATE TABLE session (
+ id TEXT PRIMARY KEY,
+ project_id TEXT,
+ time_created INTEGER
+ );
+ CREATE TABLE message (
+ id TEXT PRIMARY KEY,
+ session_id TEXT
+ );
+ CREATE TABLE part (
+ id TEXT PRIMARY KEY,
+ message_id TEXT,
+ data TEXT,
+ time_created INTEGER
+ );
+ """
+ )
+ conn.execute(
+ "INSERT INTO project (id, name, worktree) VALUES (?, ?, ?)",
+ ("project-1", "Headroom", str(project_path)),
+ )
+ conn.execute(
+ "INSERT INTO session (id, project_id, time_created) VALUES (?, ?, ?)",
+ ("session-1", "project-1", 1_700_000_000_000),
+ )
+ conn.execute(
+ "INSERT INTO message (id, session_id) VALUES (?, ?)",
+ ("message-1", "session-1"),
+ )
+ conn.execute(
+ "INSERT INTO part (id, message_id, data, time_created) VALUES (?, ?, ?, ?)",
+ (
+ "part-1",
+ "message-1",
+ json.dumps(
+ {
+ "type": "tool",
+ "tool": "bash",
+ "callID": "call-1",
+ "state": {
+ "status": "error",
+ "input": {"command": "pytest"},
+ "output": "Error: command failed with exit code 1",
+ },
+ }
+ ),
+ 1_700_000_000_001,
+ ),
+ )
+ conn.commit()
+ finally:
+ conn.close()
+
+
+def test_opencode_plugin_discovers_projects_and_scans_tool_failures(tmp_path: Path) -> None:
+ project_path = tmp_path / "repo"
+ project_path.mkdir()
+ (project_path / "AGENTS.md").write_text("# Existing context\n", encoding="utf-8")
+ db_path = tmp_path / "opencode.db"
+ _create_opencode_db(db_path, project_path)
+
+ plugin = OpenCodePlugin(db_path=db_path)
+
+ projects = plugin.discover_projects()
+ assert len(projects) == 1
+ assert projects[0].name == "Headroom"
+ assert projects[0].project_path == project_path
+ assert projects[0].context_file == project_path / "AGENTS.md"
+
+ sessions = plugin.scan_project(projects[0])
+ assert len(sessions) == 1
+ assert sessions[0].session_id == "session-1"
+ assert sessions[0].timestamp is not None
+
+ tool_call = sessions[0].tool_calls[0]
+ assert tool_call.name == "Bash"
+ assert tool_call.tool_call_id == "call-1"
+ assert tool_call.input_data == {"command": "pytest"}
+ assert tool_call.is_error is True
+ assert tool_call.error_category == ErrorCategory.RUNTIME_ERROR
+
+
+def test_opencode_plugin_uses_agents_writer(tmp_path: Path) -> None:
+ plugin = OpenCodePlugin(db_path=tmp_path / "missing.db")
+
+ assert plugin.detect() is False
+ assert isinstance(plugin.create_writer(), CodexWriter)
+
+
+def test_opencode_plugin_is_discovered_by_registry() -> None:
+ reset_registry()
+ try:
+ assert "opencode" in get_registry()
+ finally:
+ reset_registry()
diff --git a/tests/test_learn/test_registry.py b/tests/test_learn/test_registry.py
index 2e6214c1e..eb98254fa 100644
--- a/tests/test_learn/test_registry.py
+++ b/tests/test_learn/test_registry.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import contextlib
from unittest.mock import MagicMock, patch
import pytest
@@ -73,11 +74,11 @@ class TestAutoDetect:
def test_returns_empty_when_nothing_detected(self):
"""All plugins returning False → empty list."""
- with (
- patch.object(get_registry()["claude"], "detect", return_value=False),
- patch.object(get_registry()["codex"], "detect", return_value=False),
- patch.object(get_registry()["gemini"], "detect", return_value=False),
- ):
+ registry = get_registry()
+ patches = [patch.object(registry[name], "detect", return_value=False) for name in registry]
+ with contextlib.ExitStack() as stack:
+ for p in patches:
+ stack.enter_context(p)
assert auto_detect_plugins() == []