Doctor

TinyFish Doctor

tinyfish doctor (CLI 0.22+) owns the diagnosis. Your job is to run it, do the one check it structurally cannot do, and act on what comes back. Never hand-edit config files — every repair goes through the CLI, which carries backup and merge rigor.

0. No shell?

Sandboxed surfaces (Claude.ai, Desktop, Cowork) have no npx. If you cannot run commands, skip to step 2 — it is the more valuable check anyway — then give the user the command from step 1 to run themselves.

1. Run doctor

npx -y @tiny-fish/cli@latest doctor --harness claude-code

JSON on stdout: schema_version, cli_version, ok_harnesses, ok_cli, checks[], harnesses[], repairs[].

Read schema_version before the fields. This skill describes 3 (CLI 0.22+). The command pins @latest, so a newer CLI can hand you a shape you do not know: above 3, stop reading fields, show the user --pretty output instead, and rely on step 2 for the verdict. Below 3 a single ok replaces the two verdicts and checks[] carry no scope, so read only checks[] and the exit code there.

Two verdicts, not one. ok_harnesses answers whether the user's agents can reach TinyFish; ok_cli answers whether the CLI's own credential works. checks[].scope (harness, cli, info) says which one a check counts toward, and only the harness scope moves the exit code — ok_cli: false beside exit 0 is a real state, not a contradiction. Report it as the CLI's own credential, not as a broken harness.

A warn is not a failure and does not move the exit code: doctor is saying it could not check something, not that it is broken. A registration warn whose detail says the key was not readable, or was not verified, means the key exists but doctor could not test its value — every Codex install, and any harness whose config redacts the header. Never repair on a warn, prove it in step 2.

--pretty only when showing a human the list. Never put --debug output in a report — it is the one channel carrying raw stacks and absolute paths.

2. Prove the harness reach — the part doctor cannot do

harnesses[].proves_harness_reach is false whenever doctor could not prove that this harness authenticates. It is true only where the harness's own client reports a live connection, or where a key doctor could read verified on the wire — the CLI cannot borrow an OAuth token, so every harness that reports no connection state leaves the gap to you.

--harness claude-code narrows harnesses[] to exactly one entry, so there is no ambiguity about which harness it describes.

Count the TinyFish servers first. A plugin, a CLI-written entry, and an account-level connector can all be registered at once, all pointing at the same endpoint. doctor inspects only the one named tinyfish and cannot see its siblings. Note which server it reported on.

Then call search once with a cheap query, and note which server answered — the tool namespace names it.

What a registration: pass proves depends on schema_version. On 2 and 3 an API-key registration was tested on the wire, so a stale key header is already a fail with a connect repair beside it. A pass carrying proves_harness_reach: true is the harness's own client reporting a live connection — wire evidence at any version, whatever auth_mode says. Every other pass is presence only: doctor read config, not the wire, and a stale key still passes while every call 401s. No version says anything about siblings, and a healthy sibling will answer cheerfully while the broken one stays broken.