Nano Doctor

/nano-doctor — Install Health Check

You diagnose the local nanostack install. Ten checks across dependencies, install integrity, the user-scoped home directory, telemetry config, the pre-V5 detection path, and Worker reachability. Output names the category, the check, and a one-line detail. No decorative prose.

This is a diagnostic skill, not a fix-everything skill. Mechanical issues (file permissions, missing chmod +x) repair with --fix. Anything that needs human judgment stays as a warning or failure.

Telemetry preamble

Defensive telemetry init. No-op if telemetry is disabled via NANOSTACK_NO_TELEMETRY=1, ~/.nanostack/.telemetry-disabled, or if the helpers are removed.

_P="$HOME/.claude/skills/nanostack/bin/lib/skill-preamble.sh"
[ -f "$_P" ] && . "$_P" nano-doctor
unset _P

Process

Run the health check script, then summarize what the user actually needs to do:

~/.claude/skills/nanostack/bin/nano-doctor.sh

Optional flags:

• --json — machine-readable output. Use when invoked by another tool or when piping to jq. The envelope includes fix_available (boolean), fix_command (the suggested command or null), and session_profile ("guided", "professional", or null when no session exists in the current project). These three fields let calling skills decide whether to surface a one-line repair prompt or a full warning report.
• --offline — skip Worker reachability. Use in air-gapped environments or during CI.
• --fix — repair mechanical issues. Currently covers: chmod 700 on ~/.nanostack/, chmod +x on the sender, and adding the missing PreToolUse hooks for Bash and Write/Edit/MultiEdit to the local .claude/settings.json. Always backs up the file first as .claude/settings.json.YYYYMMDD-HHMMSS.bak. Never touches your existing permission entries; only adds hooks alongside them.

Interpreting the output

The script prints one line per check, grouped by category. Status values:

• ok — passed, nothing to do.
• warn — minor issue. Telemetry may report unknown, permissions may be too open, Worker may be unreachable. None of these block /think, /nano, etc.
• FAIL — critical issue. A missing dependency or missing skill file. Usage is impaired.

The host category reports the protection level for every detected agent CLI (Claude Code, Cursor, Codex, OpenCode, Gemini). Each row reads a host's declared capability from adapters/<host>.json and cross-checks against this install. When the declaration says enforced but the local hook is missing, the row warns about the drift and points at /nano-doctor --fix. When a host's adapter declares instructions_only, the row passes with a note that the workflow is guided rather than enforced on that host. See reference/host-adapter-schema.md for the full vocabulary.

Exit codes:

When to recommend --fix

If the report shows warnings for home permissions, sender_executable, bash_guard, or write_guard, re-run with --fix. The --fix mode handles those four mechanically and leaves a backup. For any other warning or failure (missing VERSION, broad Bash(rm:*), broken telemetry tier), surface the detail to the user and let them decide. Do NOT try to fix missing dependencies or rewrite permission lists automatically.