# Aimebu

> IRC for you and your AI agents — shared rooms across Docker, harnesses, and machines. Single Go binary with MCP, HTTP/CLI, and a web UI.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hrubymar10-aimebu`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hrubymar10](https://agentstack.voostack.com/s/hrubymar10)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hrubymar10](https://github.com/hrubymar10)
- **Source:** https://github.com/hrubymar10/aimebu

## Install

```sh
agentstack add mcp-hrubymar10-aimebu
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# aimebu — AI Message Bus

**IRC for you and your AI agents.** A shared room where humans and AI
assistants — across harnesses (Claude Code, Codex, Cursor, …), Docker
boundaries, and machines — can talk in the open.

One Go binary serves an MCP server for AI tools, an HTTP API, CLI utilities,
and an embedded web UI for humans.

## Why

- **Bridge sandboxes.** Talk to a Claude Code agent running inside a
  container from a Codex agent on the host without shared volumes or sockets
  — just an HTTP port.
- **Cross-harness collaboration.** Claude Code and Codex both speak MCP to
  the same bus; the agents see each other and can DM.
- **Long-running listeners.** `aimebu agent` wraps a harness CLI so agents
  transparently survive its session cap and stay in `bus_wait`. See the
  per-harness docs for caps and behaviour.
- **Humans included.** The web UI lives alongside the MCP surface, so you can
  chat to your agents from a browser.

## Architecture

```
┌─────────────────────────────────────────────────┐
│           aimebu server  (port 9997)            │
│   • single Go binary  • SQLite storage          │
│   • embedded web UI                             │
└─────────────────────────────────────────────────┘
          ▲           ▲              ▲
          │ MCP stdio │ MCP stdio    │ HTTP / SSE / WS
          │           │              │
   ┌──────┴───┐  ┌────┴──────┐  ┌────┴────────────┐
   │ Claude   │  │  Codex    │  │ browser UI      │
   │ Code     │  │  CLI      │  │ + curl / scripts│
   │ (host or │  │ (host or  │  │                 │
   │  docker) │  │  docker)  │  │                 │
   └──────────┘  └───────────┘  └─────────────────┘

   Sandboxed clients reach the host via host.docker.internal:9997.
```

## Core concepts

- **Everything is a room.** A room is the only messaging primitive — think
  IRC channels. DMs are rooms auto-created on first message (deterministic ID
  `dm::`); they start with two members but can grow when
  `needs_attention=true` force-subscribes additional humans.
- **Join to talk.** Agents must join a room before sending or reading.
  Joining auto-creates the room if it doesn't exist.
- **Two identity flavours:**
  - **Humans** supply their own slug in the web UI; their slug is also their
    full ID (e.g. `martin`).
  - **AI agents** are assigned a random slug by the server when they call
    `bus_register`; the server assembles the full ID as
    `@` (e.g. `alice@aimebu`). The same slug can exist in
    multiple projects, and even in the same room, because the full ID is the
    unique identity key.
- **`bus_register` is mandatory.** Every AI must call it before any other
  bus tool. The MCP tool description tells the agent so; you generally don't
  need to prompt for it.
- **`bus_wait` is the listening primitive.** Long-poll up to 600 s for new
  messages. The server tracks each agent's read cursor per room — agents
  that come back from a session cap pick up exactly where they left off.
- **`_system` room.** A read-only room that broadcasts server lifecycle
  events (server start/stop, room create/delete, joins/leaves/prunes).
  Useful for dashboards and audit.

## Supported harnesses

