PLUGIN brewtools / Skills

ssh — manage servers

opus human-invoked

Connects to Linux servers, discovers what runs there and executes your requests, classifying every command by risk. Setup writes ~/.ssh/config and generates an ssh-admin agent with the server inventory baked in.

Quick reference

FieldValue
Command/brewtools:ssh
Arguments[prompt] [setup|connect|configure|update-agent]
Modelopus
ConfigCLAUDE.local.md (gitignored, never committed)
Agentssh-admin

Modes

ModeDoes
setupAdd a server: key auth, ~/.ssh/config entry, discovery, agent
connectConnect to the configured server, or ask which
configureApply a config change under the same classification
any other textExecute: plan, classify, run after confirmation
update-agentRe-discover up to 3 servers, refresh ssh-admin

Example

/brewtools:ssh check disk space and docker status on vps-main

Read-only checks run without prompts. A restart or removal asks for confirmation first.

How it works

  1. Detect mode

    An explicit token wins; otherwise keywords decide. Empty input means setup with no servers, execute otherwise.

  2. Check environment

    Scans SSH keys, ssh-agent, ~/.ssh/config and the server list in CLAUDE.local.md.

  3. Connect and discover

    Tries keys (ed25519, rsa, ecdsa), reads OS, Docker, disks, ports and services within 30 s.

  4. Persist

    Saves inventory to CLAUDE.local.md, gitignores it, generates .claude/agents/ssh-admin.md.

  5. Classify, confirm, report

    READ and CREATE run freely; MODIFY and SERVICE ask; DELETE and PRIVILEGE warn and always ask.

Good to know

Every destructive command requires explicit confirmation, even when chained with safe ones. Compound requests are split into individually classified steps.

  • sshd, port and firewall changes pass a 5-step lockout gate: allow-new, sshd -t, reload, prove a new session, then deny-old.
  • Claude Code cannot answer password prompts: use ! ssh deploy@your-server.

Technical details

Safety classification and limits

Risk classes (READ, CREATE, MODIFY, SERVICE, DELETE, PRIVILEGE) and their gates: ssh-admin safety classes.

RuleLimit
Connection timeout10 s (ConnectTimeout=10 BatchMode=yes)
Discovery script30 s total
Single SSH command60 s, then killed and reported
Inline SSH commands (Phase 5)5, more are delegated to ssh-admin
SSH calls per invocation15 in total, then stop and report
Key auth attempts3, then ask
AskUserQuestion per phase3 max

Individual commands run through the shared ght 60 ssh ... helper in skills/deploy/scripts/lib/deploy-common.sh, which uses timeout, gtimeout or a Bash watchdog.

Config files and host keys
FilePurpose
CLAUDE.local.mdServer inventory: alias, host, user, key, OS, Docker
~/.ssh/configHost blocks; existing blocks are never overwritten
.claude/agents/ssh-admin.mdGenerated agent; refresh with update-agent

For a new or changed host key, compare the scanned SHA256 fingerprint with an out-of-band record before trusting it. A connection failure alone is not permission to erase known_hosts entries. Environment values are read only when named and needed; env dumps and credential files are never printed. If a helper script fails, the skill retries inline, then reports SCRIPT_ERROR / EXIT_CODE / STDERR / PHASE and stops.

Delegation

A bounded multi-command job on one host goes to ssh-admin (the plugin’s brewtools:ssh-admin when the project has no generated agent), one agent per host, briefed with the six fields in Delegation. Confirmation gates stay in the main conversation; the agent returns exact approval envelopes and runs only the APPROVED ids.

ssh-admin agent

Handles multi-step server operations with inventory context.

Deploy skill

GitHub Actions workflows, releases and GHCR.

GitHub source

Helper scripts and agent template.

Brewtools overview

All brewtools skills.

Update: /brewtools:plugin-update, /reload-plugins, then /brewcode:setup-status upgrade - FAQ