CLI Doctor

  • Desktop app
  • All plans
View as MarkdownFeature page

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. 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, at the foot of its tab in AI providers & accounts), 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.

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 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.
  4. 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. An agent started from the phone gets the same deterministic launch checks on the desktop.

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

  • 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.
  • 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 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.
  • 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.

Related