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.
What gets installed
Section titled “What gets installed”There is no download: omnodex install opencode writes the plugin file itself.
| Part | What it does | How to get it |
|---|---|---|
| Plugin file | Records sessions, prompts, tool calls before and after they run, failed calls, subagents and the model in use. In guardrails mode it can stop a call | omnodex 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 size | Add --mcp |
Install
Section titled “Install”-
Install Omnodex on the host where you run OpenCode.
-
Set up OpenCode:
Terminal window cd /path/to/your/projectomnodex install opencodeThe command asks whether to record every project you open (recommended) or only this one, and writes one file,
omnodex.js:Records Plugin is written to Every project ~/.config/opencode/plugins/omnodex.js(or$XDG_CONFIG_HOME/opencode/plugins/)This project .opencode/plugins/omnodex.jsin the projectIf 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.
-
Verify:
Terminal window omnodex status -
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 openomnodex dashboard.
Route MCP servers through the proxy
Section titled “Route MCP servers through the proxy”omnodex mcp-proxy install # creates omnodex-proxy.json if it is missingomnodex 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.
What gets traced
Section titled “What gets traced”| Event type | When it is written |
|---|---|
session.started | An OpenCode session starts |
session.ended | The session is deleted |
session.model_changed | The session’s model is first seen, or changes. OpenCode names the model with each prompt |
prompt.submitted | You submit a prompt. Includes the full prompt text |
tool.invoked | The agent is about to run a tool. Includes the tool name and parameters |
tool.completed | The tool call finishes, with success or error and how long it took |
file.read, file.written | The agent reads or writes files with its file tools |
subagent.started, subagent.stopped | The agent starts a subagent, or the subagent goes idle |
Events carry interceptor: "opencode-plugin" and platform: "opencode". Tool output is measured, not stored.
Guardrails
Section titled “Guardrails”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.
Limits
Section titled “Limits”- 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.
Uninstall
Section titled “Uninstall”| To remove | Run |
|---|---|
| Omnodex from this project (or leave it out, when recording every project) | omnodex uninstall opencode |
| Every-project recording | omnodex uninstall opencode --everywhere |
| The MCP proxy entry | omnodex 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.
Troubleshooting
Section titled “Troubleshooting”No events after installing:
- Restart OpenCode. It loads plugins only at startup.
- Run
omnodex statusin the project to confirm the plugin is installed. - Check
launcher.login your Omnodex home.Could not locate opencode hook shimmeans the launcher could not find Omnodex: for a source install,omnodex-config.jsonis missing anopencodeentry undershim_paths; for an npm install,omnodexis not on thePATHOpenCode starts with.
Next steps
Section titled “Next steps”- Shadow Mode and Guardrails - Stop or hold risky calls
- MCP Proxy for Any Client - How the proxy works
- Running Detection - Risk detection works the same across all agents