Skip to content
Get packs

SSH Doctor

Diagnoses Mac SSH failures: sshd/launchd problems, stale sessions, config and firewall issues.

Source Download skill
Repository
steipete/agent-scripts
Stars
7,433
Licence
MIT
Files
1 file

What it does

SSH Doctor is a troubleshooting playbook for an AI agent working on macOS machines where remote SSH login fails, for example when connections close before authentication. Once installed, the agent follows a fixed sequence: check local loopback first, read sshd config and system logs, look for stuck sshd-session processes, and only then check the firewall. It can also restart the SSH service and, if clearly stranded sessions block new logins, terminate them. It also includes a procedure for copying a 1Password service account token line into a user's ~/.profile on a Mac.

Great for

  • Mac users or sysadmins whose SSH server accepts connections but then drops them
  • Engineers managing several Macs who need a repeatable way to diagnose Remote Login problems
  • Agent users who already run Claude Code or similar tools against their own machines

Skip it if

  • Linux servers or non-macOS systems, since the commands use macOS-specific tools like systemsetup, launchctl and socketfilterfw (the agent would need adapting)
  • Anyone who cannot review shell commands before they run; it uses sudo and can kill processes and edit system files
  • Handling shared or production credentials without an explicit review, since the token-copy section moves a secret between hosts

Try asking

  • “My Mac's SSH connection closes right after connecting. Diagnose why using the SSH Doctor steps.”
  • “Remote Login shows as on but I cannot log in remotely. Check the config and logs.”
  • “Too many sshd-session processes are blocking new SSH logins on this Mac. Find and clear the stale ones safely.”
  • “Check whether the macOS firewall or pf rules are blocking port 22 after loopback SSH works.”
Step-by-step guide: how to use SSH DoctorInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    ssh-doctor.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip ssh-doctor.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip ssh-doctor.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Ask the agent to report config findings and proposed changes before it edits /etc/ssh/sshd_config or kills processes.
  • Keep an active shell open on the target Mac while testing, so a bad sshd change does not lock you out.
  • Review the sudo commands and the token-copy section carefully; only run them on hosts you own and control.

What's inside

  • SKILL.md

Redistributed unmodified from steipete/agent-scripts under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.