11. Diagnostics

Doctor and inspect

When the screen looks wrong, copy does not land, or a project is not picking up a rules file, start here. **Doctor** checks this terminal. **Inspect** lists the configuration Matcha CLI discovered for the current directory.

Two commands, two jobs

You want	Run
Terminal, color, clipboard, keyboard, multiplexer	`/doctor` or `matcha doctor`
Rules, skills, MCP, plugins, config layers	`matcha inspect`

Use /doctor when Matcha CLI is already open. Use matcha doctor in the shell when the TUI will not start. matcha inspect is a one-shot CLI report; it does not open the TUI.

Doctor: check this session

In the TUI:

/doctor

Aliases: /terminal-setup, /terminal-check, /terminal-info.

From a shell (no TUI):

matcha doctor
matcha doctor --json

--json is the same report in machine-readable form. Piped output still reports the same color capability as an interactive run.

A report can list issues or recommendations and still exit successfully. Zero issues does not mean every optional feature works; it means Doctor found nothing it classifies as broken.

What the report contains

The human report starts with **Matcha CLI Doctor** and groups facts:

**Environment** — detected terminal, multiplexer (tmux / Zellij / Byobu), SSH, color depth, available themes, keyboard / newline behavior, config schema, home-migration status.
**Clipboard** — native OS clipboard, tmux paste buffer, OSC 52, SSH wrap.
**Voice** — input device Doctor would use, when audio capture is in this build. The probe does not start recording.
**Findings** — ! issues and i recommendations, each with a stable id such as terminal.tmux-truecolor.
**Runtime leftovers** — leftover ~/.grok sockets, locks, or crash directories, identified only. Doctor does not delete them.

Standalone matcha doctor cannot see live TUI facts (notification focus, sandbox profile conflicts, whether fullscreen is actually active). The report then says **Needs a running session** and tells you to start matcha and run /doctor.

Apply an automatic fix

When a finding has an automatic setup, Doctor prints a command. List what can be applied here:

/doctor fix

matcha doctor fix

Apply **one** named fix at a time. Short handle or full id both work:

/doctor fix tmux-clipboard
/doctor fix terminal.tmux-truecolor

matcha doctor fix dcs-passthrough --yes
matcha doctor fix ssh-wrap

The five automatic fixes:

Handle	What it writes
`ssh-wrap`	A shell alias so SSH / container sessions go through `matcha wrap`
`tmux-clipboard`	`set -g set-clipboard on`
`dcs-passthrough`	`set -wg allow-passthrough on`
`tmux-extended-keys`	`set -g extended-keys on`
`tmux-truecolor`	`set -as terminal-features ",*:RGB"`

Without --yes, the CLI prints a preview and asks Apply this fix? [y/N]. Non-interactive stdin needs --yes.

A tmux fix edits only the **persistent** config on the computer that hosts the tmux server (plain tmux: $HOME/.tmux.conf; Byobu-tmux: the effective BYOBU_CONFIG_DIR). Matcha CLI preserves line endings and mode, makes a backup when changing an existing file, and refuses conflicting or ambiguous assignments. It does **not** run tmux source-file or change the live server.

Reload with the exact command printed after apply, or detach and reattach, then run /doctor again. Until reload, the live finding is expected to remain.

Inspect: what this directory discovered

From the project you care about:

matcha inspect
matcha inspect --json

Inspect does not spawn MCP or LSP servers. It shows what Matcha CLI **would** load for this working directory.

The human report includes:

**Environment** — version, current directory, git root, whether the project folder is trusted.
**Project Instructions** — AGENTS.md, CLAUDE.md, .cursor/rules, and similar files, with scope and an approximate token count.
**Permissions** — loaded and skipped rules; policy-enforced settings without secret values.
**Skills, agents, plugins, MCP, LSP, hooks** — each tagged with origin (project / user / plugin / builtin / config). These are the labels on the report.
**Config Sources** — user ~/.matcha/config.toml, project files, and other layers. A layer can be marked (empty) or (parse error).
**Config Warnings** and **MCP Config Problems** — invalid fields or [mcp_servers.*] entries that were skipped so the rest of the file can still load.
**Harness Compatibility** — [compat.claude] / [compat.cursor] cells (on / OFF and whether that came from config or default).

When **Project trusted** is no, repo-local hooks, plugins, and MCP/LSP rows are gated the same way a live session would gate them.

--json is the machine form, including a redacted config export (configExport.redactedToml). Use that when you need to compare layers without copying secrets.

Toggle a compat source in ~/.matcha/config.toml, for example [compat.cursor] rules = false, then run matcha inspect again. Disabled entries show [disabled].

What these commands are not

Doctor and inspect stay on this machine. They do not upload traces, send feedback, or check for product updates. Names that look like diagnostics are not recovery procedures here — read the error, fix the named file or terminal setting, then run the same command again.