CLI Doctor

  • Desktop app
  • All plans

What it does

An agent in AgentsRoom is a third-party CLI (claude, codex, grok, agy, ...) started in a terminal, and AgentsRoom never bundles those binaries. When one fails to start, the most opaque failure in AI coding, CLI Doctor answers what broke and what to do now. An agent whose CLI is confirmed absent from this computer is not launched at all: a full-pane card names the problem and offers Install <CLI>, Use <another CLI you have> and I already have it, and the agent starts by itself once the CLI is there (since 2026-11-02). It works in layers, cheapest first: a missing binary, a flag the CLI no longer accepts, a session that is not signed in or a CLI below the minimum version get a deterministic banner with a fix button and no AI involved. Anything else gets an AI diagnosis built from the error excerpt, the exact launch command and a flag provenance map that says which setting injected each flag, so the answer names the switch to flip instead of describing the flag in the abstract.

Where to find it

  • Above the composer of the failing agent's terminal: the setup banner ("{provider} CLI missing", "{provider} CLI out of date", the rejected-flag message, the sign-in hint) with Install, Automatic setup, Setup guide, Re-check, I already have it, Relaunch agent, CLI options or Update.

  • The AI card in the same place: Diagnose with AI (or automatic when the setting is on), then AI diagnosis with a cause line and ordered steps, each carrying at most one action (CLI options, CLI settings (the provider's own, in the Advanced settings card of its tab in Settings > AI providers), Relaunch, Install).

  • Dev command terminals: the same Diagnose with AI on a failing command, on click only.

  • Before the agent even starts: Install a CLI opens the same guided installer from the agent dialogs, in the Not installed footer of the provider picker and in the Provider panel of the Add agent window.

  • Setting: Settings > Privacy & data > Automatic AI error diagnosis.

  • In place of the terminal and the composer: the card "<CLI> isn't installed on this computer", or "<CLI> isn't installed correctly" when its files are incomplete, with Install or Reinstall, Use <another CLI>, I already have it (launch not started yet only) and Show the terminal (a launch that already failed).

How to use it

  1. Launch the agent. If the CLI is not installed, the banner says so and Install types the provider's install command into the terminal (or Automatic setup opens the guided installer). Once installed, the banner re-checks on its own when you come back to the agent (switching tabs, refocusing the window, closing the guided installer) and switches to Relaunch agent; Re-check stays available to force it.
  2. If the CLI refused a flag, the banner quotes the flag and CLI options opens the field where it was set (provider tab or the agent's own options). Remove it, relaunch.
  3. If the CLI lost its sign-in ("Login expired · Please run /login"), sign in again just once: /login in any agent it stopped, or claude auth login / codex login in a terminal tab of AgentsRoom. Every agent of the same CLI, account and machine that stopped on it gets its work back by itself. Signed in somewhere AgentsRoom cannot see (another terminal app)? Resume now on the banner does the same.
  4. If nothing deterministic matches, wait for the AI diagnosis (or click Diagnose with AI). Read the cause line ("Cause: not signed in", "Cause: model unavailable", ...), follow the steps, use the step actions. Nothing is executed for you.
  5. Copy this step hands a step to an agent or a teammate; on a dev terminal, Hand to an expert sends the diagnosis straight to a DevOps agent.

Settings

  • cliDoctorAutoEnabled (global, Settings > Privacy & data > Automatic AI error diagnosis): run the AI diagnosis automatically on a failed agent launch, sending the redacted terminal tail and launch command to the AI service; off = diagnosis on click only.
  • cliPresenceOverrides (global): your I already have it answers, per provider. A shell-proven "command not found" overrides them.

Agent tools (MCP)

None. The diagnosis is a user surface. An agent asked to fix a launch problem can read and change the flags involved with settings_get / settings_set (providerCliOptions, providerEnvVars, the project's envVars, or scope: "agent" for one agent's CLI options).

Providers

All 14 providers, plus catalogue providers such as Ollama, since the launch record is written at the single point where any terminal is created. Flag provenance knows the layers AgentsRoom itself adds: autonomous or manual mode, stored provider options, per-agent CLI override, model selection, reasoning effort, Codex Fast mode, system prompt, browser MCP denial, and the write-denial flags of a Read-only step in a team. The origin is named in the diagnosis text, not shown as a label. Deterministic verdicts cover the messages the CLIs actually print: command not found (zsh, bash, fish, Ubuntu's hint), PowerShell and cmd.exe "not recognized" including non-English Windows, unknown option, sign-in prompts, and the version floor.

Mobile

Not on the phone: the CLI, its PATH and its installation belong to the machine. One exception, the lost sign-in: the phone shows the same card on the console of each agent waiting for it, with Resume now, which asks the computer to resume the whole group (the computer also resumes them on its own as soon as it sees the sign-in succeed, including a /login typed from the phone's terminal). An agent started from the phone gets the same deterministic launch checks on the desktop. A launch from the phone is not held: it starts, fails on the shell, and the desktop pane shows the card.

Limits

  • AI diagnoses draw on the monthly AI helpers allowance: included on Free, larger on Plus, unlimited in practice on Pro; deterministic verdicts are never metered. Past the allowance, your own OpenAI key keeps them running.
  • What is sent: a redacted error excerpt, the sanitized launch command and the provenance map, only when a diagnosis is produced. System prompts, secret-looking values and long quoted arguments are removed locally; source code is never included.
  • Windows: the PATH is captured when AgentsRoom starts, so a CLI installed afterwards (or through nvm-windows, fnm, Volta) may need an app restart. Detection may say "installed" on a broken npm shim; the shell's own error then wins and raises the banner.
  • Remote SSH agents: the foreground process is the SSH client, so a remote CLI dying is not diagnosed; deterministic checks still apply remotely.
  • A late "command not found" printed by the agent itself, minutes into a session, never raises the banner: the scan is bounded to the launch window.

Common questions

  • Many agents stopped on "Login expired · Please run /login". Do I have to sign in again in each one? No, since 2026-11-03. Sign in once, in any of them (or with claude auth login in a terminal tab): AgentsRoom sees the sign-in succeed and hands every agent stopped by it its work back, with a message asking it to pick up where it stopped. The banner of each stopped agent says how many are waiting; Resume now covers a sign-in made outside AgentsRoom. An agent refused again right after an automatic resume is left to that button.
  • I installed the CLI, went back to the agent, and my message was refused. Fixed on 2026-11-02: above the composer, the agent now says "<CLI> is installed now. Relaunch the agent to run it." with a Relaunch agent button. It does not relaunch by itself.
  • The agent shows "<CLI> isn't installed on this computer" and no terminal. It was not launched, on purpose: the CLI could not be found, even after a fresh check of your PATH. Install it from the card and the agent starts by itself, with its brief intact. Use <another CLI> moves this agent to that CLI for good. If the CLI is in fact installed, I already have it launches the agent and stops the check for this CLI on this computer.
  • It says the CLI isn't installed correctly. The launcher is there but its files are not, typically an npm package without its native binary. Relaunching cannot help: Reinstall runs the installer, and the agent restarts when it succeeds.
  • Will I be told when a CLI loses its sign-in while I am away? Yes. One notification per account and machine, on the desktop and on the phone ("Signed out on <machine>. Agents waiting: n"). Tapping it on the phone opens the console of a stopped agent: type /login there, open the link on the phone, paste the code back, and every agent of that account on that machine resumes.
  • Can I sign a CLI back in on another computer of mine from here, or from my phone? Yes. A signed-out account of another machine shows in the footer Machines popover, under that machine ("Claude (Work) signed out", with the agents waiting; since 2026-11-05 an account without a name reads "Claude (Default account)", or its folder such as "Claude (~/.claude)" once another account is the default, with the login's email below when it is known, on the computer and on the phone), and on the phone above the remote agents. Sign in again brings a console of that machine on your screen: the console of a stopped agent (type /login), or, when none is left, a sign-in console that machine opens for that account (Claude Code and Codex). Open the link where you are, paste the code back if asked, and that machine resumes its agents and starts its waiting runs by itself. The credentials never leave that machine. The Machines chip turns orange while one of your machines has a signed-out account.
  • A scheduled agent ran at night on a signed-out account and got stuck. Can that be avoided? Yes, since 2026-11-03. Before a scheduled run starts, AgentsRoom checks that the sign-in of its CLI account on that machine is not known to be dead: an agent already refused, or the CLI refusing a real message. If it is, the run is not started: it waits, you get a "Waiting: <account> is signed out on <machine>" notification, and it starts on its own within a minute of the sign-in coming back. On the phone, tapping that notification opens Remote with Sign in again on that account. A trigger on a machine pool is left to another machine of the pool. A trigger with catch-up turned off still ends as missed past its 10-minute grace. Not covered yet: "Run now", webhook triggers, ticket board actions and the assistant.
  • A run waited for a sign-in while my account was signed in. Why? Fixed on 2026-11-05: an expired usage reading used to be enough, even though the account worked. Now, when a session reads as expired and the background renewal did not bring it back, AgentsRoom sends one line ("Reply with the single word: ok") to the cheapest model through that account's CLI, like a quota kick-off, with no tab. An answer proves the account is fine and renews its session, so the run starts on time. Only a refusal from the CLI itself holds the run, and it is asked again every 30 minutes while a run waits. That message counts on the account's quota like any other; a refused one costs nothing. A CLI with no one-shot form (Grok) gets no message: its run starts, and a real refusal shows on its console.
  • My agent opens and immediately drops back to a shell prompt. The CLI died at launch. Read the banner: missing binary, refused flag, sign-in, or open the AI diagnosis for the rest. Do not type prompts into that shell.
  • I typed a message in an agent whose CLI had quit and it was run as a shell command. Fixed on 2026-10-28: a send is refused instead, with "Not sent: this agent's CLI has quit and its terminal is back at the shell prompt, which would run your message as a command. Relaunch the agent, then send again. Your message is kept." Changing the model on such an agent relaunches it rather than typing into the shell.
  • It says the CLI is missing but I have it installed. The app's PATH may differ from your shell's (Windows especially, or a CLI installed after the app started). Restart AgentsRoom; if it persists, I already have it hides the filesystem verdict, and a real shell error will bring the banner back.
  • Which setting added this flag? The diagnosis names it. Typical sources: the provider tab's CLI options, the agent's own CLI options, autonomous mode, the model picker.
  • My reviewer agent says a file edit was refused. If it runs a team node with Read-only step on, that refusal is the point: the flag was added by the team, not by a setting, and the diagnosis says so. Turn the toggle off on that node if the agent is meant to write.
  • Claude vanished from my PATH overnight. A failed npm auto-update can leave the package without its claude link. AgentsRoom now recommends Anthropic's native installer, which drops a self-updating launcher in ~/.local/bin.
  • I only have Claude Code through its VS Code (or Cursor, Windsurf) extension. Does AgentsRoom find it? Yes, since 2026-10-24. The extension carries its own copy of the CLI without putting it on the PATH, so Claude used to be reported as missing. AgentsRoom now uses the copy of the newest installed extension when no standalone Claude Code is found; a standalone install always comes first. After the extension updates itself, click Re-check on the banner if it comes back.
  • I installed the CLI but the banner still says it is missing. Come back to the agent (switch tab or refocus the window): the banner re-checks by itself. It never re-checks on a project offloaded to an SSH host, where the CLI lives on the remote machine, nor right after a live launch failed while the app believed the CLI was present; click Re-check there.
  • Which OpenCode does Install give me? Since 1.184.0, OpenCode v2: the official v2 install script on macOS and Linux, the @opencode/cli npm package on Windows (OpenCode ships no PowerShell installer). Both routes drop the same opencode binary, so detection and launch are unchanged; the 1.x line is no longer offered.
  • Installing aider or Mistral Vibe failed on Windows with "the process cannot access the file". Fixed on 2026-09-27: the installer re-downloaded uv, the Python tool installer both CLIs use, on every attempt, and Windows refuses to overwrite a uv that is running. It now installs uv only when it is missing. Update AgentsRoom and retry.
  • Installing a CLI made my project and agents disappear. Fixed in 1.187.0: the Setup assistant now opens as a window above the app, the project stays open behind it. Clicking outside it does the same as its close button: during an install it only hides the window (the install keeps running behind the status-bar chip), it never cancels a running terminal.
  • The OpenCode install fails with "Version ... is not available for darwin-arm64". The vendor published that release without the build for your OS and CPU; nothing is wrong with the machine and retrying resolves the same missing version. The AI repair of the installer now says so and, when the installer takes a version, proposes the same command pinned to the previous release.
  • On my Mac the install stopped with "EACCES: permission denied" on /usr/local/bin. Fixed on 2026-10-23: the Setup assistant check npm permissions now looks at both folders npm writes to, so it reports "Global prefix ... not writable without sudo" in that case and the install goes to a folder in your home instead, no sudo needed. Open the Setup assistant again and retry.
  • On Windows the Claude Code install printed npm's help and installed nothing. Fixed on 2026-10-23: when Anthropic's official installer fails, the Setup assistant falls back to npm ("Native installer failed, trying the package registry instead"), and that fallback now really installs the package. Update AgentsRoom and retry.
  • The official installer failed on a machine without npm, then "npm not recognized". Fixed on 2026-11-07: when the Setup assistant already knows the machine has no npm, its fallback installs Node.js first, then installs the CLI through npm. The install log keeps the reason the official installer failed (on Windows, a "Native installer error: ..." line). If npm is still missing after that, the step fails with "npm is still not available. Install Node.js LTS from https://nodejs.org/en/download, then run this step again."
  • Every Grok agent fails with "grok did not start" after an update. Fixed on 2026-10-29: Grok rewrites its own config.toml when it saves a setting and drops the markers around the AgentsRoom servers, so the next launch added them a second time and Grok rejected the whole file. AgentsRoom now removes the stray copies before writing its block, which also repairs a file already in that state. Update AgentsRoom and start the agent again.
  • Can I reinstall a CLI that is already there? Yes, from the same guided installer: tick it although the list says Installed (CLI Update Notice). The lightning menu entry is Add or update providers.
  • Can I turn the automatic diagnosis off? Yes, Settings > Privacy & data. The Diagnose with AI button stays available.