How to Run Capability Diagnostics in Reasonix to Debug Tool Availability

Capability diagnostics is a read-only diagnostic subsystem that inspects your Reasonix workspace and reports the health of skills, commands, plugins, MCP servers, and instruction docs without modifying files or launching network connections by default.

When tools or skills fail to appear in the esengine/DeepSeek-Reasonix environment, you need a systematic way to verify configuration integrity. The capability diagnostics system provides a comprehensive health check for your workspace components, enabling you to quickly identify missing MCP servers, shadowed commands, or invalid plugin manifests before they disrupt your workflow.

What Capability Diagnostics Inspects

The diagnostic collector defined in internal/capdiag/collect.go evaluates six major component categories:

• Skills, Commands, and Hooks: Validates presence, detects shadowing, checks disabled status, and audits description quality
• Plugin packages: Verifies manifest validity, runtime availability, and counts prompts or themes
• MCP servers: Tests transport connectivity, tool registration, startup success, and runtime availability
• Instruction docs: Checks loadability of AGENTS.md, REASONIX.md, and CLAUDE.md files while flagging parsing warnings

Both the CLI command defined in internal/cli/doctor_capabilities.go and the Desktop UI share this diagnostic model, ensuring consistent reporting across interfaces.

Running Diagnostics from the CLI

The primary interface for running capability diagnostics is the reasonix doctor capabilities command.

Basic Human-Readable Output

To inspect the current workspace with formatted console output:

reasonix doctor capabilities

This static analysis reads configuration files from .reasonix/* and builds a structured report without spawning processes or making network requests.

Machine-Readable JSON for CI Pipelines

For automated testing environments, emit JSON to parse programmatically:

reasonix doctor capabilities --json | jq .

Integrate into CI scripts by checking the summary.errors field:

if reasonix doctor capabilities --json | jq -e '.summary.errors > 0' > /dev/null; then
  echo "Diagnostics reported errors"
  exit 1
fi

Diagnosing External Project Roots

Analyze a different workspace without changing your current directory:

reasonix doctor capabilities --root /path/to/other/project --json

Probing Live MCP Servers

Enable the --live flag to start MCP processes and verify actual runtime availability:

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

This mode spawns child processes for servers advertising auto_start=true and may generate network traffic. Failures during live probing appear as error-level diagnostics in the report.

Understanding Diagnostic Modes

The system operates in two distinct modes controlled by the --live flag:

Mode	Behavior	Use Case
Static (default)	No network traffic, no MCP child processes. Safe for CI and read-only filesystems.	Automated testing, pre-commit hooks
Live	Starts MCP servers in an isolated sandboxed host. Reports actual runtime availability.	Debugging missing tools, verifying server connectivity

Exit Codes and Automation

The command returns specific exit codes defined in the CLI handler:

Code	Meaning
0	Success. No error-severity diagnostics detected (warnings and info allowed).
1	Failure. One or more error diagnostics found, or live MCP server startup failed.
2	Usage error. Incorrect flags or malformed arguments provided.

These codes enable reliable shell scripting and pipeline integration.

Desktop UI Diagnostics

Users running the Reasonix Desktop application can access the same collector through the graphical interface:

1. Open Settings → Diagnostics
2. Click Refresh to execute the static collector
3. Toggle Include current session runtime to merge the active tab's Host state without starting new MCP servers

The Desktop UI invokes the same internal/capdiag/collect.go logic used by the CLI, ensuring parity between interfaces.

Filtering and Parsing Results

Extract specific diagnostic categories using standard Unix tools.

List all hook-related diagnostics:

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

Isolate MCP subsystem issues from JSON output:

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

Core Source Files

Understanding these implementation files helps when extending or debugging the diagnostic system:

• internal/cli/doctor_capabilities.go: Defines the CLI command structure, flag parsing for --live, --json, --root, and --timeout, and exit code handling.
• internal/capdiag/collect.go: Implements the core collection logic that walks the workspace, loads .reasonix/* configuration, inspects the skill/command index, parses plugin manifests, and optionally starts MCP servers when --live is specified. Generates schema version 1 JSON reports.
• internal/capdiag/render.go: Handles formatting for human-readable console output and JSON marshaling.

Summary

• Capability diagnostics provides read-only inspection of Reasonix workspace health, covering skills, plugins, MCP servers, and instruction documents.
• Use reasonix doctor capabilities for static analysis, or add --live to test actual MCP server runtime availability.
• Machine-readable JSON output via --json enables CI integration using exit codes 0 (success) and 1 (errors detected).
• The diagnostic engine lives in internal/capdiag/collect.go and is shared between CLI and Desktop UI interfaces.
• Filter specific issues using jq or sed to isolate problems with particular subsystems like MCP or hooks.

Frequently Asked Questions

What is the difference between static and live capability diagnostics?

Static diagnostics analyze configuration files and manifests without starting processes or making network connections, making them safe for CI environments. Live diagnostics (--live) spawn MCP child processes in a sandboxed host to verify actual server startup and tool registration, which may use network resources and report runtime-specific failures.

Why are my MCP tools showing as unavailable when I run static diagnostics?

Static mode only checks manifest validity and configuration presence. Since it does not start MCP servers by design, it cannot verify runtime availability. Run reasonix doctor capabilities --live to test whether the servers actually start and register their tools correctly.

How do I integrate capability diagnostics into a CI pipeline?

Use the --json flag combined with exit code checking. A return code of 0 indicates no errors, while 1 signals hard failures. Parse the JSON output with jq to check .summary.errors or filter specific subsystems. The static mode (default) is recommended for CI because it requires no network access or process spawning.

Where does the diagnostic report schema version come from?

The collector in internal/capdiag/collect.go generates reports conforming to schema version 1, which defines the structure for component health, issue severity levels (error, warning, info), and metadata. Both the CLI renderer and Desktop UI consume this standardized schema.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}