mdoctor Agent

Run reliable mdoctor setup + usage workflows, with dependency handling built in.

Quick start

From the mdoctor repo root, run:

bash skills/mdoctor-agent/scripts/install_mdoctor_with_deps.sh

Useful modes:

# Preview only
bash skills/mdoctor-agent/scripts/install_mdoctor_with_deps.sh --dry-run

# Dev mode: link current checkout (best for branch testing)
bash skills/mdoctor-agent/scripts/install_mdoctor_with_deps.sh --method dev --user-bin

# Force local installer behavior (~/.mdoctor clone/update)
bash skills/mdoctor-agent/scripts/install_mdoctor_with_deps.sh --method local

Workflow

1) Preflight

• Detect OS (Darwin or Debian/Arch-family Linux only).
• Validate method (auto|dev|local|remote).
• Check required dependencies:
  • git for local/remote methods
  • curl for remote method
• If dependencies are missing:
  • Debian-family Linux: install via sudo apt update && sudo apt install -y ...
  • Arch-family Linux (incl. Omarchy): install via sudo pacman -S --needed ...
  • macOS: instruct user to run xcode-select --install (or Homebrew install)

2) Install mdoctor

Choose method by intent:

• dev: symlink current repo ./mdoctor into bin dir (branch-accurate testing)
• local: run local install.sh (installs under ~/.mdoctor)
• remote: one-line installer from GitHub
• auto (default): prefer dev when current repo is available, fallback to local, then remote

Optional flags:

• --user-bin: use ~/.local/bin (avoids sudo in most cases)
• --repo-root <path>: override repository root for dev/local modes

3) Verify installation

Run smoke checks:

mdoctor version
mdoctor help
mdoctor info
mdoctor check -m system

The installer script forces a safe TERM fallback for non-interactive sessions to reduce tput noise during checks.

4) First safe usage

Prefer non-destructive commands first:

mdoctor check
mdoctor clean
mdoctor list

Only run destructive cleanup with explicit intent:

mdoctor clean --force

5) Troubleshooting

• If mdoctor is not found: verify symlink target and PATH.
• If /usr/local/bin is not writable: rerun with --user-bin.
• If Linux distro unsupported: stop and explain the Debian/Arch-family limitation.
• If sudo is unavailable in remote sessions: provide exact commands for user to run locally (apt on Debian-family, pacman -S on Arch-family).

Command reference

Common operations:

mdoctor check
mdoctor check --json
mdoctor check -m security
mdoctor clean
mdoctor clean --interactive
mdoctor fix dns
mdoctor fix disk
mdoctor update --check
mdoctor update

Guardrails

• Ask before state-changing operations (clean --force, fix *, package installs).
• Prefer read-only diagnosis first, then targeted fixes.
• Do not claim support for Linux outside Debian/Arch families.