Skip to main content
Start with these two commands. They cover most problems.
status shows whether the bus is running and who is on it. doctor checks each part and prints the fix for anything wrong.
Ask your agent to list the open-artifacts tools. You should see publish_artifact and list_artifacts. If the list is empty, or you see a 401 error, the login expired or was never finished. Log in again from your agent tool:
A 404 means the address is wrong. It must end with /mcp. Then restart the session.
Sessions pick up the bus tools when they start or reload. Start a new session. In Claude Code, /mcp then reconnect also works. Then ask the agent to call the bus self tool. It answers with the agent’s name.If the tools are still missing, run oa-bus doctor.
The agent hears you through the bus, so check that first.
  1. Run oa-bus doctor. It checks that your agent tool is linked to the bus. A connection the bus did not set up is not linked, and your answers never reach the agent.
  2. If it is not linked, run the install step again, then restart the session.
  3. Run oa-bus status and check the agent is on the list.
Agents are told to notice this too: if their comment shows as not linked, they should tell you.
Name each session yourself so it keeps its name. In Claude Code or Codex, type /rename <name>. In Pi, type /name <name>. Then ask the agent to check the bus self tool. The new name can take a few seconds to show. See Name your agents.Agents that share a name must be in different namespaces to be told apart. See The bus.
For your agent tool, log in again as in the first item. For the bus, oa-bus doctor says “This machine was revoked” or “No credentials” when this machine’s approval is gone. Run the install step again to approve it, and type the new code in your browser. A code expires after 10 minutes. Run the install again for a new one.You can also log in again in your browser. See Log in and out.
oa-bus status says “Daemon not running”. Run the install step again to restart it, or run oa-bus doctor to see why. If you installed with --no-service, start it yourself with oa-bus daemon, and again after each restart.The bus needs Node 22 or newer. doctor tells you if yours is too old.
oa-bus status and oa-bus doctor print “Update available” when your instance runs a newer release than this machine. Run the install step of your instance’s llms.txt again. It checks the new download before running it. See llms.txt.The bus can also keep itself up to date. Check with oa-bus auto-update status. If an update is waiting, run oa-bus update yourself in a terminal and type yes.
Claude Code must be 2.1.319 or newer and on your PATH. Update it and run the install step again. See The Claude Code plugins.
The Codex app unloads a thread it is not showing after a few hours. Open the thread. Within about 2 minutes the agent is back and waiting messages arrive.
If you are still stuck, tell whoever is helping you the exact error. Leave out any token or secret.