| 1 | # Capability diagnostics |
| 2 | |
| 3 | <a href="./CAPABILITY_DIAGNOSTICS.zh-CN.md">简体中文</a> |
| 4 | · |
| 5 | <a href="./GUIDE.md">Guide</a> |
| 6 | · |
| 7 | <a href="./PLUGIN_PACKAGES.md">Plugin packages</a> |
| 8 | |
| 9 | Reasonix ships a read-only capability diagnostics model shared by the CLI and |
| 10 | desktop **Settings → Diagnostics**. It reports Skills, Commands, Hooks, plugin |
| 11 | packages, MCP servers, and instruction docs (`AGENTS.md` / `REASONIX.md` / |
| 12 | `CLAUDE.md`). |
| 13 | |
| 14 | **Write policy** |
| 15 | |
| 16 | | Mode | Config files | MCP stats / schema cache | Network / MCP processes | |
| 17 | | --- | --- | --- | --- | |
| 18 | | Static (default) + desktop | Never written (`LoadForRootReadOnly`) | Never written | None | |
| 19 | | CLI `--live` | Never written | **Not written** (`SkipPersistence`) | Starts automatic MCP in an isolated Host | |
| 20 | |
| 21 | ## How to use (quick start) |
| 22 | |
| 23 | | Goal | What to run | |
| 24 | | --- | --- | |
| 25 | | Check this workspace’s skills / hooks / MCP / plugins | `reasonix doctor capabilities` | |
| 26 | | Machine-readable report (CI / support) | `reasonix doctor capabilities --json` | |
| 27 | | Another project root | `reasonix doctor capabilities --root /path/to/project` | |
| 28 | | Probe MCP startup for real (starts third-party servers) | `reasonix doctor capabilities --live --timeout 5s` | |
| 29 | | Ask the agent to walk through config / fix guidance | `/reasonix-guide` in chat, or ask naturally | |
| 30 | | GUI health view | Desktop **Settings → Diagnostics** | |
| 31 | |
| 32 | **Default is static and safe:** no network, no MCP child processes. Use `--live` |
| 33 | only when you explicitly want to start automatic MCP servers. |
| 34 | |
| 35 | Related (unchanged) doctor commands: |
| 36 | |
| 37 | ```bash |
| 38 | reasonix doctor # env / providers / sandbox snapshot |
| 39 | reasonix doctor session <id> # support session bundle |
| 40 | reasonix doctor redact-sessions # redact secrets in session files |
| 41 | ``` |
| 42 | |
| 43 | ## Everyday workflows |
| 44 | |
| 45 | ### 1. “Skill / command is missing or wrong” |
| 46 | |
| 47 | ```bash |
| 48 | reasonix doctor capabilities --json | jq '.skills.entries, .commands.entries, .issues' |
| 49 | ``` |
| 50 | |
| 51 | Look for: |
| 52 | |
| 53 | - `skill.shadowed` / `command.shadowed` — a higher-priority path won |
| 54 | - `skill.disabled` — name is in `[skills].disabled_skills` |
| 55 | - `skill.missing_description` — skill loads but index quality is weak |
| 56 | - `command.read_failed` — unreadable or broken markdown |
| 57 | |
| 58 | Then open **Settings → Skills** (or fix the file under `.reasonix/skills` / |
| 59 | `.reasonix/commands`). |
| 60 | |
| 61 | ### 2. “Project hooks never fire” |
| 62 | |
| 63 | ```bash |
| 64 | reasonix doctor capabilities | sed -n '/Hooks/,/Plugins/p' |
| 65 | ``` |
| 66 | |
| 67 | Project hooks load automatically from `.reasonix/settings.json`. If they do not |
| 68 | fire, confirm the active workspace and restart Reasonix after saving. Matchers |
| 69 | are **anchored** regexes: `file` does not match `read_file`. |
| 70 | |
| 71 | ### 3. “MCP tools don’t show up” |
| 72 | |
| 73 | 1. Static first (no side effects): |
| 74 | |
| 75 | ```bash |
| 76 | reasonix doctor capabilities --json | jq '.mcp.servers, .issues[] | select(.subsystem=="mcp")' |
| 77 | ``` |
| 78 | |
| 79 | 2. Only if you accept starting third-party servers: |
| 80 | |
| 81 | ```bash |
| 82 | reasonix doctor capabilities --live --timeout 10s --json |
| 83 | ``` |
| 84 | |
| 85 | Common codes: `mcp.command_not_found`, `mcp.invalid_transport`, |
| 86 | `mcp.start_failed`, `mcp.no_tools`. On desktop, prefer **Settings → Diagnostics** |
| 87 | with “Include current session runtime” to read the **active tab Host** without |
| 88 | starting a second Host. |
| 89 | |
| 90 | Each MCP entry identifies the exact winning configuration with `source`, |
| 91 | `source_path`, and `effective`. Startup failures also report `startup_stage` |
| 92 | (`launch`, `authorization`, `initialize`, or `tools/list`), |
| 93 | `startup_elapsed_ms`, and a bounded, credential-redacted `stderr` tail. This |
| 94 | distinguishes duplicate/shadowed registration from a genuinely slow or broken |
| 95 | handshake without exposing full process output. |
| 96 | |
| 97 | ### 4. Ask the agent (`reasonix-guide`) |
| 98 | |
| 99 | In an interactive session: |
| 100 | |
| 101 | ```text |
| 102 | /reasonix-guide |
| 103 | ``` |
| 104 | |
| 105 | or: |
| 106 | |
| 107 | ```text |
| 108 | My MCP server X is configured but the model never sees its tools — diagnose. |
| 109 | ``` |
| 110 | |
| 111 | The built-in skill is **inline** (`runAs: inline`). It tells the model to prefer: |
| 112 | |
| 113 | ```bash |
| 114 | reasonix doctor capabilities --json |
| 115 | ``` |
| 116 | |
| 117 | and to use `--live` only after you explicitly allow external MCP. Project or |
| 118 | global skills named `reasonix-guide` override the builtin; you can also hide it |
| 119 | with `[skills].disabled_skills = ["reasonix-guide"]`. |
| 120 | |
| 121 | ## CLI reference |
| 122 | |
| 123 | ```bash |
| 124 | reasonix doctor capabilities [--root PATH] [--json] [--live] [--timeout 5s] |
| 125 | ``` |
| 126 | |
| 127 | | Flag | Meaning | |
| 128 | | --- | --- | |
| 129 | | `--root` | Workspace root (default: current directory). Uses `config.LoadForRoot`. | |
| 130 | | `--json` | Write one JSON object to **stdout** only (warnings go to stderr). | |
| 131 | | `--live` | Start **automatic** MCP servers in an isolated Host (may network). | |
| 132 | | `--timeout` | Per-server live timeout, **1s–60s**, default `5s`. Requires `--live`. | |
| 133 | |
| 134 | ### Modes |
| 135 | |
| 136 | | Mode | Behavior | |
| 137 | | --- | --- | |
| 138 | | **Static (default)** | No network; no stdio / HTTP / SSE MCP child processes. | |
| 139 | | **Live (`--live`)** | Stderr risk banner; only servers with automatic start intent; `auto_start=false` → `skipped`; concurrency 4; Host always closed. | |
| 140 | |
| 141 | Desktop “include current session runtime” is **not** CLI `--live`: the desktop |
| 142 | only **reads** the active tab Host and never starts MCP. |
| 143 | |
| 144 | ### Exit codes |
| 145 | |
| 146 | | Code | Meaning | |
| 147 | | --- | --- | |
| 148 | | `0` | No `error`-severity issues (warnings/info are allowed) | |
| 149 | | `1` | One or more `error` issues, or live MCP start failures | |
| 150 | | `2` | Bad flags / usage | |
| 151 | |
| 152 | Examples: |
| 153 | |
| 154 | ```bash |
| 155 | # Human-readable, current directory |
| 156 | reasonix doctor capabilities |
| 157 | |
| 158 | # Fail CI only on hard errors |
| 159 | reasonix doctor capabilities --json |
| 160 | # shell: exit code 1 if summary.errors > 0 |
| 161 | |
| 162 | # Live probe with a longer timeout |
| 163 | reasonix doctor capabilities --live --timeout 15s --json 2>live-warn.txt |
| 164 | ``` |
| 165 | |
| 166 | Existing `reasonix doctor`, `doctor session`, and `doctor redact-sessions` |
| 167 | commands keep their own JSON schemas — capability fields are **not** mixed into |
| 168 | those reports. |
| 169 | |
| 170 | ## Desktop |
| 171 | |
| 172 | Open **Settings → Diagnostics**: |
| 173 | |
| 174 | | Control | Behavior | |
| 175 | | --- | --- | |
| 176 | | Open page | Loads a **static** report for the active workspace root | |
| 177 | | Refresh | Re-runs collection with the current runtime toggle | |
| 178 | | Copy redacted JSON | Clipboard paste-safe report (paths already redacted) | |
| 179 | | Include current session runtime | Merge connected / failed / deferred / disabled from the **active tab Host** only | |
| 180 | | Open settings (on an issue) | Jumps to MCP / Skills / Plugins / Hooks when `settings_tab` is set | |
| 181 | |
| 182 | The page never edits config, executes hooks, auto-enables packages, or |
| 183 | reconnects MCP. Opening Diagnostics does not rebuild the controller or snapshot |
| 184 | the session. |
| 185 | |
| 186 | ## JSON schema (version 1) |
| 187 | |
| 188 | Top-level fields: |
| 189 | |
| 190 | - `schema_version` (always `1`) |
| 191 | - `root` (display path) |
| 192 | - `live` (bool) |
| 193 | - `summary` — error/warning/info counts and resource counts |
| 194 | - `instructions`, `skills`, `commands`, `hooks`, `plugins`, `mcp` |
| 195 | - `issues[]` — ordered list of findings |
| 196 | |
| 197 | Plugin package entries are additive for Manifest v1: each package also |
| 198 | reports `prompts` and `themes` counts and a `runtime` flag when the plugin |
| 199 | declares a code runtime (see |
| 200 | <a href="./PLUGIN_PACKAGES.md">Plugin packages</a>). Older readers can ignore |
| 201 | these fields; `schema_version` stays `1`. |
| 202 | |
| 203 | Issue shape: |
| 204 | |
| 205 | ```json |
| 206 | { |
| 207 | "severity": "error|warning|info", |
| 208 | "code": "skill.shadowed", |
| 209 | "subsystem": "skills", |
| 210 | "name": "demo", |
| 211 | "source": "<workspace>/.reasonix/skills/demo/SKILL.md", |
| 212 | "message": "...", |
| 213 | "remediation": "...", |
| 214 | "settings_tab": "skills" |
| 215 | } |
| 216 | ``` |
| 217 | |
| 218 | Stable codes include: |
| 219 | |
| 220 | - `skill.shadowed`, `skill.missing_description`, `skill.disabled` |
| 221 | - `command.shadowed`, `command.read_failed` |
| 222 | - `hook.invalid_matcher`, `hook.missing_command`, `hook.malformed_settings` |
| 223 | - `plugin.missing_root`, `plugin.invalid_manifest`, `plugin.compatibility` |
| 224 | - `mcp.invalid_transport`, `mcp.command_not_found`, `mcp.missing_command`, `mcp.missing_url` |
| 225 | - `mcp.start_failed`, `mcp.no_tools`, `mcp.runtime_unavailable` |
| 226 | |
| 227 | Array and issue order is deterministic for scripting and tests. |
| 228 | |
| 229 | ### Severity |
| 230 | |
| 231 | | Severity | Meaning | CLI exit | |
| 232 | | --- | --- | --- | |
| 233 | | `error` | Broken config or failed live start | `1` | |
| 234 | | `warning` | Actionable but non-fatal (e.g. a missing hook command) | `0` | |
| 235 | | `info` | Shadowing, disabled assets, runtime unavailable | `0` | |
| 236 | |
| 237 | ## Path and secret safety |
| 238 | |
| 239 | Reports rewrite paths as: |
| 240 | |
| 241 | - `<workspace>/...` under the diagnosis root |
| 242 | - `~/...` under the user home |
| 243 | - `<external>/basename` for other absolute paths (no full external path) |
| 244 | |
| 245 | They never intentionally emit usernames, full external paths, environment |
| 246 | variable **values**, header **values**, tokens, or URL query strings. MCP |
| 247 | entries list env/header **keys** only. Error text that may carry raw HTTP |
| 248 | response bodies or MCP stderr passes through the product-wide secret redactor |
| 249 | (Authorization schemes, Bearer/JWT/vendor tokens, `KEY=value` and JSON |
| 250 | `"key":"value"` credential forms, Cookie/Set-Cookie values) and is truncated to |
| 251 | 400 characters. Prefer copying report JSON into issues or chat over pasting raw |
| 252 | config files. |
| 253 | |
| 254 | ## What is *not* diagnosed here |
| 255 | |
| 256 | | Need | Use instead | |
| 257 | | --- | --- | |
| 258 | | Provider keys, proxy, sandbox OS support | `reasonix doctor` | |
| 259 | | Full session transcript for support | `reasonix doctor session <id>` | |
| 260 | | One plugin package only | `reasonix plugin doctor <name>` | |
| 261 | | Interactive MCP list in a chat session | `/mcp` | |
| 262 | |
| 263 | ## Cache impact |
| 264 | |
| 265 | Adding the built-in `reasonix-guide` skill appends **one stable index line** to |
| 266 | the system-prompt skills index after upgrade. The skill body is loaded only on |
| 267 | invocation. Diagnostics itself is not part of the provider prompt. |
| 268 |