Skip to content

sno-ai/sno-station-skills / skills/M-build-and-rollout/medic/skill

Check that this machine's agent team can work and say what is wrong in plain lines: tools installed, core skills installed, skill commands runnable, hooks configured, Reach seat live, a heartbeat running, both vendors' quota readable, temp space free. Checks only, never repairs. Use on a new machine, when agents stop reaching each other or a long run fails to start, or when the owner asks whether everything is healthy.

FileKindSize
SKILL.mdskill md3.7 KB
scripts/medicexecutablescript9.2 KB
scripts/medic.texecutablescript10.7 KB
scripts/selftest/run-selftest.shexecutablescript1.3 KB

scripts/medic

View on GitHub
#!/usr/bin/env bash
# sno medic — one command that says, in plain lines, whether this machine's agent team can work. It
# only checks; it never repairs, starts, stops or spends anything. One line per check:
#   OK <check>: <what>            WARN|FAIL <check>: <what> -> <fix>
# and a last line `MEDIC ok=N warn=N fail=N`. FAIL means the team cannot work (a required program is
# missing, no agent CLI, Reach broken); WARN means it works worse than it should. Exit 0 when there
# is no FAIL, 1 otherwise, 2 for bad usage. Hooks, Reach and skill-file integrity come from
# `sno doctor --json`; the rest is read directly. Needs bash 4+, GNU coreutils and jq.
set -Eeuo pipefail

usage() {
  local status="${1:-2}"
  cat >&"$((status == 0 ? 1 : 2))" <<'USAGE'
usage: sno medic run [--min-free-mb N]
checks the agent team on this machine and repairs nothing. One line per check:
  OK <check>: <what>   |   WARN|FAIL <check>: <what> -> <fix>
then: MEDIC ok=N warn=N fail=N   (exit 0 without FAIL, 1 with FAIL)
--min-free-mb N   warn when the temp folder has less than N MB free (default 500)
USAGE
  exit "$status"
}

(( $# > 0 )) || usage 0
case "$1" in
  -h|--help) usage 0 ;;
  run) shift ;;
  *) printf 'medic: unknown command %s\n' "$1" >&2; usage ;;
esac
MIN_FREE_MB=500
while (( $# )); do
  case "$1" in
    --min-free-mb) [[ "${2:-}" =~ ^[0-9]+$ ]] || usage; MIN_FREE_MB="$2"; shift 2 ;;
    -h|--help) usage 0 ;;
    *) printf 'medic: unknown option %s\n' "$1" >&2; usage ;;
  esac
done

readonly CORE_SKILLS=(reach heartbeat join-talk handoff deliver charter)
readonly PUBLIC_COMMANDS=(deliver-proof handoff-checkpoint rotate-agent-resume rem-reflect)
readonly REQUIRED_TOOLS=(sno jq tmux git)
readonly REQUIRED_SNO_COMMANDS=(heartbeat subscription-quota-check)

