AI app connection troubleshooting
Use this article when your AI app cannot use AgentZ. The first headings are what your AI app tells you; the later ones are what the AgentZ app shows on Settings > AI apps. How to connect an AI app is described in Connecting your AI app.
Your AI app says it cannot reach the AgentZ desktop app
Section titled “Your AI app says it cannot reach the AgentZ desktop app”The AI app’s AgentZ plugin cannot reach the AgentZ app on this computer: AgentZ is not running, is showing its sign-in screen, or is restarting, for example while it installs an update.
Check the following:
- The AgentZ app is open. Open it if it is not.
- The AgentZ app is signed in. If it shows its sign-in screen, sign in with the link AgentZ emails you. See Signing in to AgentZ.
If AgentZ is open and signed in, reopen your AI app, so that it starts a fresh AgentZ connection. Reopen to finish updating gives the steps for each AI app. Closing the Claude desktop app’s window is not enough.
Your AI app says AgentZ is signed out
Section titled “Your AI app says AgentZ is signed out”“AgentZ is signed out on this computer, so it cannot supply an iMIS token”, or the licence has ended or is paused. Open the AgentZ app and read the note on its sign-in screen. See AgentZ sign-in troubleshooting.
Your AI app says AgentZ has no saved Staff sign-in or API connection for this iMIS site
Section titled “Your AI app says AgentZ has no saved Staff sign-in or API connection for this iMIS site”AgentZ is connected, but cannot get access to your iMIS site because a set-up step is not done.
Open the AgentZ app, go to Settings > Overview, and finish the iMIS sign-in and iMIS API checks. If iMIS API shows Waiting for your Organisation admin, your Organisation admin sets it up. See Checking your setup.
Your AI app says iMIS did not accept the username and password saved in AgentZ
Section titled “Your AI app says iMIS did not accept the username and password saved in AgentZ”Save your current iMIS password in AgentZ. See Password not accepted.
Your AI app says AgentZ switched to another iMIS site
Section titled “Your AI app says AgentZ switched to another iMIS site”Someone switched AgentZ to another iMIS site, on the iMIS sites tab or the iMIS tab. AgentZ gets access to the new site by itself once that site’s iMIS sign-in and iMIS API connection are set up. Wait a minute and ask again. See Adding another iMIS site.
Your AI app says AgentZ’s iMIS token expired and AgentZ is getting a new one
Section titled “Your AI app says AgentZ’s iMIS token expired and AgentZ is getting a new one”AgentZ renews its access to iMIS by itself. Wait a minute, then ask again.
Your AI app says AgentZ on this computer was updated after it started this AgentZ connection
Section titled “Your AI app says AgentZ on this computer was updated after it started this AgentZ connection”The AgentZ app updated while your AI app was open, and the AI app is still running the AgentZ plugin it started before. It will not recover by itself. Reopen the AI app as described under Reopen to finish updating.
Your AI app says AgentZ could not reach the AgentZ service over the internet
Section titled “Your AI app says AgentZ could not reach the AgentZ service over the internet”Check this computer’s internet connection, and your VPN if you use one. AgentZ tries again by itself every few minutes.
Your AI app says AgentZ refused the connection because too many agent sessions are connected
Section titled “Your AI app says AgentZ refused the connection because too many agent sessions are connected”Close AI app sessions that are not in use, or quit the AgentZ app and open it again.
The card says Not found on this computer
Section titled “The card says Not found on this computer”AgentZ did not find that AI app in the places it is normally installed.
Check the following:
- The app is installed for your user account on this computer.
- For the Claude desktop app’s Code tab: the Claude Code (command line) card is for the separate
claudecommand. It can say Not found on this computer while the Claude desktop app’s Code tab uses AgentZ normally. Look at the Claude desktop app card instead.
The card says Not set up
Section titled “The card says Not set up”The AI app is on this computer, but AgentZ is not in it yet. Follow the steps on its card. See Connecting your AI app.
For OpenCode, GitHub Copilot, Grok Build and Devin, AgentZ adds itself. If the card says AgentZ was taken out of the app, AgentZ does not add it again on its own: choose Update now to add it back.
The card says Turn on the bridge
Section titled “The card says Turn on the bridge”On Windows, Grok Build cannot start AgentZ from its plugin. Turn on the Desktop Apps Bridge on its card. Codex and Hermes Agent also need the bridge.
The card says Update to connect
Section titled “The card says Update to connect”The AI app has an older AgentZ plugin that cannot connect to this app. Update the plugin in that app, then reopen it. The card names exactly what to do. See Plugin update troubleshooting.
Settings > Overview says No AI app found
Section titled “Settings > Overview says No AI app found”“AgentZ works inside an AI app such as Claude. Install one on this computer, then add AgentZ to it.” AgentZ works with Claude Code (command line), Claude desktop app, Codex, OpenCode, GitHub Copilot, Cursor, Grok Build, Devin and Hermes Agent.
Claude’s Chat does not use AgentZ
Section titled “Claude’s Chat does not use AgentZ”To use AgentZ in Claude’s Chat, and see its result views there, turn on the Desktop Apps Bridge on the Claude desktop app card. Cowork and the Code tab do not need it.
Does my AI app need the AgentZ app open? Yes. The AgentZ plugin works through the AgentZ app on the same computer.
I share this computer with someone else who uses AgentZ. Whose AgentZ do my AI apps use? Your own. Each person signs in to the computer with their own account and runs their own AgentZ app, and each person’s AI apps connect to their own AgentZ through a connection of their own. Keep the AgentZ plugin in each AI app up to date: an older plugin can only use the one connection the computer shares, which only one person’s AgentZ can offer at a time. To set up the iMIS API connection, close the other person’s AgentZ first: set-up says “OAuth callback listener is not available” while it is open.
The sidebar shows AgentZ plugin with an amber dot, but Settings says Everything is working. Is something wrong? Go by Settings > Overview and the AI apps tab, which check each AI app.
Where can I read how my AI app connects to AgentZ? See The connection between your AI app and AgentZ.

