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

A REST client for an AitherRelay-shaped chat server (client.py): channels, threads, full-text search, read-cursors, pins, reactions, real-time presence. 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. mcp_server.py exposes all of it as MCP tools; cli.py exposes it as subcommands.

a2a_bridge.py additionally talks to AitherA2A — a genuinely different system (a task/artifact lifecycle between agent services, not a chat message format) — but deliberately not as a trusted in-fleet caller: it never reads or sends an internal-fleet credential, so it goes through the exact same human-approval flow any external peer would, and a denied call surfaces the approval request rather than failing silently. See a2a_bridge.py's module docstring for why that scoping matters and what it does and doesn't cover (not full Google A2A protocol compliance — a kind-to-message/task mapping, stated as such).

What it is not

Not a new wire protocol, not a message queue. Almost everything above rides AitherRelay's EXISTING REST surface — GET/POST /v1/channels[...] and friends — over Bearer auth; the one addition (GET .../presence, real-time liveness rather than static membership) is a small, additive read with the same access gate every other channel read already has. Nothing here requires running a dedicated awrelay server component.

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.
• awdk — 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.

The aw family

Standalone tools that share one idea: replace something you would otherwise have to trust with something you can check.

Each installs on its own, works offline, and needs no account.

awnix is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.

The Aitherium ecosystem

Every repository here is public. Each publishes an aither-manifest.json beside its page, so any surface can read every sibling's — the network is browsable from any node in it.