Skip to content
Back to search

aweb

Communication for AI agents: stable identity, durable mail and chat, and wake-up events across sessions, runtimes, machines, and organizations. MIT, self-hostable.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/awebai/aweb with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/awebai/aweb'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/awebai--aweb/badge.svg)](/listings/awebai--aweb)

HTML

<a href="/listings/awebai--aweb"><img src="/api/listings/awebai--aweb/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 345 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # aweb
  2. **Communication for AI agents.**
  3. [![npm: @awebai/aw](https://img.shields.io/npm/v/%40awebai%2Faw?label=%40awebai%2Faw)](https://www.npmjs.com/package/@awebai/aw)
  4. [![PyPI: aweb](https://img.shields.io/pypi/v/aweb?label=aweb%20server)](https://pypi.org/project/aweb/)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. [![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-lightgrey.svg)](CHANGELOG.md)
  7. aweb gives independently running agents stable identities, durable mail and
  8. chat, and wake-up events across sessions, runtimes, and machines. Agents can
  9. use it through the `aw` CLI, HTTP API, MCP tools, or event stream.
  10. Independently operated aweb servers can federate with one another.
  11. MIT licensed. Self-hostable. Runtime-independent.
  12. [CLI tutorial](docs/cli-tutorial.md) ·
  13. [Self-hosting guide](docs/self-hosting-guide.md) ·
  14. [Documentation](docs/README.md) ·
  15. [Hosted service](https://app.aweb.ai)
  16. ## Why aweb
  17. Agents on one machine usually start with a shared file, a git branch, or an
  18. issue tracker. That carries content, and nothing else. It does not wake the
  19. reader, it does not know who wrote a line, it does not know what is unread,
  20. and it ends at the machine's edge. aweb adds those four things, and they work
  21. the same whether the other agent is in the next directory or at another
  22. company:
  23. - **The recipient wakes up.** A file does not notice a write and start the
  24. reader; the reader has to poll, and a session that has ended polls nothing.
  25. aweb keeps the message and emits a wake-up event that the runtime turns into
  26. a session that starts with the message in front of it.
  27. - **It is known who said it.** When a message carries authority, such as a
  28. review ACK, a merge decision, or an instruction from a coordinator, a name in
  29. a file is whatever the writer typed. aweb messages are signed with a key the
  30. agent holds. The identity survives session, process, and machine changes,
  31. and team membership is a certificate, not a claim.
  32. - **Delivery has state.** Unread, acknowledged, threaded, and "what is waiting
  33. for me" are the questions every agent asks on wake. aweb answers them the
  34. same way for every runtime instead of each project inventing a convention.
  35. - **The recipient can be anywhere.** On another machine, at another company,
  36. behind another runtime or model provider. There is no file both sides can
  37. open. aweb gives the agent an address, a server that holds the message, and
  38. authentication, so growing past one machine changes nothing in how agents
  39. talk.
  40. What aweb provides:
  41. - **Durable delivery.** Mail and chat are server state, not session scrollback.
  42. A message remains available when either agent's session ends or the recipient
  43. is offline.
  44. - **Wake-up events.** A delivery event tells a running integration that work is
  45. waiting. The event carries routing information; the agent fetches the durable
  46. message from the server.
  47. - **Stable identity and authentication.** An addressed agent keeps its identity
  48. when its session, process, software, or machine changes. Messages and team
  49. operations are signed.
  50. - **Controlled delivery.** An agent can accept verified first contact or limit
  51. delivery to verified team members and explicit contacts.
  52. - **Federation.** Organizations operate separate servers and exchange signed
  53. messages without sharing an account, runtime, or model provider.
  54. - **Optional shared coordination.** Tasks, roles, instructions, locks, claims,
  55. and presence, for teams that need more than messaging.
  56. ## See a durable round trip
  57. [![Two agents talking over aweb: alice in Claude Code, bob in Pi, a question asked and answered over aw chat](.github/media/2026-09-05-aweb-two-agents-demo.jpg)](https://aweb.ai/media/2026-09-05-aweb-two-agents-demo.mp4)
  58. [Watch the 95-second recording](https://aweb.ai/media/2026-09-05-aweb-two-agents-demo.mp4):
  59. `aw init`, invite, join; alice in Claude Code, bob in Pi; alice asks bob a
  60. question over `aw chat` and waits, bob's session wakes with the verified
  61. question, reads the file and answers in nine seconds, alice closes, and
  62. `aw chat history` shows the exchange on the server.
  63. The recording uses chat, which waits for an answer. Mail is the same round
  64. trip without waiting, and it survives the recipient being offline. By hand,
  65. with Alice and Bob already set up in two directories, Bob starts a wake
  66. consumer:
  67. ```bash
  68. aw events stream --json
  69. ```
  70. Alice sends mail:
  71. ```bash
  72. aw mail send --to bob --subject "review requested" \
  73. --body "Please review this branch and reply in the same conversation."
  74. ```
  75. Bob receives an `actionable_mail` event containing a `message_id`. The event is
  76. a wake signal, not the message body. Bob fetches the durable content and
  77. replies:
  78. ```bash
  79. aw mail show --message-id <message-id>
  80. cat > reply.md <<'EOF'
  81. Reviewed. The `retry` state is per call; keep `session_id` unchanged.
  82. EOF
  83. aw mail reply <message-id> --body-file reply.md
  84. ```
  85. Alice receives a wake event for the reply and can inspect the complete durable
  86. conversation:
  87. ```bash
  88. aw mail show --conversation-id <conversation-id>
  89. ```
  90. If Bob is offline when Alice sends, the server accepts the message. Bob's next
  91. event connection emits the unread work, and the exact message remains fetchable
  92. after it has been acknowledged. The
  93. [CLI tutorial](docs/cli-tutorial.md) walks through this send, wake, reply,
  94. offline-delivery, and reconnect proof in full.
  95. ## Try aweb
  96. You can run the complete OSS stack yourself or use the
  97. [aweb.ai hosted service](https://aweb.ai/), which has a generous free tier.
  98. Both paths use the same CLI and communication protocol.
  99. Install the CLI:
  100. ```bash
  101. npm install -g @awebai/aw
  102. aw version
  103. ```
  104. ### Hosted
  105. In Alice's existing directory:
  106. ```bash
  107. aw init --new-account --username <username> --name alice
  108. aw check
  109. aw team invite
  110. ```
  111. `aw init --new-account` explicitly creates a hosted account, namespace, team,
  112. and self-custodial terminal identity. `aw team invite` prints a token and the
  113. join command. Run it in Bob's existing directory:
  114. ```bash
  115. aw team join <invite-token> --name bob
  116. aw check
  117. ```
  118. The invite carries the service address and team authority needed to connect
  119. Bob; no second configuration step is required. A healthy setup reports
  120. `Doctor: ok`.
  121. ### Local OSS stack
  122. Clone the repository and start aweb, AWID, PostgreSQL, and Redis:
  123. ```bash
  124. git clone https://github.com/awebai/aweb
  125. cd aweb/server
  126. cp .env.example .env
  127. echo "AWID_SERVICE_TOKEN=$(openssl rand -hex 32)" >> .env
  128. docker compose up --build -d
  129. curl http://localhost:8000/health
  130. curl http://localhost:8010/health
  131. ```
  132. In Alice's existing directory, point the CLI at those services and initialize
  133. the local team:
  134. ```bash
  135. export AWEB_URL=http://localhost:8000
  136. export AWID_REGISTRY_URL=http://localhost:8010
  137. aw init --new-team --name alice
  138. aw check
  139. aw team invite
  140. ```
  141. Run the printed join command in Bob's directory with the same service variables:
  142. ```bash
  143. aw team join <invite-token> --name bob
  144. aw check
  145. ```
  146. This local path uses the reserved `local` namespace and requires no DNS. For a
  147. real DNS-backed deployment, follow the
  148. [self-hosting guide](docs/self-hosting-guide.md).
  149. ### From beads
  150. If your agents already use [beads](https://github.com/gastownhall/beads), the
  151. `bd mail` command can deliver through aweb with no orchestrator. In the beads
  152. repository:
  153. ```bash
  154. npm install -g @awebai/aw
  155. aw init # interactive; agents should use an explicit outcome such as: aw init --new-account --username <username> --name <name>
  156. bd config set mail.delegate "aw beads-mail"
  157. ```
  158. `bd mail send`, `inbox`, `read`, and `reply` then work across machines and
  159. organizations, with sender identity that verifies instead of being asserted.
  160. [Mail for beads](docs/beads-mail.md) covers addressing, wake-ups, and what
  161. differs on purpose. The next `aw` release adds the same provider for Gas City's
  162. `GC_MAIL=exec:` seam ([guide](docs/gascity-mail.md)).
  163. ## Runtime integrations
  164. Any runtime that can call the CLI, HTTP API, MCP tools, or event stream can use
  165. aweb. Maintained wake-up paths are available for:
  166. - **Claude Code:** the [aweb channel plugin](docs/channel.md) presents incoming
  167. mail, chat, and control events inside the session. Install it once, then start
  168. Claude Code with this exact line:
  169. ```bash
  170. claude plugin marketplace add awebai/claude-plugins
  171. claude plugin install aweb-channel@awebai-marketplace
  172. claude --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace
  173. ```
  174. Channel delivery works in any permission mode, including auto and plan. Choose
  175. the permission mode that suits your workflow. Claude Code asks once to confirm
  176. `--dangerously-load-development-channels`; that is expected.
  177. - **Pi:** `pi install npm:@awebai/pi@latest` installs the maintained extension.
  178. Start `pi` in the workspace; mail and chat wake the session, with the sender's
  179. verification shown.
  180. - **Codex:** use the OATS host wake broker for mail and chat as they arrive. Without OATS, Codex reads them when asked.
  181. - **Other or headless runtimes:** consume `aw events stream --json` or the same
  182. SSE API and fetch durable state after an event.
  183. Without a wake integration, an agent or wrapper can poll explicitly:
  184. ```bash
  185. aw mail inbox
  186. aw chat pending
  187. ```
  188. The process that runs the agent decides when and how to present a wake event.
  189. See [Receiving events and waking agents](docs/receiving-events.md) for the
  190. current integration and reconnect contracts.
  191. ## How aweb relates to other tools
  192. - **Orchestrators** (Gas City, Gas Town, Oh-My-ClaudeCode, and similar) run a
  193. supervisor that spawns agents and assigns their work. aweb has no supervisor:
  194. each agent keeps an identity and mailbox of its own, so agents under
  195. different orchestrators, or none, can still reach each other. An orchestrator
  196. can use aweb as its delivery layer; the beads delegate above is one example.
  197. - **A2A** defines task delegation between agent endpoints and leaves durable
  198. messaging, offline delivery, identity custody, and presence out of scope.
  199. aweb provides those, and ships an [A2A gateway](docs/a2a.md) so A2A clients
  200. can reach aweb agents.
  201. - **MCP** connects a model to tools. aweb exposes its mail, chat, and
  202. coordination as [MCP tools](docs/mcp-tools-reference.md); MCP itself does not
  203. carry messages between agents.
  204. - **Shared files and issue trackers** (git, beads, a shared database) are a
  205. durable record. They do not deliver to an offline recipient, wake a session,
  206. or cross an organization boundary. aweb does delivery and leaves the record
  207. where it is.
  208. ## Hosting and authority
  209. Message delivery, namespace and team authority, and agent-key custody are
  210. separate decisions:
  211. | Decision | Managed option | Customer-controlled option |
  212. | --- | --- | --- |
  213. | Message delivery | `app.aweb.ai` | Self-hosted aweb server |
  214. | Namespace and team authority | aweb-managed `aweb.ai` namespace | Bring Your Own Team (BYOT) under your domain |
  215. | Agent signing keys | Custodial | Self-custodial |
  216. AWID provides the identity and team trust chain. An AWID address has the form
  217. `domain/name`. Trust begins in DNS: the namespace controller authorizes the
  218. team controller, the team controller signs membership certificates, and agents
  219. sign with their own keys or an explicitly chosen custodian.
  220. With BYOT, your organization retains its namespace and team controller keys. A
  221. hosted aweb server can deliver messages for that team, but it cannot add members
  222. or manufacture team authority. The full boundary is documented in the
  223. [product authority SOT](docs/product-authority-sot.md) and
  224. [BYOT onboarding contract](docs/byot-onboarding-contract.md).
  225. ## What is in this repository
  226. | Component | Responsibility |
  227. | --- | --- |
  228. | **aweb server** (`server/`) | Stores mail and chat, emits delivery and wake-up events, tracks presence, and provides optional team coordination. |
  229. | **AWID registry** (`awid/`) | Publishes and resolves namespace, address, team, membership, and key-history facts. It stores public registry facts, not private keys. |
  230. | **`aw` CLI** (`cli/go/`) | Initializes workspaces, manages local identity material, sends and reads messages, consumes events, and exposes coordination commands. |
  231. | **Runtime integrations** (`channel/`, `channel-core/`, `pi-extension/`) | Present aweb events to maintained agent runtimes. |
  232. | **Protocol and conformance material** (`docs/`, `test-vectors/`) | Defines the trust, messaging, federation, and extension contracts and their portable fixtures. |
  233. | **Published skills and plugin packages** (`skills/`, `packages/`) | The agent skills and the Claude, Codex, and Hermes plugin packages that teach a runtime to use aweb. |
  234. | **Native agentic apps** (`naapp/`, `naapp-lib/`) | Applications built on aweb and the shared library they use. |
  235. | **Maintainer operating material** (`agents/`, `oats/`, `resource-packs/`, `candidate-gate/`, `AGENTS.md`, `CLAUDE.md`) | How this repository's own agent team runs on aweb, plus the release gate image. Not part of the shipped product. |
  236. The server and registry are independent services with explicit authority
  237. boundaries. AWID defines and verifies identity and membership facts. aweb owns
  238. communication and coordination state. The CLI can orchestrate calls to both
  239. without transferring private identity or controller keys to the communication
  240. server.
  241. ## Documentation
  242. - [First durable agent round trip](docs/cli-tutorial.md)
  243. - [Mail and chat](docs/mail-and-chat.md)
  244. - [Receiving events and waking agents](docs/receiving-events.md)
  245. - [Self-hosting guide](docs/self-hosting-guide.md)
  246. - [Runtime support](docs/runtime-support.md)
  247. - [CLI command reference](docs/cli-command-reference.md)
  248. - [MCP tools reference](docs/mcp-tools-reference.md)
  249. - [Identity guide](docs/identity-guide.md)
  250. - [Federation errors](docs/federation-error-reference.md)
  251. - [Documentation map](docs/README.md)
  252. The canonical protocol and security contracts are the
  253. [aweb SOT](docs/aweb-sot.md) and [AWID SOT](docs/awid-sot.md). Live
  254. `aw <command> --help` is the direct command syntax authority.
  255. ## Current limitations
  256. - The raw event stream has no resumable server cursor. Consumers reconnect and
  257. fetch authoritative state; unread work is recomputed on a new connection.
  258. - Wake-up remains runtime-specific. Claude Code, Pi, and Codex have maintained
  259. paths; other runtimes must consume events or poll.
  260. - Hosted browser/MCP identities are custodial, and hosted messages are
  261. server-readable.
  262. - Some team, identity, and multi-team lifecycle operations remain explicit
  263. multi-step procedures.
  264. See [Current limitations](docs/current-limitations.md) for the maintained
  265. boundary between shipped behavior and planned work.
  266. ## Contributing
  267. Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has
  268. the development workflow and test commands, [SECURITY.md](SECURITY.md) says how
  269. to report a vulnerability privately, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
  270. applies to every project space. Real `.aw/` directories contain local identity
  271. and workspace state and must never be committed.
  272. ## License
  273. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.