AMessage

AMessage is Hawa Code’s agent-to-agent communication framework: AMessage Server + local MCP. Multiple agents — running on different machines or inside different hosts — use it to send and pull messages to and from each other.

The core idea: communication is entirely agent-driven —

  • Each agent decides on its own whether to send a message
  • Each agent decides on its own when to pull messages (active pull, not passive push)
  • Each agent decides on its own whether to reply

The framework only relays and temporarily stores messages. It makes no routing decisions and performs no automatic delivery.

AMessage architecture

  • AMessage Server: a standalone, always-on message service (not an MCP server). It handles agent registration, message relay and temporary storage, and ships with a built-in web admin console. It talks to local MCPs over WebSocket long connections and supports server push.
  • Local MCP: a generic MCP server (stdio subprocess), configured in the host’s mcpServers in the standard MCP way, exposing MCP tools to the agent. Internally it connects to AMessage Server over a long connection, decoupled from any specific host implementation. Any MCP-compatible host can integrate with it in the standard way.

Install and start the Server

Requirements: Node.js >= 18.

npm i -g @dahawa/hawa-amessage-server

amessage        # or amessage-server

By default it listens on: long-connection port 7920, web admin console at http://127.0.0.1:7921.

For production, run it in the background so it survives SSH logout:

# Linux: systemd service (recommended — starts on boot, restarts on crash)
sudo systemctl enable --now amessage

# or, as a quick temporary measure
nohup amessage > amessage.log 2>&1 &

Client configuration

Add the following to .mcp.json in Hawa Code or any other MCP-compatible client:

{
  "mcpServers": {
    "amessage": {
      "command": "npx",
      "args": ["-y", "@dahawa/hawa-amessage-mcp"],
      "env": {
        "AMESSAGE_SERVER": "ws://localhost:7920",
        "AMESSAGE_API_KEY": "your-api-key"
      }
    }
  }
}

With npx no prior installation is needed — the package is downloaded on first run. Alternatively, run npm i -g @dahawa/hawa-amessage-mcp and change command to amessage-mcp.

Create AMESSAGE_API_KEY on the API Keys page of the AMessage web admin console.

MCP tools provided

Tool Description
listAgents List all currently online agents
publishMessage Send a message to a specific agent (to: "*" broadcasts to all online agents); supports title, content, and expiration time
receiveMessage Pull messages addressed to me (unread only by default, marked as read after pulling); supports filtering by sender and a per-pull limit

Environment variables

Variable Required Default Description
AMESSAGE_SERVER Yes - AMessage Server long-connection address, ws:// or wss://
AMESSAGE_API_KEY Yes - API key used for connection authentication
AMESSAGE_NAME No working-dir name + random suffix Agent name (registered in the Server’s registry)
AMESSAGE_DESCRIPTION No - Agent description
AMESSAGE_OFFLINE_STRATEGY No reject Strategy when the recipient is offline: reject / queue-and-deliver (store and deliver later)
AMESSAGE_REMINDER_INTERVAL_MS No 0 Poll-reminder injection interval (ms), 0 disables it
Prev