███╗   ███╗ █████╗ ███████╗███████╗
 ████╗ ████║██╔══██╗██╔════╝██╔════╝
 ██╔████╔██║███████║███████╗███████╗
 ██║╚██╔╝██║██╔══██║╚════██║╚════██║
 ██║ ╚═╝ ██║██║  ██║███████║███████║
 ╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝

Multi-Agent Supervision System

An OCI-inspired runtime for AI agent lifecycle management.

---

Create · Supervise · Recover · Scale

What You Get

🔌 Agent as a Service	Run any AI agent as a supervised, long-running process without a terminal.
🧩 Any Agent, One Interface	Speaks ACP (Agent Client Protocol). Claude Code, Codex, or any ACP-compatible agent — no vendor lock-in.
👁️ Observable, Interactive, Async	Typed event stream for every agent. Connect via TUI (massctl agentrun chat) anytime — chat, browse diffs, send a task, walk away, come back for results. Replay from any point.
📂 Shared Workspace	Multiple agents work in the same workspace (git / local / emptyDir). Ref-counted lifecycle, automatic cleanup.
⚡ CLI + JSON-RPC	massctl CLI for daily use. Full JSON-RPC 2.0 API (ARI) for orchestrators, CI pipelines, or custom UIs.

---

What is MASS?

Multi-Agent Supervision System — manages AI coding agents the way containerd manages containers. Not a framework. Not an SDK. A supervision system with clean layering, spec-driven contracts, and recovery built into the foundation.

MASS borrows the battle-tested architecture of the OCI container ecosystem and maps it directly onto the agent domain:

OCI (Containers)                    MASS (Agents)
─────────────────                   ─────────────────
runc + containerd-shim         →    agent-run
containerd                     →    agentd
CRI (Container Runtime Interface)→  ARI (Agent Runtime Interface)
OCI Runtime Spec               →    MASS Runtime Spec
OCI Image Spec                 →    MASS Workspace Spec
crictl                         →    massctl

Containers solved a structurally isomorphic problem: how to standardize describing, preparing, and executing isolated workloads. Agents face the same layered concerns — minus the kernel isolation.

Architecture

graph TD
    Client["massctl / Orchestrator"]
    Client -->|"ARI (JSON-RPC 2.0 / Unix socket)"| Agentd

    subgraph Agentd["agentd"]
        WM["Workspace Manager"]
        ARM["AgentRun Manager"]
    end

    ARM -->|JSON-RPC| AR1["agent-run"]
    ARM -->|JSON-RPC| AR2["agent-run"]

    AR1 -->|"ACP (stdio)"| Agent1["ACP Agent<br/>(claude)"]
    AR2 -->|"ACP (stdio)"| Agent2["ACP Agent<br/>(codex)"]

Loading

The diagram shows three layers: client → daemon → runtime. Each layer communicates via JSON-RPC.

Data Models

Concept	Description
Agent	Reusable template defining how to launch an agent process (command, args, env). Register once, use across workspaces.
Workspace	Prepared working directory (git clone, local mount, or empty scratch) shared by one or more agent runs.
AgentRun	Running instance of an Agent within a Workspace. Supervised process with its own lifecycle (creating → idle → running → stopped).

Components

Concept	Description
agentd	The daemon (analogous to containerd). Manages workspaces, forks/watches/recovers agent-run processes, and exposes the ARI API.
agent-run	The low-level runtime process (analogous to runc). Manages a single agent process, holds the ACP stdio connection, and translates protocol events.
massctl	CLI client (analogous to crictl). All operations go through ARI.

Protocols

Concept	Description
ARI	Agent Runtime Interface — JSON-RPC 2.0 over Unix socket. The control plane API between massctl/orchestrator and agentd.
agent-run RPC	JSON-RPC between agentd and each agent-run process. Used for lifecycle management and session control.
ACP	Agent Client Protocol — JSON-RPC over stdio between agent-run and the actual AI agent process.

Built-in Agents

MASS ships with three built-in agent definitions. All agents communicate via ACP over stdio and require Bun (bunx) to launch:

Agent	ACP Adapter	Status
claude	@agentclientprotocol/claude-agent-acp	Enabled
codex	@zed-industries/codex-acp	Enabled
gsd-pi	gsd-pi-acp	Disabled by default

Installation

Prerequisites

• Go 1.26+ — to build MASS
• ACP-compatible agent — at least one agent to run. Built-in agents (claude, codex, gsd-pi) require Bun or Node.js.

make build
# Produces: bin/mass (daemon + agent-run) and bin/massctl (CLI)

Quick Start

# 1. Start the daemon
mass server

# 2. In another terminal — launch a claude agent in the current directory
#    -w sets the workspace name, --agent picks a built-in agent definition
massctl compose run -w my-project --agent claude

# 3. Send a prompt and wait for the response
massctl agentrun prompt claude -w my-project --text "explain this repo" --wait

# 4. Or open the interactive TUI to chat, view diffs, and monitor in real-time
massctl agentrun chat claude -w my-project

# 5. When done, stop the agent run and clean up
massctl agentrun stop claude -w my-project
massctl workspace delete my-project

For declarative workflows, use compose apply with a YAML spec instead of imperative commands.

CLI Overview

mass — the daemon binary.

Command	Description
mass server	Start the MASS daemon
mass run	Directly spawn an agent-run process (low-level)

massctl — the CLI client. All operations go through ARI.

Command	Description
massctl compose run	Quick-start a single agent in the current directory
massctl compose apply	Declarative workspace + agent-run management via YAML
massctl workspace {create,get,delete}	Manage workspaces
massctl agent {apply,get,delete}	Manage agent definitions
massctl agentrun {create,get,stop,restart,delete}	Agent-run lifecycle
massctl agentrun prompt	Send a prompt to a running agent (--wait for response)
massctl agentrun chat	Interactive TUI — chat, view diffs, replay events
massctl daemon status	Check daemon health

Tech Stack

Layer	Technology
Language	Go 1.26+
RPC	JSON-RPC 2.0 (sourcegraph/jsonrpc2)
Storage	bbolt (embedded key-value)
Agent Protocol	ACP (JSON-RPC over stdio)

Documentation

• Design Specs — Architecture overview, OCI mapping, all spec documents
• Architecture — Component map, data flow, package layout
• Development Guide — Code principles, contribution rules, development references
• Decisions — Architectural decision records (D001–D112+)

Acknowledgments

MASS's interactive TUI (diff view, chat interface) incorporates code from Charmbracelet's Crush — a beautifully designed terminal UI toolkit. The vendored subset lives in third_party/charmbracelet/crush/ under the FSL-1.1-MIT license (converts to MIT two years after release). See NOTICE for details.

Thanks to the Charmbracelet team for building excellent TUI components that make terminal applications a joy to use.

License

This project is licensed under the Apache License 2.0.

Note: Third-party code under third_party/ may use different licenses. See NOTICE for details.

---

Built with the belief that AI agents deserve the same operational rigor as containers.

MASS — because managing agents shouldn't be harder than managing containers.