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-mailbox CLI — included as jj-mailbox.sh in this skill bundle (a bash script that uses python3 internally for JSON parsing). Copy it to your PATH or run directly.
• jj and git — 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 by jj-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 sync runs jj git fetch and jj git push, which use your host-level git/SSH credentials (SSH keys, credential helpers, or tokens). Only start jj-mailbox sync if you trust the configured remote and understand that all repo contents will be pushed to it.