opencode-command-hooks plugin
An OpenCode plugin where hooks on tool and subagent calls are declared in config and command output flows into context.
- 64 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The plugin executes arbitrary shell commands from configuration, including project files.
- Command output enters the agent's context, so secrets in it become visible to the model.
Install
- Works in
Manual install
Add `"plugin": ["opencode-command-hooks"]` to `opencode.json`. Create `.opencode/command-hooks.jsonc` with an `after` hook for `task` and your check commands, then restart OpenCode and confirm the output reaches the session.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The plugin executes arbitrary shell commands from configuration, including project files.
- Command output enters the agent's context, so secrets in it become visible to the model.
This is third-party code. Review the repository files before installing.
What it does
opencode-command-hooks runs shell commands on OpenCode events: before and after a tool call, at session start and when it idles. Hooks are declared in a `command-hooks.jsonc` file or right in the frontmatter of a subagent's markdown file, next to its instructions. The `inject` field sends command output into the session so the agent reads the linter or test result and fixes errors. The `toast` field shows a notification in the interface. The `when.toolArgs` filter fires only for matching arguments, for example a write to `.ts` files. Commands run in order, and a hook failure does not stop the tool.
Who it is for. OpenCode users with several subagents who want automatic code checks after each step without extra trips through the orchestrator.
Good fit when
- After each `engineer` subagent run you need the linter, type check and tests.
- The `npm test` result should enter the context on its own, without asking the agent to call bash.
- A write to `.ts` or `.js` files should trigger a formatter.
- You prefer keeping agent configuration in one markdown file together with its hooks.
- A local notification should go out when a session idles.
Not a fit when
- Work happens in Claude Code or Codex: the plugin only plugs into OpenCode.
- A hook must block a tool call on failure: here commands only report the result.
- You need toast notifications on OpenCode 2: they are not available there yet.
Example request
Add a hook that runs lint, typecheck and tests after every engineer subagent call and injects the output into the session.Limitations
The plugin was not built by the OpenCode team and is not affiliated with them. Hooks wait for commands to finish, so a long check delays the next step. Output is truncated at 30,000 characters by default, and `truncationLimit` sets the cap. With an array of commands `inject` and `toast` use the last command's output. On OpenCode 2 toasts are not shown yet, everything else works. `{args.key}` placeholders work in `inject` and `toast`, while commands read arguments from a file whose path sits in `OPENCODE_HOOK_ARGS_FILE`.
How to disable. Remove `opencode-command-hooks` from the `plugin` array in `opencode.json`. Delete `command-hooks.jsonc` files and `hooks` blocks in frontmatter by hand.
FAQ
How do I connect the plugin to OpenCode?
Add `"plugin": ["opencode-command-hooks"]` to `opencode.json`. The configuration works unchanged on OpenCode 1.x and on OpenCode 2, which also accepts a `plugins` key.
Where are hooks stored?
Global ones live in `~/.config/opencode/command-hooks.jsonc`, project ones in `.opencode/command-hooks.jsonc`. They merge by default, and `overrideGlobal: true` disables global hooks for the same event.
How do I send test results to the agent?
Set `run: "npm test"` and `inject` with `{stdout}`, `{stderr}` and `{exitCode}` placeholders. The output lands in the session after the event and the agent reads it on its own.
Does a hook block a tool call on error?
No. Hooks wait for commands, but a failure does not stop the tool. Commands run in order even if a previous one failed.
How do I limit a hook to certain arguments?
Use `when.toolArgs` with an exact value, a `glob` pattern or a `regex`. The hook fires when all listed arguments match, and the values are available in templates as `{args.filePath}`.
Discussion
No questions or reviews yet.
Related
PluginsA Windows plugin for OpenCode Desktop that sets edit boundaries, screens commands and ties test results to the current code.
OpenCode plugin that turns a session into a team of agents led by an architect and runs the work through plan phases
A Telegram bot for OpenCode: send coding tasks, watch progress and switch models from your phone while OpenCode keeps running on your own computer
A Claude Code hooks set with voice cues: a sound on session start, tool use, agent reply and other lifecycle events.
An OpenCode plugin that uses the Morph cloud service to merge partial edits into a file with no exact string search.
An OpenCode plugin that searches conversation history across all projects by keyword, regex, with typos, and by touched files.
README in short
The author explains that automatic validation of codebase state helps when a fleet of subagents works, while asking an orchestrator to call bash is nondeterministic and costly. The plugin wraps hooks that OpenCode already exposes.