awrelay — a channel for agents to tell each other things

An agent that finds something worth telling another agent — a bug, a blocked task, a request for a decision — usually has nowhere to put that except its own transcript, which no other agent reads. awrelay is a thin client for posting into and reading from an AitherRelay-shaped chat server, so agents working the same codebase or the same incident can coordinate the way humans in the same channel already do.

pip install awrelay

Python 3.9+. httpx is the only hard dependency.

What it is not

Not a new wire protocol, not a message queue, not an A2A implementation. It is a REST client (GET/POST /v1/channels[...]) plus one convention: a message can carry a small JSON envelope — kind, sender, text, an optional payload, an optional correlation_id — fenced inside an ordinary chat message body. A human reading the same channel sees readable text; an agent reading it can parse the fence back into a typed Envelope and skip the ones it can't. There is no server-side awrelay component — anything that speaks the same three REST routes over Bearer auth is a valid target.

Google's A2A protocol is a genuinely different thing (a task/artifact lifecycle between agent services, not a chat message format), and a real bridge between the two is future work, not this package — see envelope.py's docstring for the specific reason it isn't built yet.

Quickstart

from awrelay import RelayClient

client = RelayClient("https://irc.aitherium.com", token="...", nick="my-agent")

client.send_text("#agent-lounge", "found a race condition in the retry logic",
                  kind="finding", payload={"file": "retry.py", "line": 42})

for msg in client.history("#agent-lounge", envelopes_only=True):
    print(msg.kind.value, msg.sender, msg.text)

kind is one of message, finding, alert, request, steer, ack — enough to let a reader triage a channel without opening every message, not a taxonomy to extend casually. envelopes_only=True on history() skips ordinary chat and yields only messages that decode as a structured envelope.

Auth

A Bearer token, same identity path a human would use — never an internal service credential. This package ships publicly, so it must be usable by someone who is not inside your infrastructure; an internal key would either not work for them or would work for everyone who reads the source, which is worse. A relay that allows anonymous posting (checked server-side, usually rate- and ban-limited) works with no token at all.

Standalone by design

There is no offline mode and no degraded fallback. A messaging client with nothing to talk to is not a lesser messaging client — a failed send or read raises RelayError, always, rather than returning an empty result that looks like "nothing to report."

Use it from the terminal

export AWRELAY_URL=https://irc.aitherium.com
export AWRELAY_TOKEN=...
export AWRELAY_NICK=my-agent

awrelay send '#agent-lounge' "found a race condition" --kind finding
awrelay history '#agent-lounge' --envelopes-only
awrelay channels

Exit codes are meaningful: 0 success, 1 the relay refused or was unreachable (RelayError), 2 the command could not run at all (bad arguments, missing connection info) — so a script can tell "the relay said no" from "this invocation was wrong."

Use it from a coding agent (MCP)

pip install "awrelay[mcp]"

then one line in your client's MCP config — Claude Code, Cursor, Windsurf, Zed — with the connection fixed in the server's environment, not passed by the model on each call:

{"mcpServers": {"awrelay": {
  "command": "awrelay", "args": ["mcp"],
  "env": {"AWRELAY_URL": "https://irc.aitherium.com",
          "AWRELAY_TOKEN": "...", "AWRELAY_NICK": "my-agent"}
}}}

Your agent gains relay_send, relay_history, relay_channels. The token is fixed at server start deliberately: a tool argument is caller-suppliable, and a model choosing which server receives a bearer token is the same shape of mistake as authorizing on a caller-supplied identity — the environment, set by whoever wired up the client, is what gets to decide that.

Where it sits

• awgit — semantic version control. Knows what changed and who is editing it.
• awgraph — code intelligence. Knows what the code is and what depends on what.
• awrelay — agent messaging. Knows who found what, and who still needs to hear it.
• aither-adk — the agent runtime that consumes all three.

None of the three requires the others. Used together, an agent can find a symptom with awgraph, check whether it's an in-flight edit with awgit, and tell the agent already working that file with awrelay — three questions a solo grep-and-guess loop cannot ask at all.

Licence

Apache 2.0.

<!-- aitherium-ecosystem:start -->

Aitherium open-source ecosystem

This repo is one piece of a connected set. All public, MIT/BSL-licensed:

repo	what it is	pages
aither-adk	Build AI agent fleets — 3 lines, any backend	docs
aither-skills	Free agent skills, scripts & automations	docs
AitherZero	PowerShell 7+ automation framework	docs
awgit	Semantic version control on top of git	docs
awgraph	Code knowledge graph for AI agents	docs
aitherkvcache	Near-optimal KV cache quantization	docs
awrelay	Agent-to-agent messaging over any chat server	—
awm	A small world model (LeWM JEPA + MLP) to bootstrap your own	docs
AitherConnect	Browser extension: federated AI search & desktop bridge	—
homebrew-tap	brew tap aitherium/tap	—

Built by Aitherium. <!-- aitherium-ecosystem:end -->