agentMailSystem

Minimal Go tools to let CLI-based agents exchange messages via NATS, with an email-like mailbox workflow.

The core idea: agents should not spam each other with rapid-fire requests. Instead, messages become “mail” files on disk (./agentMailSystem/), and a background helper periodically sends/receives mail via NATS and nudges the running terminal session.

Binaries

• agentClirunner: thin terminal wrapper; runs a command in its own shell process and forwards stdin/stdout/stderr 1:1. Supports --add-Notification helpers.
• agentGetNATSMessages: presence + message receiver. Creates the mailbox folder ./agentMailSystem/, writes incoming messages as Markdown files, notifies the running terminal, and periodically processes the Outbox.
• agentSendNATSMessages: direct send CLI (useful for users/scripts). Includes local safeguards (one pending request per peer; one reply per message id).
• agentGetNATSAgents: lists online agents (presence).
• agentRepeatPrompt: periodically injects a prompt into the terminal input (or --stdout).

NATS Configuration

This repo does not ship with any default NATS URL or credentials.

All NATS-enabled binaries support configuration in this priority order:

1. CLI flags: --nats-url, --nats-creds
2. Env vars: AGENTMAILSYSTEM_NATS_URL, AGENTMAILSYSTEM_NATS_CREDS
3. Config file: ./agentMailSystem/config.yaml or ~/.agentMailSystem/config.yaml

Example config (./agentMailSystem/config.yaml):

nats:
  url: nats://127.0.0.1:4222
  # creds: /path/to/user.creds

Mailbox Layout

When agentGetNATSMessages runs in an agent’s working directory, it creates:

agentMailSystem/
  inBox/
    archive/
  outBox/
    availableAgentsInfos.md
    <OtherAgentId>/
      archive/
  archive/
    <OtherAgentId>/   (outboxes for agents that went offline)

• Incoming NATS messages are written to agentMailSystem/inBox/YYYYMMDD-HHMMSS-<id>.md.
• The running terminal is notified: “You have mail… open the file… then move it to archive.”
• Outgoing messages are created by the LLM as Markdown files in agentMailSystem/outBox/<OtherAgentId>/.
  • For replies: start the file with InReplyTo: <MessageID>, then a blank line, then your message.
• The background tool sends at most one mail per agent per cycle (default: every ~30 seconds) and moves sent files into archive/.

Build

Requires Go 1.22+.

go test ./...
make build

Outputs go into ./build/ (keeps the repo root clean).

Install (macOS + Linux)

make build
sudo ./build/install.sh

# optional:
sudo ./build/install.sh --prefix /usr/local/bin
sudo ./build/uninstall.sh

Run (Example)

Run an agent with mailbox messaging enabled:

agentClirunner "codex --dangerously-bypass-approvals-and-sandbox" \
  --add-Notification agentGetNATSMessages \
  --agent "Tanelorn.JokeJurry" \
  --description "Rates jokes 1-10"

In a second terminal, run another agent:

agentClirunner "codex --dangerously-bypass-approvals-and-sandbox" \
  --add-Notification agentGetNATSMessages \
  --agent "Tanelorn.JokeFactory" \
  --description "Writes jokes"

Notes

• If your agent runtime runs commands inside a sandbox, you must allow outbound network access to reach NATS (otherwise DNS/connect will fail).