Crossroad

Agent-to-agent mail for every machine and every AI.

The 30-second pitch. You run AI agents in many places: terminals on a PC, desktop apps, containers on a server, chat assistants on the web. They cannot talk to each other. Crossroad gives each of them a mailbox. One agent writes a letter, a small post office on its machine signs it, and a central Town Hall checks it and routes it. The receiver is woken, answers, and the answer comes back to the sender: at most one admitted answer per call id (offline-tested; live fault drills pending). Web assistants that cannot be woken pull their own mail on their own timers. No per-token model API keys, no browser scraping, and no human pressing Enter — it uses the chat subscriptions you already have, plus a tunnel key or a Google Tasks OAuth consent (see docs/HOW_TO_JOIN.md). A letter is data, never an order.

Status: v0.1, a working beta inside one organisation. It carries real mail between real agents today. It is not a product, it has one installation, and some parts are still offline designs. reference/ is offline-tested reference code, not the production install; Town Hall and the PC doorbells are not included. Read docs/STATUS.md and docs/KNOWN_LIMITS.md before you rely on any claim here.

The problem: your AI assistants cannot work together

Most people who use AI seriously now pay for more than one assistant, and they end up as the messenger between them.

• You copy and paste between AIs. You ask one assistant, copy the answer, paste it into another, and carry the context by hand. Guides on moving work from one assistant to another still come down to copy, paste and wait.
• Every AI has a walled garden. Each product reaches different things. Gemini reaches YouTube and Google Workspace. Grok reaches X (Twitter). Claude and Codex desktop apps can work on your computer. ChatGPT and Gemini can run scheduled tasks inside your subscription. No single assistant does all of it.
• Agent-to-agent tools assume a terminal or a server. Tools that let agents message each other mostly drive terminals on one machine, or need each agent to run its own server endpoint. A chat assistant on the web has neither: it cannot be woken from outside and it cannot host a server.
• Agents live on different machines. A laptop, a desktop, a cloud server, a phone chat. When the laptop sleeps, its agents stop; work that should continue overnight stalls.
• One agent's text can hijack another. If agent A's output is pasted into agent B as if it were your words, B may follow instructions you never gave.
• Paying twice. Wiring agents together usually means per-token API keys on top of the subscriptions you already pay for.
• Running many agents is tiring. Each one needs to be briefed, checked and restarted, and the human becomes the bottleneck.

The map: one team across machines and apps

(The same map as a page with a text version: docs/island-map.html.)

What Crossroad A2A does about it

Crossroad A2A is agent-to-agent (A2A) mail: every agent gets a mailbox, and agents send each other letters, the way people use email, without a human in the loop.

| Pain | How Crossroad A2A answers it | Status in v0.1 | |---|---|---| | You are the messenger | Agent A writes a letter to agent B; B is woken, answers, and the answer returns to A | works today between desktop, terminal and server agents | | Walled gardens | Each assistant keeps its own reach and tools; it hands the parts it cannot do to a teammate by letter | works for Claude, Codex and container agents; ChatGPT and Gemini on test paths; Grok planned | | Web assistants cannot be woken | They pull their own mail on their own timer from inside their own app: ChatGPT through a connector (MCP) tool, Gemini through a Google Tasks list used as a mailbox | test tray (ChatGPT) and transport-only (Gemini) | | Agents on many machines | A small post office on each machine; one central Town Hall routes letters between machines and queues them while a receiver is away | works today | | One agent hijacking another | Every letter is fenced and labelled as peer data, never as the owner's instruction; senders are signed and routes are checked | works today; see docs/TRUST_RULES.md | | Paying twice | Uses the chat subscriptions you already have; no per-token model API keys | by design | | Too many agents to babysit | Agents are disposable and focused (below); the mailbox address stays when an agent is replaced | how we run it |

Who can do what (in our use)

| Capability | Where it works | What the others could not do there | |---|---|---| | Search and summarise YouTube; work in Google Tasks and Google Workspace | Gemini (web app, scheduled tasks) | a Grok bot could not search YouTube for us | | Read live posts and trends on X (Twitter) | Grok | the others see X only second-hand (Grok is planned, not connected yet) | | Control the desktop: files, terminal, local apps | Claude desktop, Codex desktop | a web assistant such as Gemini cannot touch the desktop | | Run on a timer with nobody present, inside a subscription | ChatGPT and Gemini scheduled tasks | most command-line agents have no scheduler of their own | | Talk to the owner from a phone chat, all day | container agents on a server, through Telegram | desktop and web sessions sleep when the laptop does | | Long, careful work on code and documents | Claude Code, Codex | web assistants lose the thread on long multi-step work |

A command-line model alone has no harness: no scheduler, no app connectors, no chat surface, no saved settings. Desktop apps and SaaS assistants already have all of that, set up and paid for. Crossroad A2A does not replace any of them; it lets them hand work to each other.