OKS=0 WARNS=0 FAILS=0
ok() { OKS=$((OKS + 1)); printf 'OK %s: %s\n' "$1" "$2"; }
warn() { WARNS=$((WARNS + 1)); printf 'WARN %s: %s -> %s\n' "$1" "$2" "$3"; }
fail() { FAILS=$((FAILS + 1)); printf 'FAIL %s: %s -> %s\n' "$1" "$2" "$3"; }
have() { command -v "$1" >/dev/null 2>&1; }
# runs <name>: `sno <name> --help` answers, so the sno command is runnable.
runs() { timeout 10 sno "$1" --help >/dev/null 2>&1; }
join() { local out="" item; for item; do out+="${out:+, }$item"; done; printf '%s' "$out"; }
# lacking <program>...: the programs among them that are not on PATH, as "a, b"; empty when all are there.
lacking() { local gone=() p; for p; do have "$p" || gone+=("$p"); done; (( ${#gone[@]} == 0 )) || join "${gone[@]}"; }
skip() { warn "$1" "not checked, $2 is missing" "install $2 (see the tools line)"; }

# 1. Programs the team runs on.
missing=()
for tool in "${REQUIRED_TOOLS[@]}"; do have "$tool" || missing+=("$tool"); done
for tool in "${REQUIRED_SNO_COMMANDS[@]}"; do runs "$tool" || missing+=("sno $tool"); done
if (( ${#missing[@]} )); then
  fail tools "not available: $(join "${missing[@]}")" "install them with: sno setup"
else
  ok tools "$(join "${REQUIRED_TOOLS[@]}" "${REQUIRED_SNO_COMMANDS[@]/#/sno }") are installed"
fi

# 2. At least one agent CLI.
vendors=()
for v in claude codex; do have "$v" && vendors+=("$v"); done
if (( ${#vendors[@]} )); then
  ok agent-cli "found $(join "${vendors[@]}")"
else
  fail agent-cli "neither claude nor codex is on PATH" "install the Claude Code or Codex command line"
fi

# 3. The core skills, where each vendor reads them.
problems=()
for v in ${vendors[@]+"${vendors[@]}"}; do
  case "$v" in claude) dir="$HOME/.claude/skills" ;; codex) dir="$HOME/.agents/skills" ;; esac
  lost=()
  for s in "${CORE_SKILLS[@]}"; do [[ -f "$dir/$s/SKILL.md" ]] || lost+=("$s"); done
  (( ${#lost[@]} == 0 )) || problems+=("$v is missing $(join "${lost[@]}")")
done
if (( ${#problems[@]} )); then
  warn skills "$(join "${problems[@]}")" "run: sno setup"
elif (( ${#vendors[@]} )); then
  ok skills "all ${#CORE_SKILLS[@]} core skills are installed for $(join "${vendors[@]}")"
else
  warn skills "not checked, no agent CLI is installed" "install claude or codex first"
fi

# 4. The commands the skills ship.
broken=()
for c in "${PUBLIC_COMMANDS[@]}"; do runs "$c" || broken+=("$c"); done
if (( ${#broken[@]} )); then
  warn commands "does not run: $(join "${broken[@]}")" "run: sno setup"
else
  ok commands "${#PUBLIC_COMMANDS[@]} skill commands run"
fi

# 5. Hooks, Reach and skill files, as `sno doctor` sees them.
doctor="" lack="$(lacking sno jq)"
if [[ -z "$lack" ]]; then
  doctor="$(timeout 90 sno doctor --json 2>/dev/null || true)"
  jq -e 'type == "object" and (.hooks | type == "array") and (.reach | type == "array") and (.skills | type == "array")' >/dev/null 2>&1 <<<"$doctor" || doctor=""
fi
if [[ -n "$lack" ]]; then
  for c in hooks reach skill-files; do skip "$c" "$lack"; done
elif [[ -z "$doctor" ]]; then
  for c in hooks reach skill-files; do warn "$c" "sno doctor gave no usable answer" "run sno doctor by hand and read its message"; done
else
  bad=()
  for v in ${vendors[@]+"${vendors[@]}"}; do
    r="$(jq -r --arg t "$v configured" '[.hooks[]? | select(.target == $t) | .result][0] // "not reported"' <<<"$doctor")"
    [[ "$r" == ok ]] || bad+=("$v hooks are $r")
  done
  while IFS= read -r line; do [[ -z "$line" ]] || bad+=("$line"); done < <(
    jq -r --argjson vs "$(printf '%s\n' ${vendors[@]+"${vendors[@]}"} | jq -R . | jq -sc .)" \
      '.hooks[]? | select(.target | test("^(claude|codex) trust$")) | select(.target[:-6] as $v | $vs | index($v)) | select(.result != "ok") | "\(.target) is \(.result)"' <<<"$doctor")
  if (( ${#vendors[@]} == 0 )); then warn hooks "not checked, no agent CLI is installed" "install claude or codex first"
  elif (( ${#bad[@]} )); then warn hooks "$(join "${bad[@]}")" "run: sno setup"
  else ok hooks "hooks are configured for $(join "${vendors[@]}")"; fi

  reach_bad="$(jq -r '.reach[]? | select(.result != "ok") | "\(.result)\t\(.detail)"' <<<"$doctor")"
  if [[ -n "$reach_bad" ]]; then
    while IFS=$'\t' read -r result detail; do
      fail reach "sno doctor reports Reach as $result" "${detail:-run sno doctor and read its message}"
    done <<<"$reach_bad"
  else
    ok reach "sno doctor reports Reach as ok"
  fi

  files_bad="$(jq -r '.skills[]? | select(.result != "ok") | .target' <<<"$doctor")"
  if [[ -n "$files_bad" ]]; then
    n="$(grep -c . <<<"$files_bad")"
    first="$(head -n3 <<<"$files_bad" | paste -sd, - | sed 's/,/, /g')"
    warn skill-files "$n skill file(s) fail sno doctor, first: $first" "run: sno update"
  else
    ok skill-files "every installed skill file passes sno doctor"
  fi
fi

# 6. This agent's Reach seat, or at least one live seat.
lack="$(lacking sno jq)"
if [[ -z "$lack" ]]; then
  seats="$(timeout 20 sno reach seats --json 2>/dev/null || true)"
  addr="${SNO_REACH_ADDR:-}"
  if [[ -n "$addr" ]]; then
    state="$(jq -rs --arg a "$addr" '[.[] | select(.address == $a) | .state][0] // "absent"' <<<"$seats" 2>/dev/null || printf unknown)"
    if [[ "$state" == live ]]; then ok seat "your seat $addr is live"
    else warn seat "your seat $addr is $state" "run join-talk in this agent window"; fi
  else
    live="$(jq -s '[.[] | select(.state == "live")] | length' <<<"$seats" 2>/dev/null || printf 0)"
    if [[ "$live" =~ ^[1-9] ]]; then ok seat "$live live seat(s)"
    else warn seat "no live seat, so nobody can be reached" "run join-talk in an agent window"; fi
  fi
else
  skip seat "$lack"
fi

# 7. A heartbeat is running somewhere on this machine.
if have sno; then
  running="$(timeout 10 sno heartbeat --list 2>/dev/null | grep -Ev '^(WHO|\()' | grep -c . || true)"
  if (( running > 0 )); then ok heartbeat "$running heartbeat(s) running"
  else warn heartbeat "no heartbeat is running, so long work has no watcher" "when a long job starts, run: sno heartbeat --label <name> --interval 10 -- <command>"; fi
else
  skip heartbeat sno
fi

# 8. Each vendor's subscription quota can be read and allows new work.
lack="$(lacking sno jq)"
if [[ -z "$lack" ]]; then
  (( ${#vendors[@]} )) || warn quota "not checked, no agent CLI is installed" "install claude or codex first"
  for v in ${vendors[@]+"${vendors[@]}"}; do
    # The reader exits non-zero when a vendor is blocked or unreadable but still prints its verdict.
    reading="$(timeout 60 sno subscription-quota-check --vendor "$v" --json --quiet 2>/dev/null || true)"
    verdict="$(jq -r '.vendors[0].verdict // "unknown"' <<<"$reading" 2>/dev/null || true)"
    verdict="${verdict:-unknown}"
    case "$verdict" in
      go|short_only) ok quota "$v quota reads $verdict" ;;
      wait) warn quota "$v quota reads wait, so it will refuse new work now" "wait for the reset shown by: sno subscription-quota-check --vendor $v --human" ;;
      *) warn quota "$v quota could not be read" "log in to $v on this machine, then run: sno subscription-quota-check --vendor $v --human" ;;
    esac
  done
else
  skip quota "$lack"
fi

# 9. Free space where agents and tests write.
tmpdir="${TMPDIR:-/tmp}"
free_mb="$(df -Pk -- "$tmpdir" 2>/dev/null | awk 'NR == 2 { printf "%d", $4 / 1024 }' || true)"
if [[ ! "$free_mb" =~ ^[0-9]+$ ]]; then
  warn temp-space "could not read free space of $tmpdir" "check the folder exists: $tmpdir"
elif (( free_mb < MIN_FREE_MB )); then
  warn temp-space "only $free_mb MB free in $tmpdir (want $MIN_FREE_MB)" "free space there, or point TMPDIR at a bigger disk"
else
  ok temp-space "$free_mb MB free in $tmpdir"
fi

printf 'MEDIC ok=%s warn=%s fail=%s\n' "$OKS" "$WARNS" "$FAILS"
(( FAILS == 0 ))
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall