ainbox

AInbox – Filesystem-Based Async Mailbox for Coding Agents

A minimal, cross-platform mailbox runtime with a native Rust CLI and a Python compatibility path for decentralized agent communication via structured markdown messages and a shared filesystem.

No broker. No orchestrator. Just files and conventions.

Quick Start

Installation

# Linux/macOS installer (downloads the latest native release)
curl -fsSL https://raw.githubusercontent.com/JerrettDavis/AInbox/main/scripts/install.sh | bash

# Windows installer (downloads the latest native release)
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/JerrettDavis/AInbox/main/scripts/install.ps1 | iex"

# Native install from source
cargo install --path .

# Python compatibility install from the repo checkout
pip install -e .

# Python compatibility install from GitHub
pip install git+https://github.com/JerrettDavis/AInbox.git

If you already have an AInbox checkout locally, prefer the safe ensure helpers:

# Linux/macOS (source it so PATH updates stay in the current shell)
source ./scripts/ensure-mailbox.sh

# Windows PowerShell
.\scripts\ensure-mailbox.ps1

The ensure helpers install the latest native release only when mailbox is missing and make the install directory available in the current session.

Verify:

mailbox --version

Prebuilt native binaries are published through GitHub Releases for Windows, macOS, and Linux. The same packaged archives are also published to GHCR as OCI artifacts for package-registry consumers.

Optional installer controls:

# install a specific release tag
AINBOX_VERSION=vX.Y.Z curl -fsSL https://raw.githubusercontent.com/JerrettDavis/AInbox/main/scripts/install.sh | bash

# install into a custom directory
AINBOX_INSTALL_DIR="$HOME/bin" bash scripts/install.sh

Plugin Marketplace Installation

Claude Code

claude plugin marketplace add JerrettDavis/AInbox
claude plugin install ainbox@ainbox-marketplace
claude plugin install agent-poll@ainbox-marketplace
claude plugin install elections@ainbox-marketplace

When the Claude plugin is enabled, bundled hooks do a best-effort silent bootstrap of the native mailbox binary on session start and before Bash tool calls. If the environment cannot support that automatic install, use the local ensure helpers instead.

GitHub Copilot CLI

copilot plugin marketplace add JerrettDavis/AInbox
copilot plugin install ainbox@ainbox-marketplace
copilot plugin install agent-poll@ainbox-marketplace
copilot plugin install elections@ainbox-marketplace

The marketplace installs the AInbox command/skill plugin metadata. Claude Code can now auto-bootstrap the native mailbox binary through plugin hooks when possible; otherwise use the native installers or local ensure helpers above so mailbox is available on PATH.

Once the native CLI is available, you can bootstrap supported global agent integrations in one step:

mailbox init -g

mailbox init now does two local setup steps:

• creates the local .mailbox/ folders
• seeds project mailbox instructions in .claude/MAILBOX.md and .agents/MAILBOX.md, then prepends CLAUDE.md and AGENTS.md with one-time imports

mailbox init -g keeps that local setup and also seeds user-scoped instruction files in ~/.claude/ and ~/.agents/ before updating-or-installing the AInbox marketplace/plugins for supported agent CLIs already present on PATH (currently Claude Code and GitHub Copilot CLI).

Advanced consumers can also pull packaged archives from GHCR with OCI tooling using package names like ghcr.io/jerrettdavis/ainbox-mailbox-linux-x86_64:vX.Y.Z.

The core ainbox plugin also ships two mailbox-aware subagents:

• orchestrator - delegates work and synthesizes results through subagents and mailbox coordination
• project-manager - active leader that contributes directly while keeping delegation and coordination flowing through AInbox

You can force mailbox-based orchestration explicitly:

# Claude Code: launch directly into the AInbox orchestrator
claude --agent ainbox:orchestrator "Coordinate this task through mailbox-aware subagents and synthesize the result."

# Claude Code: use the active leader variant instead
claude --agent ainbox:project-manager "Lead this task with mailbox coordination and delegate bounded work."

# GitHub Copilot CLI: launch the CLI, then select the AInbox subagent
copilot
/agent
# choose ainbox:orchestrator or ainbox:project-manager, then give the task prompt

Headless Workflow Smoke Test

To validate a local mailbox workflow end-to-end, including election handling, mailbox handoffs, and Claude-driven proposer/reviewer collaboration, run:

.\scripts\run-headless-mailbox-e2e.ps1