Capability diagnostics

September 2, 2026 · View on GitHub

Reasonix ships a read-only capability diagnostics model shared by the CLI and desktop Settings → Diagnostics. It reports Skills, Commands, Hooks, plugin packages, MCP servers, and instruction docs (AGENTS.md / REASONIX.md / CLAUDE.md).

Write policy

Mode	Config files	MCP stats / schema cache	Network / MCP processes
Static (default) + desktop	Never written (`LoadForRootReadOnly`)	Never written	None
CLI `--live`	Never written	Not written (`SkipPersistence`)	Starts automatic MCP in an isolated Host

How to use (quick start)

Goal	What to run
Check this workspace’s skills / hooks / MCP / plugins	`reasonix doctor capabilities`
Machine-readable report (CI / support)	`reasonix doctor capabilities --json`
Another project root	`reasonix doctor capabilities --root /path/to/project`
Probe MCP startup for real (starts third-party servers)	`reasonix doctor capabilities --live --timeout 5s`
Ask the agent to walk through config / fix guidance	`/reasonix-guide` in chat, or ask naturally
GUI health view	Desktop Settings → Diagnostics

Default is static and safe: no network, no MCP child processes. Use --live only when you explicitly want to start automatic MCP servers.

Related (unchanged) doctor commands:

reasonix doctor                  # env / providers / sandbox snapshot
reasonix doctor session <id>     # support session bundle
reasonix doctor redact-sessions  # redact secrets in session files

Everyday workflows

1. “Skill / command is missing or wrong”

reasonix doctor capabilities --json | jq '.skills.entries, .commands.entries, .issues'

Look for:

skill.shadowed / command.shadowed — a higher-priority path won
skill.disabled — name is in [skills].disabled_skills
skill.missing_description — skill loads but index quality is weak
command.read_failed — unreadable or broken markdown

Then open Settings → Skills (or fix the file under .reasonix/skills / .reasonix/commands).

2. “Project hooks never fire”

reasonix doctor capabilities | sed -n '/Hooks/,/Plugins/p'

Project hooks load automatically from .reasonix/settings.json. If they do not fire, confirm the active workspace and restart Reasonix after saving. Matchers are anchored regexes: file does not match read_file.

3. “MCP tools don’t show up”

Static first (no side effects):

reasonix doctor capabilities --json | jq '.mcp.servers, .issues[] | select(.subsystem=="mcp")'

Only if you accept starting third-party servers:

reasonix doctor capabilities --live --timeout 10s --json

Common codes: mcp.command_not_found, mcp.invalid_transport, mcp.start_failed, mcp.no_tools. On desktop, prefer Settings → Diagnostics with “Include current session runtime” to read the active tab Host without starting a second Host.

Each MCP entry identifies the exact winning configuration with source, source_path, and effective. Startup failures also report startup_stage (launch, authorization, initialize, or tools/list), startup_elapsed_ms, and a bounded, credential-redacted stderr tail. This distinguishes duplicate/shadowed registration from a genuinely slow or broken handshake without exposing full process output.

4. Ask the agent (`reasonix-guide`)

In an interactive session:

/reasonix-guide

or:

My MCP server X is configured but the model never sees its tools — diagnose.

The built-in skill is inline (runAs: inline). It tells the model to prefer:

reasonix doctor capabilities --json

and to use --live only after you explicitly allow external MCP. Project or global skills named reasonix-guide override the builtin; you can also hide it with [skills].disabled_skills = ["reasonix-guide"].

CLI reference

reasonix doctor capabilities [--root PATH] [--json] [--live] [--timeout 5s]

Flag	Meaning
`--root`	Workspace root (default: current directory). Uses `config.LoadForRoot`.
`--json`	Write one JSON object to stdout only (warnings go to stderr).
`--live`	Start automatic MCP servers in an isolated Host (may network).
`--timeout`	Per-server live timeout, 1s–60s, default `5s`. Requires `--live`.

Modes

