Event Shell Exec

OpenCode plugin that executes shell commands when configured events are triggered.

Installation

Add the plugin to your opencode.json:

{
  "plugin": ["@dragonwize/opencode-event-shell-exec"]
}

Configuration

Create an opencode-event-shell-exec.json file in either (or both) of these locations:

Location	Path	Scope
Global	~/.config/opencode/opencode-event-shell-exec.json	All projects
Project	<project-root>/opencode-event-shell-exec.json	Single project

Both files are optional. When both exist, command arrays for the same event pattern are concatenated (global first, project second).

Config format

The config file is a JSON object mapping event patterns to arrays of commands:

{
  "session.idle": [
    "notify-send 'OpenCode session completed!'"
  ],
  "session.*": [
    "echo '[{event.type}] at $(date)' >> /tmp/opencode-sessions.log"
  ],
  "*": [
    "echo '{event.type}' >> /tmp/opencode-all-events.log"
  ]
}

Event patterns

Pattern	Matches
session.idle	Only the session.idle event
session.*	Any event starting with session. (session.idle, session.created, etc.)
*	Every event

When multiple patterns match an event, all matching groups run in parallel. Commands within each group run sequentially.

Available events

• command.executed
• file.edited, file.watcher.updated
• installation.updated
• lsp.client.diagnostics, lsp.updated
• message.created, message.updated, message.part.updated
• permission.requested, permission.replied
• server.session.updated
• session.created, session.idle, session.compacted, session.deleted, session.error, session.updated
• todo.updated
• tool.execute.before, tool.execute.after
• tui.file.open

Command entries

Each command in the array can be either a string or an object:

String (simple):

"echo 'hello world'"

Object (advanced):

{
  "command": "echo 'hello world'",
  "cwd": "/tmp",
  "env": { "LOG_LEVEL": "debug" },
  "timeout": 5000
}

Field	Type	Required	Description
command	string	Yes	The shell command to execute
cwd	string	No	Working directory for the command
env	object	No	Extra environment variables (merged with process.env)
timeout	number	No	Timeout in milliseconds; command is killed if exceeded

Interpolation

Environment variables are substituted at config-load time:

{
  "session.idle": ["{env:NOTIFY_COMMAND} 'Session done!'"]
}

Event data is substituted at execution time:

{
  "*": ["echo 'Event: {event.type}' >> /tmp/events.log"]
}

Token	Replaced with
{env:VAR_NAME}	Value of environment variable (empty string if unset)
{event.type}	The event type string (e.g. session.idle)
{event.properties.xxx}	Dot-path into the event object
{event}	JSON-stringified entire event object

Execution

Commands run via Bun's shell API, which is cross-platform and prevents shell injection by default. Commands are run with .nothrow().quiet() so failures are logged (via client.app.log) rather than thrown.

Example config

See opencode-event-shell-exec.example.json for a full example.

Development

bun install
bun test
bun run typecheck

License

MIT