Agents bus

The agents bus is the channel through which agents in the app's terminals, and the chats, list each other, exchange messages and wait for each other while the app runs. It lives in krad-agents and exists only while the app runs, so there is still no daemon.

TransportCopy Anchor Link

• The app listens on a TCP port of 127.0.0.1, picked by the system.
• Each request is one line of JSON: an envelope with the token, the caller and the request. The answer is one line of JSON back.
• The only guard is a random token created for each run of the app. Any process of your user that can read a terminal's environment variables can therefore use the bus.

Every terminal and chat process the app starts gets three environment variables, with the app's folder first on PATH:

A lead gets a token of its own, separate from the one other terminals get.

The CLICopy Anchor Link

Agents call the bus from their shell with krad-ade-agents. Run with no arguments, it prints its guide.

krad-ade-agents <list|send|check|wait|read|spawn|code|help> [args] [--json]

--json prints the raw response. Waits are capped at 30 minutes. The exit code is 0 on success, 1 for a usage error and 2 when the bus fails or refuses the request; run outside a Krad ADE terminal, the CLI says so and exits with 2.

The binary has internal commands too: hook, ask and statusline, which hooks call, and mcp, which serves code tools as a stdio MCP server.

Mailbox and noticesCopy Anchor Link

Each environment has one mailbox where messages wait. If the recipient sits idle at its prompt, the app types a short line into it that points it at krad-ade-agents check. Claude Code also learns about the bus from text the app appends to its system prompt; the other harnesses discover it from that typed line and from krad-ade-agents help.

The lead on the busCopy Anchor Link

A lead's chat acts for you, not as a peer agent:

• send from a lead gives the Worker the text as its next message, as you would, instead of posting to a mailbox; a closed Worker reopens with its conversation to take it;
• spawn starts the Worker as a chat in a session of its own and prints its id once it has started, or the error that stopped it;
• read returns the end of the Worker's conversation, and reading a Worker that has finished closes it;
• the bus checks the lead's own token, so a request with another terminal's token cannot act as a lead.

See Lead and Workers.

Agent state from hooksCopy Anchor Link

Every hook calls krad-ade-agents hook <harness>, and the app turns the report into one of the agent states: working, waiting for input or done. Claude Code receives its hook settings on its command line when the app starts it, Codex runs its notify program at the end of each turn, and opencode reports through a status plugin. Hook events include a prompt submitted, a tool run, a permission asked and a turn finished. The Done state lasts until you look at the agent.

Code toolsCopy Anchor Link

The app adds krad-ade-agents mcp as an MCP server to each Claude Code, Codex, opencode and Gateway agent it starts. It does this at launch, in whatever way the harness accepts, and leaves your global and project config files alone. A code tool request goes over the bus to the app, and the app answers it with the language server for that file, which it starts if needed. Tools that change code only edit files inside the group root or worktree of the agent that called them.

Remote hostsCopy Anchor Link

For a remote host, the control connection opens an ssh -R forward: a loopback port on the host that leads back to the bus on this computer. Remote agents get that port in KRAD_ADE_ENDPOINT. Every request still has to carry the token, so other people logged in to the same host cannot use the bus. When the connection drops, the tunnel goes with it, and so do the agents that relied on it.