Agentic Plugins

OpenCode plugin focused on one workflow: check backup logs over SSH and decide if an alert is a false positive.

Quick Start

1. Install dependencies

yarn install

2. Build and link globally

yarn symlink

yarn symlink does all of this:

• rebuilds plugin (dist/index.js)
• links src/agents/*.md -> ~/.config/opencode/agents/
• links src/skills/*/ -> ~/.config/opencode/skills/
• links src/commands/*.md -> ~/.config/opencode/commands/
• copies project opencode.json to ~/.config/opencode/opencode.json
• rewrites global plugin path to this repo build (file:///.../dist/index.js)

3. Verify global config points to this plugin

python3 -c "import json, pathlib; p=pathlib.Path.home()/'.config/opencode/opencode.json'; print('config:', p); print('plugin:', json.loads(p.read_text()).get('plugin'))"

Expected: plugin path includes this repo and ends with /dist/index.js.

4. Configure SSH aliases (required)

Define SSH aliases in ~/.ssh/config. Keep jump-chain logic in SSH config, not in prompts.

Example:

Host first-jump
  HostName first.jump.company
  User your-user

Host second-jump
  HostName 20.76.46.5
  User your-user
  ProxyJump first-jump

Host db-prod-1
  HostName 10.10.10.21
  User your-user
  ProxyJump second-jump

5. Verify SSH path before OpenCode

ssh db-prod-1 'echo ok'

Expected: command succeeds and prints ok.

6. Run OpenCode with target allowlist env var

Recommended launch command (ensures env var is present for that OpenCode process):

OPS_SSH_ALLOWED_TARGETS="db-prod-1,db-prod-2" opencode

If you prefer a permanent shell variable instead:

echo 'export OPS_SSH_ALLOWED_TARGETS="db-prod-1,db-prod-2"' >> ~/.zshrc
source ~/.zshrc
opencode

7. Use the tool

Tool name:

• ops_check_backup_log

Example instruction:

• "Run ops_check_backup_log with sshTarget=db-prod-1 and logFilePath=/path/to/backup.log"

Arguments:

• sshTarget (required): SSH alias from ~/.ssh/config
• logFilePath (required): absolute remote path
• okPattern (optional): text meaning false alert (default: ok)
• timeoutMs (optional): SSH timeout in ms (default: 15000)
• maxBytes (optional): max bytes read from log file (default: 32768)

Decision Output

The tool returns one of:

• false alert -> safe to close
• log is empty -> continue incident process
• pattern not found -> needs manual review

It also returns a small log preview and SSH stderr (if available).

Authentication and Security

• No passwords or tokens are stored by this plugin.
• Authentication is delegated to your existing VPN + SSH setup.
• Access is restricted by OPS_SSH_ALLOWED_TARGETS allowlist.
• If allowlist is missing or target is not listed, the tool fails closed.

Troubleshooting

• Target "..." is not allowed -> update OPS_SSH_ALLOWED_TARGETS
• Failed to check backup log + SSH error -> verify VPN, jump hosts, and SSH alias
• Tool missing in OpenCode -> run yarn symlink again, then repeat step 3

Legal Note

Follow your company and customer security rules before automating operations.