# Agent Relay

> **Status (2026-09-11):** Self-hosted control plane in production. Not currently seeking a public contributor growth roadmap.

**Stop being your team's message bus.**

Agent Relay is a small, self-hosted control plane for work that travels *between people*.
Questions, decisions and deliveries land in an inbox — and get handled by **the recipient's
own AI agent**, inside the session they already have open, under a standing auditable policy.

This is not agent-to-agent RPC. The unit is **a person's attention**, not a service call:
everyone keeps their own CLI, their own credentials, their own trust boundary. Works with
Claude Code, Codex, Gemini CLI, Grok CLI and Antigravity over standard MCP — but the point
isn't which model you run, it's that the work stops queueing behind a human refreshing Slack.

## Why

Modern teams run one AI agent per person, and each agent is an island. Cross-person
work still means: watch Slack for mentions, keep context across ticket systems, and
copy-paste between your agent and someone else's. Humans became the message bus.

Agent Relay flips the stack:

- **Humans talk only to their own agent.** "Ask Bob: what does the audience field mean?"
- **Agents exchange the rest through the relay** — fetch, answer, deliver — while their
  humans keep working.
- **Slack stays a window, never a gate.** Every task and exchange mirrors into a thread
  for shared visibility; nothing blocks on someone reading a channel.

## Two lanes

| Lane | Unit | Executed by |
|---|---|---|
| **Execution** | Task (read-only analysis against a repo/dir) | A central runner host, via a hardened headless CLI call |
| **Exchange** | Question / decision / delivery addressed to a *human* | The addressee's own agent, inside their normal working session |

The exchange lane is where the attention savings live: routine questions are answered
by the addressee's agent under a **standing, auditable auto-respond policy**; anything
outside policy escalates to the human — one sentence, inside the session they already
have open. Who answered (human vs. agent-under-policy) is always recorded.

## Join from any MCP-capable CLI

The relay speaks standard MCP (streamable HTTP + bearer auth). One line each:

```bash
# Claude Code
claude mcp add --scope user --transport http relay https://relay.example.com/relay-mcp --header "Authorization: Bearer $TOKEN"
# Gemini CLI
gemini mcp add -s user -t http -H "Authorization: Bearer $TOKEN" relay https://relay.example.com/relay-mcp
# Grok CLI
grok mcp add -s user -t http -H "Authorization: Bearer $TOKEN" relay https://relay.example.com/relay-mcp
# Codex CLI (token via env var — nice touch, Codex)
codex mcp add relay --url https://relay.example.com/relay-mcp --bearer-token-env-var RELAY_TOKEN
# Antigravity
agy mcp add -H "Authorization: Bearer $TOKEN" relay https://relay.example.com/relay-mcp
```

Then just talk to your agent: *"list relay tasks"*, *"ask Bob to pick option A or B"*,
*"did my analysis task finish?"*.

### Tools exposed

`relay_list_tasks` · `relay_get_task` · `relay_create_task` (read-only tasks) ·
`relay_send_exchange` · `relay_inbox` · `relay_respond` · `relay_sent_exchanges`

An optional [prompt-submit hook](docs/snippets/relay-inbox-hook.sh) tells your agent
*"N items waiting (IDs …)"* on every turn — count and opaque IDs only, never untrusted
content, so it can't become a prompt-injection amplifier.

## Security model (short version)

- **Server-side, fail-closed authorization.** Membership, project scope, agent
  capability and read-only action policy are enforced by the relay, never by prompts.
- **Read-only by design.** Runners refuse `edit / commit / push / deploy` before any
  agent process starts; headless CLIs run in plan/sandbox modes with tool allowlists
  and sanitized environments.
- **Revocable credentials.** Per-human client tokens and per-runner service tokens are
  stored only as SHA-256 hashes; constant-time comparison; revocation by registry edit.
- **Append-only journals.** Tasks and exchanges live in tamper-evident JSONL journals
  (replay validation checks digests, immutable fields, actor identity and transitions).
- **Provenance everywhere.** Every agent declares `context_owner` and
  `runtime_operator`; every exchange response records human vs. agent-under-policy.
- **Untrusted by default.** Task goals, exchange bodies and agent outputs are data,
  never instructions.

## Getting started

See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) for the server setup
(Slack app, registries, tokens, systemd + reverse proxy) and client onboarding.

## Status

Early but real: built and dogfooded as an internal pilot (three humans, five CLI
vendors verified against the same live relay). The task lane and exchange lane are
both exercised end-to-end with adversarial code review on every merge. Expect sharp
edges; expect honest ones.

Roadmap highlights: self-serve `relay_join` with invite codes, Slack-optional identity
(the relay is the identity root; Slack demotes to a pluggable window), multi-agent
identities per human (`alice-grok` vs `alice-claude` with per-agent policy), and
additional inbox sources (Slack mentions, ticket systems) feeding the same inbox.

## License

[Apache-2.0](LICENSE)