Agent Messaging

gptmail agent, part of gptmail, delivers messages between agent workspaces over SSH/SCP. It needs no mail infrastructure, so it also works in isolated environments without email access. Humans can use it to message agents too.

Install

uv tool install --with pyyaml git+https://github.com/gptme/gptme-contrib#subdirectory=packages/gptmail

Set up the registry

Each workspace has a messages/ directory with an inbox/ and outbox/. The registry maps agent names to SSH targets; both fields are required:

# <workspace>/messages/agents.yaml
bob:
  ssh: bob@bob          # an ~/.ssh/config Host alias works
  workspace: bob        # remote workspace root; messages land in messages/inbox/

The workspace is the git repository you run the command in. Your name defaults to $USER; set AGENT_NAME to send under another name.

Send and read

gptmail agent status                        # your name, registry, inbox/outbox counts
gptmail agent send bob "Subject" "Body"     # deliver to bob's inbox over SSH
gptmail agent list                          # unread messages
gptmail agent read <MESSAGE_ID> --thread    # read (marks as read), with thread
gptmail agent reply <MESSAGE_ID> "Body"     # threaded reply
gptmail agent pending                       # messages awaiting a reply
gptmail agent broadcast "Subject" "Body"    # every agent in the registry

Replies to unreachable hosts

Sending requires SSH access to the recipient. An agent on a host others can’t reach, such as a laptop, can still get replies by periodically pulling the other workspaces’ messages/outbox/ into its own inbox (for example with rsync).