Doctor¶
Run quincy doctor to check your installation for common problems. Green means good, red means something needs fixing. If you're having trouble with Quincy, this is always a good first step.
To target a specific server:
The command exits with a non-zero status if any critical check fails.
What It Checks¶
Local Checks¶
These run on the client before contacting the server:
| Check | What It Verifies |
|---|---|
| Support directory | The app data directory exists and is writable |
| quincy-server binary | The server binary is discoverable in PATH or a sibling directory |
| CLI server binding | The CLI has a saved connection to a server (name, URL, and last-connected date) |
Server Checks¶
These run on the Quincy server and are returned via GET /v1/doctor:
| Check | Status | What It Means |
|---|---|---|
| Config signature | pass/fail | The app configuration exists and its digital signature is valid |
| Orchestrator agent | pass/fail | The main orchestrator agent config loads successfully |
| llama-server binary | pass/fail/warning | The llama-server binary exists at the configured path (or is auto-discoverable) |
| Model file | pass/fail | The configured model file exists on disk |
| Providers | green/yellow/red | Reachability of configured LLM providers (green = all up, yellow = some up, red = none) |
| Agent configs | pass/fail per agent | Signature validation on every agent config |
| Agent names | pass/warning/fail | Name collision detection across all agents (see below) |
Agent Name Collisions¶
Each agent has a short name that Quincy uses to create delegation tools (like call_files). Two agents can't share the same name.
The doctor detects two types of problems:
Exact duplicates (fail) — Two or more agents have the same name. This causes tool registration collisions — both would try to create the same delegation tool.
Near-miss names (warning) — Two names are very similar (differ by only one or two characters). Names this close together can confuse the language model when it's choosing which tool to call. For example, files and file, or search and sarch.
Advanced: Authenticated vs. Unauthenticated¶
The /v1/doctor endpoint returns different levels of detail depending on authentication:
- Unauthenticated: Top-level summary statuses only (config, orchestrator, providers, binary, model, agent names)
- Authenticated: Full detail arrays — per-agent validation results, per-provider reachability, and per-collision details
The CLI authenticates automatically, so you always see the full output. This distinction matters if you're building a custom client or monitoring tool.