Skip to main content
OpenCode is a first-class Observal harness integration. Observal can install OpenCode agents, configure MCP servers, expose skills, install hook plugins, and collect OpenCode session telemetry.

Overview

OpenCode agent profiles are Markdown files. Project agents live in .opencode/agents/. User agents live in ~/.config/opencode/agents/. OpenCode session telemetry uses an in-process TypeScript plugin. The plugin is installed by observal auth login or observal doctor patch. Agent pulls write agent profiles and update the Observal lockfile, but they do not embed the telemetry plugin in each agent file. The plugin listens to OpenCode session and message events, reads message data through the OpenCode client API, converts new messages into Observal session lines, and sends them to Observal.

Supported capabilities

Setup

1. Install the Observal CLI

2. Authenticate

This writes credentials to ~/.observal/config.json. If OpenCode is detected, login can install the Observal plugin.

3. Pull an agent into OpenCode

OpenCode’s default scope is user scope. By default, the agent is written to ~/.config/opencode/agents/{name}.md. To install into the current project:
Project agents are written to .opencode/agents/{name}.md.

4. Install or refresh the OpenCode plugin

This installs or updates observal-plugin.ts when the plugin is missing, stale, or different from the bundled source.

Config paths

OpenCode MCP configs use the mcp key.

Plugin spec

Observal installs a TypeScript plugin named observal-plugin.ts. The plugin subscribes to OpenCode runtime events: The bundled spec version is checked by doctor patch, along with the plugin content hash, so stale local copies are replaced.

Attribution

OpenCode exposes the active agent name in session events, not an Observal UUID. The Observal lockfile maps that OpenCode agent name back to the registry agent id and installed version.
  1. observal agent pull writes the OpenCode agent profile and records the agent name, id, version, scope, and project directory in ~/.observal/lockfile.json.
  2. The OpenCode plugin receives session.created or agent switch events and reads the active OpenCode agent name.
  3. Built-in OpenCode agents such as build, plan, general, explore, scout, compaction, title, and summary are ignored.
  4. The plugin selects the configured server URL under registries in ~/.observal/lockfile.json, then searches that registry’s opencode harness for an entry whose name or id matches the active agent.
  5. If multiple entries match, a project-scoped entry for the current directory wins, then a user-scoped entry, then the first match.
  6. The session payload is sent with the resolved agent_id and agent_version.
  7. If no lockfile match exists, the plugin skips attribution for that session instead of guessing.

Session push behavior

The OpenCode plugin implements the same acknowledged delivery contract as Python harnesses:
  1. Load ~/.observal/config.json and resolve the active agent through ~/.observal/lockfile.json.
  2. On session.idle, recover missing, stale, or quarantined local state from the server’s contiguous checkpoint.
  3. Retry any durable pending batch before reading new messages.
  4. Fetch messages from client.session.messages and convert each message into one stable JSONL-compatible source record.
  5. Atomically persist the pending indexed batch under ~/.observal/opencode_session_outbox/ before network delivery.
  6. Retry the same batch idempotently until the server returns a contiguous acknowledgement covering it.
  7. Advance the persisted source line only after that acknowledgement; a crash after server commit safely retries the batch.
  8. On finalization, compare a SHA-256 audit manifest and replay from the server-requested repair range when needed.
Acknowledged state is retained for seven days to avoid unnecessary replay. Capacity errors fail closed without discarding pending records. Corrupt state is quarantined and rebuilt from the authenticated server checkpoint plus the OpenCode message source.

Agent profile format

OpenCode agents are Markdown files. Observal writes the agent prompt into the profile selected by scope:

Caveats

The plugin is shared per OpenCode install. It is installed by auth login or doctor patch, not by each agent pull. Attribution depends on the lockfile. If an agent profile is copied by hand without running observal agent pull, the plugin may see the OpenCode agent name but have no Observal id or version to send. Built-in OpenCode agents are ignored. Sessions for built-in agents are not attributed to registry agents. MCP config is OpenCode-specific. OpenCode uses opencode.json and the mcp key, not Kiro or Claude Code MCP paths.