Mode	Behavior
Static (default)	No network; no stdio / HTTP / SSE MCP child processes.
Live (`--live`)	Stderr risk banner; only servers with automatic start intent; `auto_start=false` → `skipped`; concurrency 4; Host always closed.

Desktop “include current session runtime” is not CLI --live: the desktop only reads the active tab Host and never starts MCP.

Exit codes

Code	Meaning
`0`	No `error`-severity issues (warnings/info are allowed)
`1`	One or more `error` issues, or live MCP start failures
`2`	Bad flags / usage

Examples:

# Human-readable, current directory
reasonix doctor capabilities

# Fail CI only on hard errors
reasonix doctor capabilities --json
# shell: exit code 1 if summary.errors > 0

# Live probe with a longer timeout
reasonix doctor capabilities --live --timeout 15s --json 2>live-warn.txt

Existing reasonix doctor, doctor session, and doctor redact-sessions commands keep their own JSON schemas — capability fields are not mixed into those reports.

Desktop

Open Settings → Diagnostics:

Control	Behavior
Open page	Loads a static report for the active workspace root
Refresh	Re-runs collection with the current runtime toggle
Copy redacted JSON	Clipboard paste-safe report (paths already redacted)
Include current session runtime	Merge connected / failed / deferred / disabled from the active tab Host only
Open settings (on an issue)	Jumps to MCP / Skills / Plugins / Hooks when `settings_tab` is set

The page never edits config, executes hooks, auto-enables packages, or reconnects MCP. Opening Diagnostics does not rebuild the controller or snapshot the session.

JSON schema (version 1)

Top-level fields:

schema_version (always 1)
root (display path)
live (bool)
summary — error/warning/info counts and resource counts
instructions, skills, commands, hooks, plugins, mcp
issues[] — ordered list of findings

Plugin package entries are additive for Manifest v2: each package also reports prompts and themes counts and a runtime flag when the plugin declares a code runtime (see Plugin packages). Older readers can ignore these fields; schema_version stays 1.

Issue shape:

{
  "severity": "error|warning|info",
  "code": "skill.shadowed",
  "subsystem": "skills",
  "name": "demo",
  "source": "<workspace>/.reasonix/skills/demo/SKILL.md",
  "message": "...",
  "remediation": "...",
  "settings_tab": "skills"
}

Stable codes include:

skill.shadowed, skill.missing_description, skill.disabled
command.shadowed, command.read_failed
hook.invalid_matcher, hook.missing_command, hook.malformed_settings
plugin.missing_root, plugin.invalid_manifest, plugin.compatibility
mcp.invalid_transport, mcp.command_not_found, mcp.missing_command, mcp.missing_url
mcp.start_failed, mcp.no_tools, mcp.runtime_unavailable

Array and issue order is deterministic for scripting and tests.

Severity

Severity	Meaning	CLI exit
`error`	Broken config or failed live start	`1`
`warning`	Actionable but non-fatal (e.g. a missing hook command)	`0`
`info`	Shadowing, disabled assets, runtime unavailable	`0`

Path and secret safety

Reports rewrite paths as:

<workspace>/... under the diagnosis root
~/... under the user home
<external>/basename for other absolute paths (no full external path)

They never intentionally emit usernames, full external paths, environment variable values, header values, tokens, or URL query strings. MCP entries list env/header keys only. Error text that may carry raw HTTP response bodies or MCP stderr passes through the product-wide secret redactor (Authorization schemes, Bearer/JWT/vendor tokens, KEY=value and JSON "key":"value" credential forms, Cookie/Set-Cookie values) and is truncated to 400 characters. Prefer copying report JSON into issues or chat over pasting raw config files.

What is not diagnosed here

Need	Use instead
Provider keys, proxy, sandbox OS support	`reasonix doctor`
Full session transcript for support	`reasonix doctor session <id>`
One plugin package only	`reasonix plugin doctor <name>`
Interactive MCP list in a chat session	`/mcp`

Cache impact

Adding the built-in reasonix-guide skill appends one line to the next changed session-context Skills catalog. The skill body is loaded only on invocation. Diagnostics itself is not part of the provider prompt.