Doctor

preflight doctor reads your Claude Code, Cursor and Codex files and reports findings. Each finding has a stable code, a severity (error, warning or note), a short explanation, an estimated token cost per session when one is known, and the smallest fix. There is no overall score: findings are listed by severity, each with an icon and a word.

preflight doctor                 # grouped, readable output in a terminal
preflight doctor --json          # JSON array of findings (also the default when piped)
preflight doctor --days 60       # usage window for unused-context checks
preflight doctor --processes     # count running MCP server processes (macOS, Linux)
preflight doctor --measure       # run SessionStart hooks once to measure their output
preflight doctor --connect       # start or call each MCP server (opt-in)

The static doctor only reads files. --measure and --connect run programs and are opt-in; in the desktop app they are previewed and confirmed first. --measure runs each distinct SessionStart hook once in a new, empty temporary folder (CLAUDE_PROJECT_DIR points there) with a time limit, and deletes the folder afterwards. --processes runs ps and is skipped cleanly on other systems.

Token figures are character estimates (characters / 4), the same as the context map. MCP tool definitions are not measured locally, so their cost is shown as unknown, never as zero.

FindingsCopy Anchor Link

Existing codes such as secret, broad-permissions, mcp-unverified, drift and settings-secret are unchanged.

Usage-based checks (unused-context, mcp-global-single-project, cache hygiene) read the session transcripts in ~/.claude/projects from the window. When there are none, they are listed under Skipped with the reason instead of reporting anything. Cache heuristics ignore subagent lines, which share the parent session. With --no-transcripts, or when transcript reading is turned off in the desktop app, these checks are skipped with that reason. Only Claude Code transcripts are read, so resources that only Codex uses are never reported as unused.

ThresholdsCopy Anchor Link

Every threshold can be set under doctor in preflight.config.json. The global configuration (~/.preflight/global/preflight.config.json) applies first, then the project's. Missing keys keep their default.

{
  "version": 1,
  "activeProfile": "default",
  "profiles": { "default": { "resources": [] } },
  "doctor": {
    "unusedDays": 30,
    "manualMaxUses": 1,
    "instructionsMaxLines": 200,
    "skillSimilarity": 0.5,
    "skillTarget": { "min": 60, "max": 80 },
    "maxPlugins": 15,
    "maxMcpServers": 10,
    "hookOutputChars": 1000,
    "hookTotalChars": 2000,
    "hookTimeoutMs": 10000,
    "mcpProcessMemoryMb": 1024,
    "cacheGapMinutes": 5,
    "duplicateMinChars": 40
  }
}

InstructionsCopy Anchor Link

preflight instructions lint [file]
preflight instructions draft [--scope global|project] [--agent claude-code|codex] [--write]

lint reports lines, estimated tokens (with and without @imports, resolved up to five levels deep), broken imports, lines repeated from skills, and credentials, for ~/.claude/CLAUDE.md, the project's CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md, plus Codex's $CODEX_HOME/AGENTS.md (default ~/.codex/AGENTS.md) and AGENTS.md. draft --agent codex keeps the blocks that Preflight manages for instructions resources (<!-- preflight:begin … -->) unchanged.

draft proposes a concise file and prints it as a diff. It keeps your rules, removes repeated lines, lines a skill already carries and broken imports, then adds only the short sections your file does not cover: style, verification (with the check commands detected in the project), subagent models (Claude Code), secrets, and skills. Nothing is written without --write; --write --dry-run previews the file change, and a written draft goes through the journaled transaction, so preflight rollback undoes it.

DesktopCopy Anchor Link

Health → Doctor groups findings by severity, with the explanation, fix and token cost of each. Count MCP processes runs the --processes check; Measure startup hooks previews and then runs --measure. Health → Instructions shows the instructions file, a line gauge against the limit, imports and lint findings; Draft improvements opens the diff in the review dialog and writes only when you apply it. The Overview shows the number of global skills against the target range.

Adapted in part from agent-compass (MIT); see THIRD_PARTY_NOTICES.md.

Manual skills and switchesCopy Anchor Link

preflight skill manual deploy lint-fix        # preview
preflight skill manual deploy lint-fix --apply
preflight skill auto deploy --apply            # undo
preflight disable grafana --apply              # skill, MCP server, plugin, hook, subagent
preflight enable grafana --apply

Without --apply, each command only previews. skill manual changes one frontmatter line and keeps every other byte of SKILL.md. disable uses the switch of the agent when it has one: enabledPlugins for Claude Code plugins, disabledMcpjsonServers for project MCP servers, enabled = false for Codex MCP servers. Otherwise Preflight moves the entry or file to .preflight/disabled/ (in the home or project folder) and enable puts it back. The preview shows the listing tokens saved. There is no doctor --fix yet.