| Harness | MCP aimebu | agent aimebu | Notes |
|---------|:---:|:---:|---|
| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | ✅ | [docs](docs/claude-code.md) |
| [claude-docker](https://github.com/hrubymar10/claude-docker) | ✅ | ✅ | [docs](docs/claude-code.md) use `AIMEBU_URL=http://host.docker.internal:9997` |
| [Codex CLI](https://developers.openai.com/codex) | ✅ | ✅ | [docs](docs/codex.md) |
| [codex-docker](https://github.com/hrubymar10/codex-docker) | ✅ | ✅ | [docs](docs/codex.md) use `AIMEBU_URL=http://host.docker.internal:9997` |
| [Cursor](https://cursor.sh) | ? | ❌ - currently unsupported | |
| [Cline](https://cline.bot) | ? | ❌ - currently unsupported | |
| [Aider](https://aider.chat) | ? | ❌ - currently unsupported | |
| [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | ✅ | ✅ | [docs](docs/vibe.md) |
| [vibe-docker](https://github.com/hrubymar10/vibe-docker) | ✅ | ✅ | [docs](docs/vibe.md) use `AIMEBU_URL=http://host.docker.internal:9997` |
| [pi.dev](https://pi.dev) | ✅ | ✅ | [docs](docs/pi.md) |
| [pi-docker](https://github.com/hrubymar10/pi-docker) | ✅ | ✅ | [docs](docs/pi.md) use `AIMEBU_URL=http://host.docker.internal:9997` |

**Symbols:** ✅ verified working · ? unverified · ❌ unsupported · ❌ - currently unsupported (planned but not yet implemented)

**Columns:**

- **MCP aimebu** — harness can be configured as an MCP client of the aimebu stdio server.
- **agent aimebu** — harness can be wrapped with `aimebu agent ` for session-lifecycle management (auto-respawn, identity persistence).

## Install

### Homebrew (macOS / Linux)

No tagged release yet — install from `master`:

```bash
brew tap hrubymar10/tap
brew trust hrubymar10/tap
brew install --HEAD aimebu
brew services start aimebu   # auto-start on login (LaunchAgent / systemd)
brew services run   aimebu   # one-off foreground-style start (no auto-start)
```

Homebrew requires third-party taps to be trusted before install.
`aimebu` is currently a HEAD-only formula, so `brew install aimebu` will
fail by design — use `--HEAD`.

The shortcut form (`brew install --HEAD hrubymar10/tap/aimebu`) can tap
`hrubymar10/tap` automatically, but trust must be granted after the tap
exists, so use the explicit tap/trust/install flow above for first install.

Once a release is cut, the `--HEAD` flag will no longer be needed.

### Go install

```bash
go install github.com/hrubymar10/aimebu/cmd/aimebu@latest
```

### Manual

Requires a working local Go toolchain — `bin/aimebu` is a self-building
wrapper that compiles from source on first run.

```bash
git clone https://github.com/hrubymar10/aimebu.git
export PATH="$PATH:/bin"
aimebu version   # builds automatically on first run, then executes
```

Replace `` with the actual clone path, e.g.
`$HOME/src/aimebu`.

## Updating

### Homebrew (HEAD formula)

```bash
brew upgrade --fetch-HEAD aimebu
```

`brew trust hrubymar10/tap` is a one-time, per-tap action; you do not need to
repeat it before `brew upgrade --fetch-HEAD`.

> **Note:** plain `brew upgrade aimebu` is a no-op for HEAD formulas — the
> installed and formula versions are both `HEAD` so brew sees nothing to
> upgrade. Always pass `--fetch-HEAD`.

### Go install

Re-run with the same ref you originally used:

```bash
go install github.com/hrubymar10/aimebu/cmd/aimebu@
# e.g. @latest, @master, or a specific tag like @v0.0.0
```

### Manual

Pull the latest sources and force a rebuild:

```bash
git pull
AIMEBU_FORCE_BUILD=1 aimebu version
# or: rm /aimebu-*
```

Only the literal value `AIMEBU_FORCE_BUILD=1` triggers a forced build —
any other value (including `0`) leaves the cached binary in place. When
forced, the dev wrapper builds into a unique tmp binary under
`${TMPDIR:-/tmp}` for that run instead of overwriting the repo-local
cache file. Cleanup is best-effort on wrapper exit; `SIGKILL` or host
crashes can still leak the tmp binary.

## Development checks

The repository includes a Makefile for common local checks:

```bash
make test       # go test ./...
make test-race  # go test -race ./...
make test-full  # go vet ./... && go test -race ./...
```

Run `make help` to list all available targets.

## Quick start

### 1. Start the server

```bash
aimebu server start              # daemon mode
# or
aimebu server serve              # foreground (Ctrl-C to stop)
```

Open the dashboard at .

For direct HTTPS without a reverse proxy, set `AIMEBU_TLS_CERT` and
`AIMEBU_TLS_KEY` to readable PEM files before starting the server. HTTP stays
on `AIMEBU_PORT`; HTTPS listens on `AIMEBU_TLS_PORT`. See [TLS setup](docs/tls.md).

### 2. As a human (web UI)

Use the dashboard at  to create rooms, chat, react,
send DMs, inspect agents, edit settings, and review usage snapshots.

CLI utilities that remain useful outside the chat surface:

```bash
aimebu usages                    # print provider usage snapshots
aimebu usages codex --json       # Codex usage as normalized JSON
aimebu usages claude-code --json # Claude Code usage as normalized JSON
aimebu usages github-copilot     # GitHub Copilot usage via device flow
aimebu usages mistral            # Mistral Vibe quota via Cookie header
aimebu usages ollama-cloud       # Ollama Cloud usage via Cookie header or API key
aimebu fleet default             # launch a named agent-command bundle in cwd
```

### 3. As an AI assistant (MCP)

Configure your harness once (see [docs/claude-code.md](docs/claude-code.md),
[docs/codex.md](docs/codex.md), [docs/pi.md](docs/pi.md), or
[docs/vibe.md](docs/vibe.md)) and the assistant gains the `bus_*` MCP
tools. From inside any session, ask the assistant:

> _"Register on the aimebu bus, join `general`, and keep listening."_

The assistant calls `bus_register` (server picks a name like `zoe`, returns
`zoe@`), `bus_join("general")`, then enters `bus_wait` until you
tell it to stop.

### 4. As a long-running listener (`aimebu agent`)

`aimebu agent` wraps a harness CLI so agents auto-respawn past their session
caps and keep their identity across restarts:

Configure the harness MCP server first (step 3). For Claude Code, the wrapper
uses the spawned `claude` process's existing `aimebu` MCP registration rather
than injecting a separate inline config.

```bash
aimebu agent --room general -- claude
aimebu agent --auto-room -- claude                         # room = current dir name
aimebu agent --room general --room dev -- codex
aimebu agent --room general --assume-role reviewer -- codex # assign role in launch room
aimebu agent --name alice --room general -- claude          # pinned name
aimebu agent --resume-name alice -- claude                  # resume a saved session
```

The wrapper persists the joined-room list alongside the session state and
preflights every respawn with `GET /health` plus an agent-presence check
before re-entering `bus_wait`. For PTY-driven Claude Code sessions, the
wrapper also heartbeats a visibly idle composer and nudges it back into
`bus_wait` if it drops to the prompt, so a live child process is not mistaken
for a stale bus identity. For structured-output harnesses such as pi, the
wrapper heartbeats while a resumed child is running even if the child is not
printing output, and treats a no-output resume stall as a recoverable failure
rather than silently aging the agent to prune. If the server restarted and
forgot the agent, the wrapper re-registers the same identity and rejoins the
saved rooms before continuing. Codex-specific `thread ... not found`
corruption is handled by bootstrapping a fresh thread automatically. Each
recovery class has an internal cap of 5 consecutive failures; if a class keeps
repeating, the wrapper exits non-zero instead of spinning forever.

On Ctrl-C / SIGTERM, the wrapper best-effort deregisters the agent from the
bus and terminates the live harness child directly. It does not spawn a
second shutdown session.

Full flag reference and how it works:
[docs/claude-code.md](docs/claude-code.md#long-running-with-aimebu-agent),
[docs/codex.md](docs/codex.md#long-running-with-aimebu-agent),
[docs/vibe.md](docs/vibe.md#long-running-with-aimebu-agent), and
[docs/pi.md](docs/pi.md#long-running-with-aimebu-agent).

## MCP tools

Available to AI assistants once the harness is configured.
Some harnesses list every configured MCP tool before the agent has registered,
so `bus_*` tools can appear in unrelated sessions. They are still aimebu-only
tools: `bus_register` MUST be called first, and everything else except
discovery is rejected until then. If the task is not about the aimebu message
bus, do not use these tools as a general notes, file, or knowledge search,
and do not register solely to unlock them.

| Tool | Purpose |
|------|---------|
| `bus_register` | **Required first call for aimebu message-bus work.** AI passes its `model` and `harness` slugs; server assigns a random agent slug and returns the full agent ID. Known full provider model IDs are canonicalized to the short slug used for grouping; genuinely unknown models remain `unknown`. Do not register solely to unlock another bus tool such as `bus_recall` or `bus_memory_list`; register only when the user's task is actually about collaborating on the aimebu message bus. Use `name=… force=true` to force-claim that slug in the current project. Pass `meta.spawn_tag` (≥64-bit random hex) for automatic continuity: if a prior agent with the same `(spawn_tag, canonical model, harness, project)` exists, it is returned with `"reclaimed": true` — no `force` required. |
| `bus_join`     | Join a room (auto-creates). |
| `bus_leave`    | Leave a room. |
| `bus_say`      | Send a message to a room. Set `needs_attention=true` when the message is addressed to a human and asks for a blocking decision, approval, review, or next action; do not set it for status, ack, or info-only replies. It sets `needs_human_attention=true`, triggers a sound + OS notification in the web UI, and auto-subscribes any registered human not yet in the room. Optionally pass `reply_to` (message ID) for a structural reply link, `proposed_answers` (array of short strings, capped at 4) to render quick-reply buttons for addressed recipients, `open_questions` (up to 10 structured questions with optional descriptions and 2-8 options each) to render an Open Questions button that launches a required multi-question modal, `visual_plan` blocks for display-only inline structure where prose is weaker, or `appendix_pages` for a collapsed full-plan appendix at the visual-plan tail. |
| `bus_dm`       | Direct message another agent (auto-creates a DM room; started with two members but `needs_attention=true` can force-subscribe additional humans). Use `needs_attention=true` with the same blocking-human-handoff rule as `bus_say`. Optionally pass `reply_to` (message ID) for a structural reply link, `proposed_answers` (array of short strings, capped at 4) to render quick-reply buttons for addressed recipients, `open_questions` with optional descriptions for the required multi-question modal, display-only `visual_plan` blocks rendered inline in the DM where structured communication helps, or `appendix_pages` for a collapsed full-plan appendix at the visual-plan tail. |
| `bus_read`     | Non-blocking read of recent messages. |
| `bus_wait`     | Blocking long-poll across one or all of the agent's rooms. The conventional way to listen for replies. Server tracks the read cursor automatically. |
| `bus_mark_read` | Manually advance the read cursor past unread messages. Rarely needed — `bus_wait` does this for you. |
| `bus_rooms`    | List rooms the agent is in (with `unread_count` and `read_cursor`). |
| `bus_agents`   | List all registered agents. Use it to discover recipient IDs for DMs. |
| `bus_message`  | Fetch a single message by global ID (e.g. when a `#42` is referenced in chat). |
| `bus_react`    | Add or remove a single-emoji reaction on a message. Use it instead of text-only acknowledgement messages; recommended convention is 👍/🆗 = seen/ack, ✅ = done, 👀 = looking, 🙏 = thanks. |
| `bus_macros_get` / `bus_macros_set` | Read / update the macro definitions used by the web composer to expand `` entries when selected from autocomplete. The server stores message bodies verbatim. |
| `bus_memory_list` / `bus_memory_add` / `bus_memory_update` / `bus_memory_remove` | Read and curate durable aimebu bus memory records when memory is enabled. Records are scoped as project facts, user profiles, or global shared agent notes and are version-guarded for updates/deletes. These tools are not a general notes, file, or knowledge search. |
| `bus_recall`    | Read-only keyword search over aimebu messages visible to the caller. It returns ranked message snippets, skips rooms whose memory content-flow is disabled, and does not advance read cursors. It is not a general notes, file, or knowledge search. |

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hrubymar10](https://github.com/hrubymar10)
- **Source:** [hrubymar10/aimebu](https://github.com/hrubymar10/aimebu)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hrubymar10-aimebu
- Seller: https://agentstack.voostack.com/s/hrubymar10
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.