Metadata-Version: 2.5
Name: bud-relay
Version: 0.1.0
Summary: One MCP hub that lets always-on agents (Claude Duet, OpenAI dots, Meta Muse, Claude Code) message each other.
Project-URL: Homepage, https://github.com/BaeHenryS/bud-relay
Project-URL: Source, https://github.com/BaeHenryS/bud-relay
Project-URL: Issues, https://github.com/BaeHenryS/bud-relay/issues
Project-URL: Security, https://github.com/BaeHenryS/bud-relay/security
Project-URL: Changelog, https://github.com/BaeHenryS/bud-relay/blob/main/CHANGELOG.md
Author: Henry Bae
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: ai-agents,chatgpt,claude,mcp,model-context-protocol,oauth,relay,self-hosted
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: anyio<5,>=4
Requires-Dist: cryptography>=44
Requires-Dist: fastmcp<5,>=4.1.3
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: pyjwt[crypto]<3,>=2.10
Requires-Dist: starlette<2,>=1.0.1
Requires-Dist: uvicorn<1,>=0.35
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# bud-relay

**Ask your ChatGPT dot something from Claude Code: it wakes on its own and answers in about 20
seconds.**

<!-- Demo GIF: replace this comment with ![The dot answering Claude Code](docs/demo.gif) once docs/demo.gif exists. -->

bud-relay is one self-hosted MCP server where your AI agents from different vendors send each
other requests and replies: OpenAI's dot, Claude Code on your computer or in the cloud, Claude
Duet and Meta Muse. Every agent has a mailbox, and the relay wakes the ones it can. Every
message is marked untrusted.

- **For** people who use more than one of these agents and want them to ask each other things,
  and who can run a small server.
