# How to Run Capability Diagnostics in Reasonix to Debug Tool Availability

> Learn how to run capability diagnostics in Reasonix to debug tool availability. This read-only subsystem inspects your workspace and reports the health of skills, commands, plugins, and more without modifications.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md), [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), and [`CLAUDE.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CLAUDE.md) files while flagging parsing warnings

Both the CLI command defined in [`internal/cli/doctor_capabilities.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```bash
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:

```bash
reasonix doctor capabilities --json | jq .

```

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

```bash
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:

```bash
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:

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

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

```

Isolate MCP subsystem issues from JSON output:

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.