Agents won't start or respond

Work down this list — it’s ordered by how often each cause is the culprit: the CLI isn’t installed, the CLI isn’t signed in, the key isn’t set (or a stale window is running), or the task hit an error the transcript explains.

The window says the CLI isn’t available

Cause: the agent’s binary isn’t installed or isn’t on your PATH.

1. Open Settings → Agents — the detection list shows every brand with found/not-found and an Install hint.
2. Install the CLI (each brand’s official installer), then click Scan again.
3. Open a new agent window of that brand.

The agent replies with a login/authentication error

Cause: the CLI isn’t signed in and no API key is set.

1. Easiest: click Sign in in the agent’s header. It opens a console already running that CLI’s login command — complete the sign-in there, then re-send. It has to be a real console window rather than a Terminal pane, because the sign-in is interactive and a pane can’t type into it.
2. Or set its API key in Settings → Agents → Agent API keys (.env), click Recheck keys, and open a fresh agent window. (Key guide)
3. The transcript shows the exact login instruction for the brand when this happens — follow it verbatim.

An agent that was working suddenly stops with an authentication error

Cause: the CLI’s sign-in expired part-way through a session. Claude reports this as “OAuth token has expired” or “OAuth session expired and could not be refreshed”.

This is different from never having signed in, and Mastery HQ says so — the message names the expiry rather than claiming you were never signed in. The Sign in button reappears in the agent’s header the moment it happens, and disappears again once a run succeeds.

Sign in again with that button and re-send. If you have a second account configured for that brand and it’s still signed in, Mastery HQ switches to it automatically and re-runs, telling you it did.

Worth knowing: an expired sign-in also stops loops and graphs using that agent — including their judge, which is why a graph can finish all its stages and still report no score.

I added a key but the agent still fails

Cause: running windows keep their original environment.

1. Close the agent window and open a new one — new windows pick up the current .env.
2. Check for a project-level .env in the workspace folder overriding your global keys.

The run starts, then exits immediately with a code

Cause: the task itself errored — the CLI’s message is in the transcript just above Process exited.

1. Read the last lines before the exit; they name the problem (rate limit, invalid flag, network).
2. Retry once; if it persists, run the same prompt in that CLI directly in a terminal to see its full output.

OpenCode says “API key is missing”

Cause: OpenCode’s default model is a Google one, and it reads that key under a different name (GOOGLE_GENERATIVE_AI_API_KEY) from the GEMINI_API_KEY the rest of Mastery HQ uses.

Since v0.1.137 the app forwards your Gemini key under both names, so pasting one key into Settings → Agents is enough. If you’re still seeing it:

1. Confirm a non-empty GEMINI_API_KEY in Settings → Agents, then open a new agent window — windows pick up keys at launch.
2. Or pick a different model on that window, for a provider you already have a key or a login for.

Nothing happens at all when I press Send

1. Confirm you’re in the desktop app (agents require it — the browser preview can’t spawn processes).
2. Check who’s working — if the agent is mid-run, new input waits its turn; Stop first to interrupt.

Still stuck?

Export the transcript (Export button) and send it via Feedback with the agent brand and what you expected.