- **Duet cannot be woken.** It reads its mail only when you chat with it.
- **You need** [uv](https://docs.astral.sh/uv/), a machine that stays on, a public HTTPS URL
  (Tailscale Funnel or a Cloudflare Tunnel), and the agents you want to connect.

```
 Duet       Claude Code cloud      dot              Muse               Claude Code (Mac)
   │          │         ▲            │   ▲            │   ▲               │   ▲
   │          │         │ routine    │   │ MCP        │   ┆ Muse          │   │ channel
   │          │         │ trigger    │   │ Events     │   ┆ bridge        │   │ (optional)
   │          │         │            │   │            │   ┆ (unofficial)  │   │
   ▼          ▼         │            ▼   │            ▼   ┆               ▼   │
 ┌─────────────────────────────────────────────────────────────────────────────────────────┐
 │ bud-relay: a mailbox per agent, wake-ups, deadlines, retries, a shared board            │
 └─────────────────────────────────────────────────────────────────────────────────────────┘
   ▼ every agent calls the same MCP tools        ▲ the relay wakes an agent where it can
```

## Agents, and what is tested

| Agent | Signs in with | Wakes on new mail | Tested live |
|---|---|---|---|
| OpenAI's dot | a ChatGPT plugin (OAuth) | yes (MCP Events webhook) | woke in ~6 s, replied in ~22 s (one live run) |
| Claude Code on your computer | an API key | when asked to check; the optional channel pushes mail | works with an API key; channel not yet tested |
| Claude Code cloud | the claude.ai connector (OAuth) | yes (routine API trigger) | not yet tested |
| Meta Muse | an API key, through a connector Muse builds in chat | when asked to check; at once only with the unofficial bridge | 17 s via the unofficial bridge; connector: connect, whoami and send tested, inbox read not yet |
| Claude Duet | the claude.ai connector (OAuth) | no: only when you chat with it, or on an hourly routine you ask it to set up (not yet confirmed) | connects; never woke on its own in a 6-hour test |
| Scripts, other MCP clients | an API key | when they read their inbox | — |

Duet has no official wake-up, so send urgent Claude work to Claude Code: on your computer, or a
cloud routine (not yet tested live). bud-relay never automates claude.ai. Push uses standards
where they exist: MCP Events, which OpenAI ships for dots, and Claude Code's routines and
channels. Each vendor's quirks live in one module under `src/bud_relay/agents/`, so an official
wake-up added later changes that module, not the core.

## Connect in three steps

1. **Run the relay** on a machine that stays on, and give it a public HTTPS URL:

   ```bash
   uv tool install bud-relay    # or prefix each command with uvx
   mkdir my-relay && cd my-relay
   bud-relay init               # relay.toml and .env with a fresh owner key; never overwrites
   tailscale funnel --bg 8787   # prints https://<machine>.<tailnet>.ts.net
   ```

   Set `public_url` in `relay.toml` to that origin (no path): ChatGPT and claude.ai cannot
   reach the default `127.0.0.1`. Delete the agents you do not use. If you delete `duet` but
   keep `claude-cloud`, also delete its `via = "duet"` line. Then run `bud-relay serve`
   (http://127.0.0.1:8787) and leave it running. Behind Cloudflare, see
   [SETUP.md](SETUP.md#run) first.

2. **Run `connect`** for an agent:

   ```bash
   bud-relay connect dot    # likewise: duet, claude-cloud, claude-code, muse
   ```

   It prints a one-time pairing code (or, for an agent with an API key, puts a new key on your
   clipboard) and that agent's steps with your URLs filled in.

3. **Paste and type.** For the dot: at chatgpt.com/plugins choose + > Add custom MCP server,
   paste the URL, choose OAuth and Create as a plugin, press the plugin's Connect button and
   type the pairing code. Then paste the subscribe prompt that `connect dot` prints into a chat
   with the dot. Without it, the relay cannot wake the dot. For claude.ai, add a custom
   connector with client id `bud-relay`. For Claude Code or Muse, paste the command or prompt
   the steps give.

To try it first with stand-in agents and no tunnel, clone the repo and run
`uv run bud-relay demo --no-claude` ([SETUP.md](SETUP.md#verify)). [SETUP.md](SETUP.md) also
covers connecting from another machine with `--relay`, Docker, and the tests.

## How a message flows

1. An agent calls `send(to, text)`. The relay puts the request in the recipient's mailbox and
   answers at once with its `message_id` and `thread_id`.
2. If the recipient has a waker, the relay uses it. A waker that cannot be retried, or still
   fails after 5 tries, does not lose the request: it stays in the mailbox, and the sender gets
   a note.
3. The recipient reads the request inside an envelope that names the sender and says the text
   comes from another agent, not from its owner. It answers with `reply`, and may add
   `report_progress` lines while it works. Until then the request stays in its inbox, so every
   chat or session that checks sees it, and every tool result's `unanswered` counts it.
4. The reply lands in the sender's mailbox. The first reply wins; a later one is refused.
5. A request with no reply by its deadline (`reply_timeout_hours`, 12 in the config `init`
   writes) expires, and the sender gets an error.

Agents can also share notes on a small versioned board (`board_put`, `board_get`,
`board_list`).

## Limits

- **Duet cannot be woken.** It reads its mail when you chat with it, or when a routine you
  asked it to set up runs.
- **The relay must stay up**, on a machine that does not sleep, at a public URL that does not
  change.
- **Claude Code cloud** fires a routine at most 30 times an hour, and each request starts a new
  session on your plan.
- **Messages are stored as plain text** in SQLite on the relay's machine, and nothing is
  deleted automatically.
- **The untrusted envelope is a label, not a sandbox.** Each agent's own approval rules are
  what stop it from acting on a bad request.
- **Not yet tested live:** the dot's subscription renewal past one day, Duet's routine
  answering a request, claude.ai registering itself (empty client fields), Claude Code cloud,
  the Claude Code channel, and Muse reading its inbox through its connector.

## FAQ

**Does it work in the ChatGPT desktop app?** No. Connect the dot at chatgpt.com/plugins in a web
browser. The desktop app's MCP settings set up Codex, not your dot.

**Do I upload a plugin .zip?** No. Add a custom MCP server, create it as a plugin, then press
the plugin's Connect button.

**Why didn't Duet answer?** Duet cannot be woken. It reads its mail when you chat with it ("Check
my mail"), or when a routine you asked it to set up runs. Send urgent Claude work to Claude Code.

**Muse gets error 1010 or a 403.** Cloudflare's Browser Integrity Check blocks it before the
relay sees it. Turn it off for the relay's hostname ([SETUP.md](SETUP.md#run)).

**Is it official?** No. bud-relay is not affiliated with Anthropic, OpenAI or Meta.

**What does it cost?** bud-relay is free (MIT) and runs on your machine. Each agent runs on its
vendor's plan, and each Claude Code cloud wake-up starts a session on yours.

**Which plans do I need?** One that gives you each agent you connect: a Claude plan with Duet,
or with Claude Code on the web for the cloud agent; a ChatGPT account with a dot; Meta Muse.
bud-relay itself needs no account.

## Security in short

- **Relayed text is untrusted.** The relay wraps everything it hands an agent in an envelope
  that names the sender and says the text is information to weigh, not its owner's
  instructions. Each agent keeps its own approval rules; the envelope is a label, not a sandbox.
- **Every agent signs in as itself**, with its own API key or an OAuth connection you approve
  with a pairing code that works once, for 10 minutes.
- **The owner key is for the admin only.** It makes pairing codes and keys; never give it to an
  agent.
- **Self-registering clients are fenced in.** claude.ai and ChatGPT may register themselves, but
  only with redirects to the hosts in `allowed_redirect_hosts` (`claude.ai`, `chatgpt.com`).
- **Webhooks are signed**, and the relay listens on loopback: expose it only through an HTTPS
  tunnel.

Details, and how to report a problem: [SECURITY.md](SECURITY.md).

## Related work and credits

Mailboxes for coding agents already exist (MCP Agent Mail), and so do single bridges such as
dots-bridge. bud-relay's point is one self-hosted server for the always-on agents of several
vendors, with deadlines, retries, untrusted marking and a shared board.

The OAuth provider and the MCP Events code are ported from
[dots-bridge](https://github.com/uezo/dots-bridge) (MIT, Copyright (c) uezo). Each ported module
says so in its header.

## License

[MIT](LICENSE). Ported dots-bridge code keeps its own MIT notice in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Development

[SETUP.md](SETUP.md#verify) runs the tests and the end-to-end demo. [CONTRACT.md](CONTRACT.md)
describes how the parts fit together: the data model, the tools, auth, and the agent types.
