@common-creation/opencode-plugin-automode

An OpenCode plugin that acts as a safety classifier for the bash tool: every bash command is judged by an LLM before it runs — safe commands are allowed, dangerous ones are rejected.

日本語版はこちら: README.ja.md

How it works

1. The plugin hooks tool.execute.before and intercepts every bash call.
2. The command is sent to an LLM (via the @opencode-ai/sdk client) with a system prompt describing what counts as safe vs. dangerous.
3. The LLM replies with a JSON verdict: {"allowed": true|false, "reason": "..."}.
4. allowed: true → the command runs as usual.
5. allowed: false → the tool call is rejected with an error the agent can react to (no user prompt needed).

Classification runs in a dedicated throwaway session that is deleted after each call. The classifier session cannot invoke bash, edit, write, create, delete, webfetch, or task.

Installation

As an npm plugin:

{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@common-creation/opencode-plugin-automode"]
}

Or load it directly from a local build (e.g. dist/index.js) via a path spec in your opencode.json.

Configuration

Env var	Default	Description
OPENCODE_AUTOMODE_ENABLED	true	Set to false to disable the plugin entirely.
OPENCODE_AUTOMODE_MODEL	(auto)	Classifier model in provider/model format (e.g. opencode-go/deepseek-v4-flash). Defaults to the model of the calling session, then to the configured default model.
OPENCODE_AUTOMODE_FAIL_MODE	closed	closed = block when the classifier fails or times out (fail-closed). open = allow in that case (fail-open).
OPENCODE_AUTOMODE_TIMEOUT_MS	30000	Timeout for a single classification call.
OPENCODE_AUTOMODE_MAX_RETRIES	2	Extra attempts when the classifier response is not valid JSON.
OPENCODE_AUTOMODE_LOG_PATH	(empty)	File to write plugin logs to (one JSON object per line). Empty disables file logging.

Security notes

• This is a guardrail, not a sandbox. A malicious agent or prompt-injected content is not stopped by this plugin.
• The classifier only sees the bare command (no assistant prose or tool outputs), which reduces rationalization and prompt-injection attacks on the classifier itself.
• Commands touching paths outside the project are still subject to OpenCode's own permission system (e.g. external_directory prompts).
• In-project destructive operations (e.g. rm -rf of a project subdirectory) may be classified as safe, as they are routine development cleanup. Tune expectations per your threat model.

Development

bun install
npm run typecheck # tsc --noEmit
npm run build # tsc -> dist/
bun test# unit tests for the JSON parser
bun run scripts/manual-test.ts # boots a server and classifies a battery of safe/dangerous commands

The manual test exits non-zero if any command is misclassified. It needs a working OpenCode install with authentication; set AUTOMODE_MODEL to choose the classifier model (defaults to opencode-go/deepseek-v4-flash).

License

MIT