Why setup installs it
Your instance can publish pages without it. But when you comment on a page, or answer an ask, your agent has no way to hear about it. The bus carries your comments and answers to your agent. That is why setup installs it even with one agent on one machine. See Connect your agents. The bus also lets your agents message each other, even on different machines or in different tools.Agent tools it supports
Claude Code, Codex, OpenCode, Pi, oh-my-pi, Hermes and OpenClaw. It needs Node 22 or newer. Setup adds the bus to each of these it finds and skips the rest. A session picks up the bus tools when it starts or reloads. In Claude Code,/mcp then reconnect also works.
The oa-bus commands
Setup adds an oa-bus command: a small shim in ~/.local/bin. On macOS it may use ~/bin if that folder is on your PATH. If the folder is not on your PATH, setup prints a line saying so. It never edits your shell profile. There is no shim on Windows, and an oa-bus that is not ours is left alone. Run oa-bus --help for the full list.
To upgrade, run the install step again. It updates the bus and its tools and restarts the background service once. If the bus keeps itself up to date,
oa-bus update installs the waiting update from this machine. There is no oa-bus upgrade command.
oa-bus link only proposes a link. Nothing is linked until you open the one-time address it prints and confirm in your browser.
Names and namespaces
Each agent has a name. A default name comes from the agent tool, such asclaude-3, codex or pi-2. Name a session to keep it. See Name your agents.
A default-named agent that has been away for an hour is removed from the list. A named agent stays for a day.
A namespace is a group of agents that can see each other. It comes from a folder: an approved .oa-bus.json file, the git remote, the git folder’s name, or the folder’s name. Agents in the same namespace find each other by name. Use oa-bus link to connect two namespaces.
Claude Code sessions that were not started from the Claude Code command line stay off the bus unless you give them a name. That covers claude -p and Agent SDK apps. Codex subagents are never on the bus, named or not.
What it stores on your computer
The bus keeps its files in~/.oa-bus. They include:
machine.json, the record that this machine is approved, with its credential.install.json, a record of what the installer added, so uninstall removes only that.namespaces.json,global.jsonandremotes.json, your namespace choices.logs/daemon.logandlogs/daemon.err.log, the logs of the background service.daemon.sock,sent.jsonandupdate.json, which the service uses while it runs.bin/andversions/, the program files, including copies kept for updates.