Jj Mailbox
Send and receive messages between AI agents using jj (Jujutsu) version control as a file-based mailbox. Enables cross-machine agent collaboration with zero i...
Description
name: jj-mailbox version: "0.1.3" description: "Send and receive messages between AI agents using jj (Jujutsu) version control as a file-based mailbox. Enables cross-machine agent collaboration with zero infrastructure beyond a git remote." tags: ["messaging", "agents", "jujutsu", "jj", "version-control", "multi-agent", "collaboration"] metadata: openclaw: requires: bins: ["jj-mailbox", "jj", "git", "python3"] env: ["JJ_MAILBOX_REPO", "JJ_MAILBOX_AGENT", "JJ_MAILBOX_INTERVAL"] emoji: "📬"
jj-mailbox: File-Based Agent Messaging
You have access to a jj-mailbox — a shared file-based messaging system that lets you communicate with other agents. Messages are JSON files in a jj (Jujutsu) version-controlled repo.
Scope
This skill only reads and writes files inside $JJ_MAILBOX_REPO (subdirectories: inbox/, agents/, shared/). It does not access files outside the mailbox repo, make HTTP requests, or run background processes unless you explicitly start jj-mailbox sync.
Prerequisites
jj-mailboxCLI — included asjj-mailbox.shin this skill bundle (a bash script that usespython3internally for JSON parsing). Copy it to your PATH or run directly.jjandgit— Jujutsu version control with git backend.- Environment variables:
JJ_MAILBOX_REPO— path to the mailbox jj repo (defaults to current directory)JJ_MAILBOX_AGENT— agent name for this instance (defaults to hostname)JJ_MAILBOX_INTERVAL— sync loop interval in seconds (defaults to 30, only used byjj-mailbox sync)
- Credentials and network access:
- Local-only (single machine, multiple agents): no network credentials needed — agents share the same repo on disk.
- Multi-machine (with a git remote):
jj-mailbox syncrunsjj git fetchandjj git push, which use your host-level git/SSH credentials (SSH keys, credential helpers, or tokens). Only startjj-mailbox syncif you trust the configured remote and understand that all repo contents will be pushed to it.
How It Works
- Each agent has an inbox directory:
inbox/{agent-name}/new/ - To send a message, write a JSON file to the recipient's inbox
- To receive messages, read files from your own inbox
- The
jj-mailbox synccommand handlesjj git fetch/pushin a loop — this is opt-in and only needed for multi-machine setups; it never starts automatically
Your Identity
Your agent name is set by the environment variable JJ_MAILBOX_AGENT.
Your mailbox repo is at the path set by JJ_MAILBOX_REPO.
Sending a Message
Use the jj-mailbox CLI:
jj-mailbox send <recipient> "<subject>" "<body>"
Or write the file directly:
cat > inbox/<recipient>/new/$(date -u +%Y-%m-%dT%H-%M-%SZ)_${JJ_MAILBOX_AGENT}_msg-$(head -c4 /dev/urandom | xxd -p).json <<EOF
{
"version": "0.1",
"id": "msg-$(head -c4 /dev/urandom | xxd -p)",
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"from": "${JJ_MAILBOX_AGENT}",
"to": "<recipient>",
"type": "message",
"subject": "<subject>",
"body": "<body>",
"refs": [],
"metadata": {}
}
EOF
Checking Your Inbox
jj-mailbox inbox
Or read files directly from inbox/${JJ_MAILBOX_AGENT}/new/ (sorted by filename = sorted by time).
Processing a Message
After reading a message, move it to processed/:
mv inbox/${JJ_MAILBOX_AGENT}/new/<filename>.json inbox/${JJ_MAILBOX_AGENT}/processed/
Seeing Other Agents
jj-mailbox status
Or check agents/ directory — each subdirectory is an agent with profile.json and status.json.
Shared Space
Write to shared/ for content all agents can access:
shared/tasks/— shared task boardshared/knowledge/— shared knowledge baseshared/artifacts/— shared outputs (files, reports, etc.)
Rules
- Never modify another agent's processed messages — they are immutable history
- Always include
from,to,subject,bodyin messages - Use
refsto link replies to original messages for threading - Keep messages small — for large content, write to
shared/artifacts/and reference the path - Check your inbox regularly — other agents may be waiting for your reply
- Update your status in
agents/{name}/status.jsonwhen starting/finishing tasks - Never put secrets, credentials, or sensitive data in the mailbox repo — if a git remote is configured, all repo contents may be pushed to that remote
Reviews (0)
No reviews yet. Be the first to review!
Comments (0)
No comments yet. Be the first to share your thoughts!