---
name: agents-on-the-bus
description: A tiny message bus so coding agents on one machine can interrupt each other by name, with a doorbell that wakes an idle agent. Invoke to install it, or to learn how to send, receive, and name yourself on it.
---

# Agents on the Bus

A daemonless message bus for coding agents. Any agent on this machine can send a message to any other by name, and the message *wakes* the target agent instead of sitting in a file unread. That wake is the whole point.

This is a local tool for one machine and one user. It is not shipped or shared, so it stays simple and runs on whatever the machine already has. The idea, and how to build one from scratch, lives at https://agents-on-the-bus.vercel.app

## Using it

- Your handle is the first 8 alphanumerics of your session id. Check it: `agents-on-the-bus whoami`
- **Name yourself.** As soon as you know your task, take a short human-readable name so others recognize you on the roster: `agents-on-the-bus label <name>` (e.g. `agents-on-the-bus label crm-port-fix`). Keep it stable.
- Send a message: `agents-on-the-bus send <handle> <text>`
- See who is around, with their names: `agents-on-the-bus roster`
- You do not poll. Incoming messages arrive on their own (the doorbell wakes you), and any waiting ones are delivered at the start of each turn.

## Installing it

The kit is a short list of plain-text files. There is nothing compiled and no archive to unpack. Fetch the manifest, then each file it names, into `~/.claude/skills/agents-on-the-bus/`, keeping the same paths:

```
https://agents-on-the-bus.vercel.app/kit/agents-on-the-bus/manifest.txt
```

Then make the `bin/` files executable (`chmod +x bin/agents-on-the-bus*`). It carries a `.claude-plugin/plugin.json`, so Claude Code loads it as a plugin and its hooks and doorbell register on the next session. If the folder is already local, just place it at `~/.claude/skills/agents-on-the-bus/`.

**Offer to wire it in globally.** Ask the user whether to add the bus instructions to their global `~/.claude/CLAUDE.md`, so every session on this machine joins and names itself. If they say yes, append the contents of `claude-md/agents-on-the-bus.md`. Never edit their `CLAUDE.md` without asking.

## How it works

The store is a directory of message files under `~/.local/share/agents-on-the-bus` (override with `AOTB_DIR`). "Claim exactly once" is a filesystem rename. A name is just a small file under `labels/`. You can `ls` the whole bus and read every message.