Doctor as live state

rig doctor --json is more than human diagnostics. It's a machine-readable contract that any agent can read, reason about, and act on without scraping shell output.

This page covers what's in it and how to use it. For the full schema with every check kind, see Doctor JSON contract.

Shape

{
  "schema_version": 1,
  "generated_at": "2026-05-27T14:23:11Z",
  "ok": false,
  "manifest": { /* parsed rig.toml */ },
  "config": { /* effective include/exclude */ },
  "rig": { "name": "...", "author": "...", "version": "1.0.0", "runtime": "claude-code" },
  "paths": {
    "manifest": "rig.toml",
    "instance": ".rig/instance.toml",
    "setup_cache": ".rig/setup.json",
    "claude_skill": ".claude/skills/rig/SKILL.md",
    "mcp": ".mcp.json"
  },
  "summary": { "total_checks": 12, "gaps": 2 },
  "checks": [ /* every check, ok or not */ ],
  "gaps": [ /* required checks where ok: false */ ]
}

The check shape

Each entry in checks[] and gaps[]:

{
  "id": "env.FINANCIAL_DATASETS_API_KEY",
  "kind": "env",
  "name": "FINANCIAL_DATASETS_API_KEY",
  "required": true,
  "ok": false,
  "status": "missing",
  "message": "Required env var not set in .env or process.env",
  "remediation": {
    "action": "set in .env",
    "command": "echo 'FINANCIAL_DATASETS_API_KEY=...' >> .env"
  }
}

kind

One of:

• dir — folder exists.
• env — env var set (in target file or process.env).
• tool — CLI on PATH.
• mcp — MCP server declared (and optionally launchable).
• plugin — Claude plugin installed (currently advisory).
• permissions — Claude allow/deny rules merged.
• collab — for sync rigs: tapd version, binding, daemon, sync state.

Full kind reference: Doctor JSON contract.

required

true if this check is a hard requirement (its failure puts it in gaps[] and makes ok: false). false if it's advisory (still in checks[], ignored in gaps[]).

status

Short string. Common values:

• ok — the check passed.
• missing — required thing absent.
• found — present (used for dir checks).
• not_on_path — for tool checks.
• not_declared — for mcp/env checks where the manifest expected something the workspace doesn't have.

remediation

When known, includes an action (human description) and a command (the literal shell command to run). Agents can execute the command after asking the user when destructive; safe commands (mkdir, etc.) can run without asking.

How to use it

As an agent

rig doctor --json > /tmp/doctor.json
jq '.gaps' /tmp/doctor.json

Walk the gaps:

1. Group by kind (env vars first, then tools, then dirs, then MCP, then plugins).
2. For each env gap, ask the user for the value.
3. For each dir gap, mkdir -p it.
4. For each tool gap, surface the install hint; ask the user to install.
5. For each mcp gap, surface the launch command; ask the user to debug.
6. For each plugin gap, surface to the user (no automation yet).
7. Re-run rig doctor and confirm ok: true.

This is the repair workflow.

In CI

Exit code is non-zero on any required gap, so:

rig doctor || exit 1

Or be specific:

rig doctor --json | jq -e '.ok' > /dev/null

As a human

rig doctor          # human-readable output
rig doctor --json   # for piping into other tools

What's in .rig/setup.json

.rig/setup.json is the snapshot of rig doctor --json from the last rig install. The agent can read it for last-known-good state without re-running doctor. Live doctor takes precedence — setup.json is a cache, not authoritative.

See also

• Repair workflow
• Doctor JSON contract — the full schema with every kind.
• Troubleshoot — human-side view.