Skip to content

OpenCode Setup

Omnodex traces OpenCode, in the terminal app and in opencode run. Requires omnodex 0.15.0 or later.

OpenCode has no command hooks. It loads JavaScript plugins instead, so Omnodex installs a small plugin file that hands each event to Omnodex and does no work of its own.

There is no download: omnodex install opencode writes the plugin file itself.

PartWhat it doesHow to get it
Plugin fileRecords sessions, prompts, tool calls before and after they run, failed calls, subagents and the model in use. In guardrails mode it can stop a callomnodex install opencode
MCP proxy entry (optional)Routes the MCP servers you choose through the Omnodex proxy, which records each call with its timing and response sizeAdd --mcp
  1. Install Omnodex on the host where you run OpenCode.

  2. Set up OpenCode:

    Terminal window
    cd /path/to/your/project
    omnodex install opencode

    The command asks whether to record every project you open (recommended) or only this one, and writes one file, omnodex.js:

    RecordsPlugin is written to
    Every project~/.config/opencode/plugins/omnodex.js (or $XDG_CONFIG_HOME/opencode/plugins/)
    This project.opencode/plugins/omnodex.js in the project

    If a file of that name already exists and Omnodex did not write it, the install stops and changes nothing; move that file aside first.

    When it finishes, the command offers to connect to the hosted dashboard. Press Ctrl+C to skip.

  3. Verify:

    Terminal window
    omnodex status
  4. Restart OpenCode. It loads plugins when it starts. Then have the agent run a command, and look for a new session file under event-log/sessions/ in your Omnodex home, or open omnodex dashboard.

Terminal window
omnodex mcp-proxy install # creates omnodex-proxy.json if it is missing
omnodex install opencode --mcp

--mcp adds an omnodex server under mcp in ~/.config/opencode/opencode.json and keeps everything else in the file. Then move the servers you want recorded from that file into upstream_servers in omnodex-proxy.json; see MCP Proxy for Any Client. If your configuration is an opencode.jsonc file, Omnodex does not rewrite it, since that would drop your comments: the command says so, and you add the entry by hand.

Event typeWhen it is written
session.startedAn OpenCode session starts
session.endedThe session is deleted
session.model_changedThe session’s model is first seen, or changes. OpenCode names the model with each prompt
prompt.submittedYou submit a prompt. Includes the full prompt text
tool.invokedThe agent is about to run a tool. Includes the tool name and parameters
tool.completedThe tool call finishes, with success or error and how long it took
file.read, file.writtenThe agent reads or writes files with its file tools
subagent.started, subagent.stoppedThe agent starts a subagent, or the subagent goes idle

Events carry interceptor: "opencode-plugin" and platform: "opencode". Tool output is measured, not stored.

In guardrails mode, the plugin waits for Omnodex’s answer before each tool call runs:

  • Stop: the plugin refuses the call, and the agent sees Omnodex’s reason.
  • Hold for confirmation: OpenCode’s plugin hooks cannot prompt you, so the call is stopped too, and the reason tells the agent to ask you before trying again.

Nothing changes in the plugin when you switch modes. Because a plugin that fails would block your tool call, the Omnodex plugin treats every problem on its side, such as a missing install, a crash or a slow answer, as “no decision”, and the call runs.

  • No prompt for held calls. OpenCode’s plugin hooks can only let a call run or stop it, so a held call is stopped rather than confirmed in place.
  • Session ends. OpenCode reports the end of a session only when it is deleted. A session you close and might resume later has no end event.
To removeRun
Omnodex from this project (or leave it out, when recording every project)omnodex uninstall opencode
Every-project recordingomnodex uninstall opencode --everywhere
The MCP proxy entryomnodex uninstall opencode --mcp (0.15.1 or later)

Each command shows what it will change and asks first. Omnodex removes a plugin file only when Omnodex wrote it, and your event data stays. Restart OpenCode afterwards. See Uninstalling.

No events after installing:

  • Restart OpenCode. It loads plugins only at startup.
  • Run omnodex status in the project to confirm the plugin is installed.
  • Check launcher.log in your Omnodex home. Could not locate opencode hook shim means the launcher could not find Omnodex: for a source install, omnodex-config.json is missing an opencode entry under shim_paths; for an npm install, omnodex is not on the PATH OpenCode starts with.