Setup Doctor

setup-doctor

Audits how AI coding agents are configured in your project and at the user level, scores the result from 0 to 100, and tells you exactly what to fix. It also summarizes your local usage into a shareable card.

The badge above is this repository's own score, produced by running setup-doctor against itself.

Features

• Doctor audits instruction files, skills, subagents, MCP servers, plugins, settings and hooks. It runs 30 rules across 6 categories and reports a score, a band (Excellent, Good, Needs work, or Poor), and a specific fix for every finding.
• Wrapped summarizes your local session logs (sessions, active days, tokens, an estimated cost, streaks, and a persona label) and writes a shareable card as SVG, with optional PNG.
• Badge writes a static or live score badge for your README.
• HTML report produces a single self-contained file with no network requests.
• MCP server exposes Doctor and Wrapped as read-only tools for any MCP client.

Quick start

No install is needed. Run it from the root of a project:

npx setup-doctor

The default command audits the project and prints a report:

Setup Doctor  score 85/100  (Good)   rules v1.2.0

Instruction files 29/30 Skills n/a MCP n/a Plugins n/a Settings 5/10 Freshness n/a

Always-loaded context: about 0 tokens

HIGH SET-02 Hook PreToolUse in .claude/settings.json points to scripts/missing.sh which is missing or not executable Fix: Correct the path, make the script executable, or remove the hook. LOW INS-01 No instruction file found for claude Fix: Create CLAUDE.md (or the agent's equivalent) with build and test commands, code style rules and a short project layout.

2 findings

Absolute paths in the finding messages are shortened here for readability.

Read the getting started guide for how to interpret the score and each finding.

Commands

Run setup-doctor --help for every flag, or see the command reference.

Supported agents

Categories that do not apply to an agent (for example, plugins for Codex) are excluded from its score rather than counted as failures. Details are in agents.

Installation

Common options

Full flag reference: doctor, wrapped.

Badge

Add your score to the README:

npx setup-doctor badge

This writes setup-doctor-badge.svg and prints a Markdown snippet with your current score. To keep the badge current automatically, publish a shields.io endpoint file from CI. See CI integration.

Privacy and safety

• No network access at runtime. There is no telemetry and no update check. An automated check in CI enforces this (scripts/check-no-network.mjs).
• Audits never change your agent configuration. Only doctor --fix edits configuration files, and it shows a diff, requires confirmation, and writes a backup first. badge, wrapped and --out write new output files only.
• Secrets are never printed. Findings report the rule and location. Values appear as [REDACTED].
• Shareable outputs contain aggregate numbers only. The Wrapped card and the badge never include prompts, file paths, usernames or repository names. Local reports (HTML and JSON) can contain file paths, so review them before sharing.
• Session logs are read for metadata only. Timestamps, model names, token counts and tool names are read. Message text is discarded line by line.
• No account, API key or login is required.

Documentation

• Getting started: your first run and how to read the output
• Doctor: every audit option, output formats, exit codes
• Wrapped: periods, privacy controls, the card, and output formats
• Fix mode: previewing and applying fixes, backups, and what is fixable
• Configuration: .setupdoctorrc, disabling rules, thresholds, and ignore patterns
• Agents: what each agent reads and how shared files are scored
• CI integration: GitHub Actions, score history, PR comments, badges, pre-commit
• MCP server: using Doctor and Wrapped from an MCP client
• Cursor skills: installing the Doctor and Wrapped skills in Cursor
• Troubleshooting: common problems and fixes

Reference documents:

• Rules: specification of the v1 rules
• Themes: visual theme design tokens
• Decision log: assumptions, deviations and decisions made during development

Contributing

Issues and pull requests are welcome. Before opening a pull request, run the full check:

npm install

npm run check # typecheck, tests, privacy guard, version sync, em dash guard npm run build # bundles src/bin.ts to dist/bin.js

Each rule lives in its own file under src/rules/ and has a trigger fixture and a clean fixture under test/fixtures/. Rules are pure functions of the normalized model: file system access happens only in adapters under src/adapters/.

License

MIT. See LICENSE. Bundled font licenses (SIL Open Font License 1.1) are in src/data/fonts/LICENSES.md.