Doctor
See what's missing or broken on this machine and fix it in one click: agents, logins, the green border, updates, and your workspace.
Where: Top bar→Doctor
The Doctor is the stethoscope icon at the right end of the top bar. It checks everything Griddler depends on and lists only what needs you, each with its fix. The icon turns amber or red when a check does.
Fix what the Doctor lists
Each row has a status, a name, what it found, and one action:
| Action | What it does |
|---|---|
| ▶ Run | Opens a terminal window running the fix. When it finishes, click ↻ Re-run. |
| ↗ Open | Opens the download page when there's nothing safe to run. |
| Set up… | Opens the Welcome page, where workspace and Azure DevOps fixes happen. See First run. |
| Clean up | Ends leftover background processes Griddler started. |
| A command chip | Copies the fix. It flashes copied ✓. |
Status icons: ✓ fine, ! needs a look, ✗ broken, · for your information.
Show all N checks lists the passing rows too. Show only what needs you goes back. When nothing needs you, the Doctor says All N checks passed.
Install everything at once
When something is missing, the footer shows Set up all prerequisites. One terminal window installs it all: Node.js, git, Claude Code, and Codex. It uses winget on Windows, Homebrew on macOS, and your package manager on Linux. Logins stay manual, because they need a browser.
The Doctor re-runs its checks when the install finishes. If a step fails, the Last prerequisite install row names it.
Make panes turn green again
When the Attention hooks row warns, click Repair attention hooks. It rewrites Griddler's hooks in your Claude Code settings and in every profile, then checks again. Panes you start after that turn green when they need you. More on Know when a pane needs you.
What each row means
| Group | Row | Checks | Fix |
|---|---|---|---|
| Runtime | Node.js / npm | Node.js is installed and runs. The agents install through npm. | ▶ Run |
| git | git is installed. Required on Windows: Claude Code runs through Git Bash. | ▶ Run | |
| curl | curl is on your PATH. Panes can't turn green without it. | On Windows curl ships with the system, so the PATH is broken. Elsewhere, install it. | |
| Claude Code, Codex | CLI installed | The agent is installed and answers. A missing Codex is only ·. | ▶ Run installs or reinstalls it. |
| CLI launches | Claude Code accepts the options Griddler starts panes with. The row quotes its first error. | Close Griddler, then run the fix. | |
| Binary intact | The Claude Code program isn't half-written and matches the newest build you have. | Close Griddler, then run the fix. | |
| Logged in (default) | Your default account is signed in. | ▶ Run starts the login. | |
| Update | A newer Codex is out. | ▶ Run, or update it the way you installed it. | |
| config.toml | Codex's settings file parses. Codex won't start while it's corrupt. | Fix or delete the file the row names. | |
| Panes are dying on launch | Panes Griddler started closed right away. | See A pane closes as soon as it starts. | |
| Key bindings | A personal key binding the pane takes first, or a bindings file that doesn't parse. | Change the binding it names, or keep it. | |
| Profiles | One per extra account, like claude:personal | That account is signed in. Panes on a logged-out profile fail to sign in. | Log in… in Auth profiles. |
| Griddler | Attention hooks | Griddler's hooks are in your Claude Code settings and every profile. | Repair attention hooks |
| Hook listener :47831 | Griddler is receiving those hooks. | port in use by another Griddler: quit the other one and restart this one. A stale hook: Repair attention hooks. | |
| Agent host | Whether this machine can run a Griddler Agent itself. ✓ names your Docker Desktop version. docker is not installed or Docker Desktop is not running is only ·: you can still deploy an agent to a dev VM over ssh. | None. Install or start Docker Desktop to run an agent here. | |
| Agents | Signed in only. How many agents you've deployed, and which are silent, have a sign-in invalid (Re-sync on the Agents panel), or run an older version (Deploy again to upgrade). none deployed is only ·. | None. Fix it on the Agents panel. | |
| Leftovers | Background processes Griddler started that outlived their pane. | Clean up | |
| Update feed | Griddler can reach its updates. Automatic updates are Windows-only; on macOS and Linux the row says to install by hand. | ✗: see An update never installs. | |
| Tavern / social | Team features have a sign-in to use. | Sign in: Settings→Account. | |
| claude-mail | Mail works through your sign-in. | Sign in. Nothing else to set up. | |
| az CLI (commit boxes + bounties) | The Azure CLI is installed, signed in, and can see the project where merged pull requests pay out. Checked at most hourly; ↻ Re-run checks now. | Install the Azure CLI. Signed out: ▶ Run (az login). No access: ask for access to the project, or sign in as the account that has it. | |
| Clipboard (RDP) | Over Remote Desktop only: copies can reach your own computer. | ▶ Run restarts the clipboard helper. | |
| Last prerequisite install | Set up all prerequisites failed, and at which step. | ▶ Run tries again. | |
| Onboarding | Service account | You're signed in and the sign-in still works. | Sign in, or sign in again when it says expired. |
| Knowledge workspace | This machine has a knowledge workspace with all its folders. | Set up… | |
| Archive | When the archive last synced. Under 7 days ✓, 7–30 days ·, over 30 days or never !. | ▶ Run pulls it. | |
| Azure DevOps | You're signed in to Azure DevOps, which cloning and pulling the archive needs. | Set up… connects it, usually with no typing. |
For information only: Homebrew (a Mac missing Node.js or git), Prerequisite install (an install is running), Remote access (Phone and Remote), Character, Portrait and Shared avatar (your game character, its painting, and whether teammates see it), and Mail queue (only an admin can check it).
Signed out, most Onboarding rows read ·, not red. Service account says signed out — offline mode works fine. Team features are hidden, not broken; see Signed in or not.
Report a problem the Doctor missed
Type what's wrong in the What's going wrong? (optional, goes with the Trace) box, then click Submit Griddler Trace. Quote the Trace ID it shows to support. 🩺 Copy Griddler Trace copies the same snapshot instead. Open log folder shows Griddler's log. What a Trace contains is on Troubleshooting.
Limits
- The Doctor runs on its own 15 seconds after Griddler starts and every 6 hours, and colors the icon. Opening it checks again, reusing results from the last 30 seconds; ↻ Re-run always checks fresh.
- To repair Claude Code itself, close Griddler first. Windows won't replace a program that's running.
- If rows changed in the background, ▶ Run asks you to Re-run first so it never runs a stale fix.