Install CC Safety Net in OpenCode

Run npx -y cc-safety-net@latest install --opencode. It installs the cc-safety-net@latest plugin through OpenCode’s own plugin commands, then checks that OpenCode loaded it. Restart OpenCode afterward. CC Safety Net supports OpenCode 1.18.29+ and 2.0.6+ from the same npm package.

Install CC Safety Net in OpenCode

Check your OpenCode version

Make sure you run OpenCode 1.18.29+ or 2.0.6+. If you run an older release, upgrade OpenCode before you update CC Safety Net.

Run the installer

npx -y cc-safety-net@latest install --opencode

Restart OpenCode

Restart OpenCode. Do the same after every update.

Confirm the plugin is active

npx cc-safety-net doctor

What the OpenCode install changes

On OpenCode 1.x, install clears OpenCode’s cached copy of the package, then runs opencode plugin -g -f cc-safety-net@latest.
On OpenCode 2.x, install runs opencode plugin add cc-safety-net@latest, or opencode plugin update when the plugin is already configured.

Install then checks that OpenCode can load the plugin, and on 2.x that it activated. A plugin that OpenCode never loads protects nothing, so install fails instead of finishing silently. Troubleshoot OpenCode lists the errors.

Where OpenCode keeps its configuration

OpenCode’s config directory is the first of these that applies:

OPENCODE_CONFIG_DIR, when it is set and non-empty.
$XDG_CONFIG_HOME/opencode, when XDG_CONFIG_HOME is set.
~/.config/opencode.

The config file there is opencode.json or opencode.jsonc. When OPENCODE_CONFIG_DIR is set, OpenCode 2.x reads only that directory, while OpenCode 1.x also loads the XDG directory.

What the OpenCode plugin checks

OpenCode loads CC Safety Net in process as a plugin. On OpenCode 1.x it checks the bash tool as a command, and on 2.x the shell tool. Other tools, such as read, edit, write, patch, grep, and glob, go through path and secret protection.

Set the shell dialect on OpenCode 2.x

OpenCode 2.x does not tell the plugin which shell runs a command, so the plugin’s shell option selects the analyzer dialect. It defaults to powershell on Windows and posix everywhere else. Set it in the config entry if you run PowerShell on Unix, or Git Bash on Windows:

{
  "plugins": [
    {
      "package": "cc-safety-net@latest",
      "options": { "shell": "powershell" }
    }
  ]
}

Use "posix" for any shell that runs POSIX sh syntax, such as ash, bash, dash, ksh, sh, or zsh, and "powershell" for powershell or pwsh. The option does not choose OpenCode’s shell. It has to match the one OpenCode uses. Any other value fails the plugin with CC Safety Net: plugin option shell must be posix or powershell. Before OpenCode starts a shell, the plugin checks that the executable matches the option. A shell that does not run POSIX sh syntax, such as fish, nushell, or tcsh, fails the "posix" check. A failed check stops the shell from starting:

CC Safety Net: actual shell "<actual>" does not match plugin option shell "<configured>". Configure the plugin's shell option to match OpenCode; supported dialects are posix and powershell.

This stop is not an ordinary tool denial. It may fail the current operation, and it leaves no audit entry tied to a session.

What happens when the OpenCode check fails

If the CC Safety Net plugin throws, OpenCode blocks the call. OpenCode has no timeout on plugin hooks, so a stalled check keeps the call waiting. If the plugin fails to load, OpenCode starts without it and tools run unchecked. On 2.x, if a reload fails while an earlier working copy is active, that copy keeps checking calls.

OpenCode coverage limits

On Windows, OpenCode 1.x converts a POSIX-rooted workdir such as /tmp with cygpath -w when it runs a POSIX shell. CC Safety Net resolves the same workdir against the current drive, as C:\tmp. CC Safety Net can then check such a call against a different directory than the one it runs in.

Uninstall CC Safety Net from OpenCode

npx -y cc-safety-net@latest uninstall --opencode

Uninstall removes the cc-safety-net entries from opencode.json and opencode.jsonc and keeps their JSONC comments. It also clears the cached package.

Troubleshoot OpenCode

Message	What to do
`OpenCode 1.18.29+ or 2.0.6+ is required; found <version>.`	Upgrade OpenCode, then run the install again
`Change the cc-safety-net package spec in <path> to cc-safety-net@latest, preserving its options, then retry. Adding another spec would create a duplicate plugin ID.`	Edit that entry to `cc-safety-net@latest`, keep its options and comments, and run the install again
OpenCode did not load cc-safety-net from cc-safety-net@latest. Run `opencode plugin list` for details.	Run `opencode plugin list` and check the `cc-safety-net` row
`OpenCode reports cc-safety-net failed: <first line of OpenCode's error>`	Fix the error OpenCode names, then run the install again
OpenCode lists no active cc-safety-net for this directory. Run `opencode api plugin.list` for details.	Run `opencode api plugin.list` in the same directory

On OpenCode 2.x, doctor also asks OpenCode whether the plugin activated in the directory you run doctor in. When it did not, doctor prints Error (OpenCode): OpenCode reports cc-safety-net failed: <the host's first error line>.

Get started

Guides

Configuration

Troubleshooting

CLI commands

Rules and protection

Logs and traces

More reference

Concepts

Project

Install CC Safety Net in OpenCode