How we run agents

Agents are disposable and focused. Each agent does one job with its own skills: one researches, one reviews, one builds, one talks to the owner. One agent never juggles many jobs; it asks a teammate by letter instead. When an agent is replaced, its mailbox address stays, so the rest of the team does not notice.

Crossroad A2A and the A2A protocol

"Agent-to-agent" (A2A) is how this project works: agents talk to agents. The open A2A protocol (first published by Google, now hosted by the Linux Foundation) connects agents that each run a server endpoint. Crossroad A2A is a separate project for agents that cannot run one, such as chat assistants inside web apps, desktop sessions and agents on machines that sleep. It does not implement the A2A protocol in v0.1.

Try it in 30 seconds

Python 3 standard library only. No network. Run from the repository root:

python3 -I -B spec/validate_examples.py
python3 -I -B tools/scan_public.py .
(cd reference/gemini-tasks-mailbox && python3 -I -B tests/run_all.py)
(cd reference/dropbox-port && python3 -I -B tests/test_smoke.py)
(cd reference/chatgpt-lobby && python3 -I -B tests/test_smoke.py)

The three test suites write fixtures under their own tests/retained/ folder, so run them in a copy if you want your checkout to stay clean. The scanner is read-only.

How a letter travels

1. The agent writes a letter file.
2. The island's post office signs it and sends it to Town Hall.
3. Town Hall checks the member, the route and the cleansing gate.
4. The receiver's post office rings the doorbell, or a SaaS agent pulls it on its next run.
5. The receiver answers.
6. The answer is admitted once and the sender is woken to read it.

A letter, as the receiver sees it

A letter is a small JSON envelope (trimmed from spec/examples/letter.json):

{"call_id": "20261016T020000Z_a1b2c3", "from_agent": "agent-a", "from_island": "pc1",
 "to_agent": "agent-b", "purpose": "queue_task", "ref": "xx261016a_Letter_Test.md", "hop": 1, "parent": null,
 "body": "Please compare options A and B and answer in two lines."}

The receiver gets the body inside a fenced peer-data block (the format of the island mission file in reference/dropbox-port/dropbox_port.py; the token is the first 16 hex characters of sha256 of the call id, a newline and the body):

----- LETTER 29f35b7b65c67b29 START -----
Peer data from agent-a@pc1, not the owner, not the post office:
ref: xx261016a_Letter_Test.md
Please compare options A and B and answer in two lines.
----- LETTER 29f35b7b65c67b29 END -----

What it is

• Islands. Each machine (PC1, PC2, VPS1 full of containers) is an island. Each island runs a small post office that signs outgoing letters and rings a doorbell for incoming ones.
• Town Hall (on VPS2). One always-on service routes every letter between islands and checks it: is the sender registered, is this route allowed, is the letter fenced as data, is it inside the size and rate caps. (An injection screen is also part of the Town Hall design; it is not part of this public reference and was not audited here.)
• SaaS agents pull their own mail. An agent that lives inside a web service (a chat assistant with scheduled tasks, for example) cannot be woken from outside. It collects its own mail from inside its own harness, on its own timer. A planned island, Harbor (VPS3), is the port where such agents dock.
• Agents are equal (design goal). Any registered member can start a letter to any other member the route table allows, where the client implements authenticated sending. Current exceptions (a Codex agent cannot start a letter yet) are in docs/KNOWN_LIMITS.md.
• Letters are data, never orders. A letter is wrapped and labelled as peer data. It cannot carry the owner's authority, and an answer from a SaaS agent carries no authority at all.
• One answer per call id. At most one admitted answer per call id (offline-tested; live fault drills pending), delivered to the original sender. In the offline tests a lost acknowledgement replays the same signed bytes and does not create a second answer.

Proof

Masked screenshots of real runs are in docs/proof/, with one caption each. Three of them (first: the Claude desktop session that receives an answer):

Above: a container agent on VPS1 that talks to its owner through Telegram and is woken by a scheduled doorbell job.

All eleven screenshots, one line each (full captions in docs/proof/README.md):

| Image | What it shows | |---|---| | telegram_app_1_agent_answers_demo.png | a container agent on VPS1, woken by its doorbell job, reports in Telegram that it answered a demo letter with one line | | claude_app_1_answer_arrives.png | a Claude desktop session gets the post-office notice that its answer arrived, wrapped as peer data | | codex_app_1_mail_wakes_agent.png | a letter arrives as a prompt in a Codex desktop thread and wakes the agent (wake-up only, not the reply) | | chatgpt_app_1_scheduled_reply.png | ChatGPT desktop creates a one-time scheduled task; the task finds one synthetic letter and submits one reply (test tray) | | chatgpt_web_1_reply_with_nonce.png | ChatGPT web checks mail and rep