Doctor JSON contract

rig doctor --json

The output is the canonical machine-readable readiness state for the current rig workspace. Schema below.

Top-level

Field	Type	What
`schema_version`	int	Current: `1`. Bumped on breaking changes.
`generated_at`	string (ISO-8601)	Timestamp of the doctor run.
`ok`	boolean	`true` if every required check passes.
`manifest`	object	Parsed `rig.toml` (as JSON).
`config`	object	Effective configuration (resolved `[package].include` etc.).
`rig`	object	`name`, `author`, `version`, `runtime`.
`paths`	object	Resolved paths to key files (see below).
`summary`	object	`total_checks: int`, `gaps: int`.
`checks`	array	Every check, ok or not.
`gaps`	array	The subset of `checks` where `required: true` and `ok: false`.

`paths`

Key	What
`manifest`	Path to `rig.toml`.
`instance`	Path to `.rig/instance.toml` (may be missing for un-installed workspaces).
`setup_cache`	Path to `.rig/setup.json` (cached doctor output from last `rig install`).
`claude_skill`	Path to project-level `.claude/skills/rig/SKILL.md`.
`mcp`	Path to MCP config (typically `.mcp.json`).

Check entries

Every entry in checks[] (and the subset in gaps[]):

{
  "id": "string",
  "kind": "dir | env | tool | mcp | plugin | permissions | collab",
  "name": "string",
  "required": true,
  "ok": false,
  "status": "ok | missing | found | not_on_path | not_declared | …",
  "message": "string",
  "remediation": {
    "action": "string",
    "command": "string"
  }
}

Per-kind status values

`dir`

status	meaning
`found`	Directory exists.
`missing`	Directory doesn't exist.

Remediation command: mkdir -p <path>. Safe for agents to run unprompted.

`env`

status	meaning
`ok`	Variable is set (in target file or process.env).
`missing`	Variable not set anywhere.

Remediation: typically an interactive prompt for value, or pointer to the [env].template file.

`tool`

status	meaning
`ok`	CLI is on `PATH`.
`not_on_path`	CLI absent.

Remediation: install URL when known (e.g. https://astral.sh/uv for uvx).

`mcp`

status	meaning
`ok`	Server declared in `.mcp.json` (and, if probed, launchable).
`not_declared`	Server expected by manifest but absent from `.mcp.json`.
`not_launchable`	Server declared but the launch command failed.

Remediation: the launch command, or a pointer to fix the MCP config.

`plugin`

status	meaning
`ok`	Plugin appears to be installed (heuristic).
`not_installed`	Plugin not detected.

Advisory only — Claude Code plugin install isn't yet automated, so gaps of kind plugin are surfaced but don't make ok: false.

`permissions`

status	meaning
`ok`	Declared `[permissions]` are in `.claude/settings.json`.
`out_of_sync`	Declared rules not yet merged (run `rig install`).

`collab`

Only present when [sync] is in the manifest. Sub-checks:

name	status	meaning
`tapd`	`ok`, `not_on_path`, `version_mismatch`	Daemon binary.
`binding`	`ok`, `not_initialised`	`.rig/tap-binding.local.json` valid.
`daemon`	`running`, `stopped`	Process state.
`sync`	`idle`, `pulling`, `conflicts`, `apply_errors`, `offline`	Sync state.

Remediation for each typically points at a rig workspace command (e.g. rig resume, rig status).

`summary`

{
  "total_checks": 12,
  "gaps": 2
}

Exit code

The CLI exits non-zero if summary.gaps > 0. Useful in scripts:

rig doctor || exit 1

Schema version

Currently 1. Future versions may add fields (forward-compatible) or restructure (in which case schema_version bumps). Read carefully if you're building tools on top.