MACS

Multi-Agent Collaboration System

The terminal-native cockpit for AI-first software engineering.

简体中文 · Why · Supported AI CLIs · Architecture · Quickstart · Protocol

Why MACS

Modern software engineering is rapidly becoming a multi-agent workflow: one developer, multiple AI CLIs, dozens of concurrent contexts. Every tool ships its own prompt surface, its own state, its own handoff conventions — and the developer pays the integration tax.

MACS is the missing protocol layer between you and your agents. It does not replace Claude Code, Codex CLI, or any other agent. It provides a stable, terminal-native cockpit — a passive sidecar that discovers, displays, and dispatches work across every AI CLI you already use.

Design axiom — Discover · Display · Jump · Dispatch. MACS never owns your agents' reasoning, task ownership, or code generation. It owns the protocol fabric that makes multi-agent collaboration observable, recoverable, and repeatable.

Supported AI CLIs

MACS is built to complement the strongest AI coding tools in the ecosystem — first-class support for the pair most engineers actually run day to day:

Tool	Vendor	Integration Mode	Status
Claude Code	Anthropic	Sidecar · Inline · CLI fallback	First-class
Codex CLI	OpenAI	Sidecar · Inline · CLI fallback	First-class
Oh My Codex (OMX)	Community	Command injection · Protocol handoff	Native
Oh My Claude Code (OMCC)	Community	Command injection · Protocol handoff	Native
Gemini CLI	Google	Inline · CLI fallback	Supported
Generic AI CLI	Any	stdio · File-based handoff	Compatible

OMX and OMCC are treated as first-party collaboration partners: their slash commands ($deep-interview, $plan, $ralplan, $autopilot, $ralph, $team) are shipped as built-in shortcut templates, dispatched through the same policy-controlled injection pipeline as any other action.

Features

1. Single-keystroke cockpit

m opens — or recalls, or folds — the MACS cockpit from anywhere in your terminal. No GUI. No context loss. No leaving the pane you were in.

2. Protocol-driven collaboration

Every interaction between MACS and an agent is a versioned protocol exchange:

Read protocols — startup_snapshot, task_list, task_detail, command_catalog, long_run_status, interaction_context, selector_tree
Action protocols — claim_task, complete_task, start_long_run, run_migration, compose_handoff, request_ai_analysis

Every envelope carries protocol_version, schema_version, runtime_version, capabilities, status, fallback. That means handoffs are inspectable, diffable, and machine-consumable — not free-form prompt strings.

3. Sidecar orchestration

Inside Claude Code or Codex CLI, MACS becomes a dual-pane cockpit:

┌──────────────────────────┬──────────────────────────┐
│                          │                          │
│   AI conversation pane   │   MACS sidecar           │
│   (left / primary)       │   • task inbox           │
│                          │   • command palette      │
│   Reasoning stays here.  │   • handoff composer     │
│                          │   • selector tree        │
│                          │                          │
└──────────────────────────┴──────────────────────────┘
   ← return focus to AI       → / a  send to AI input

All dispatches follow an explicit send-policy matrix:

inject_only — default; types content into the AI input, never sends
inject_and_send — inject + submit, for vetted templates
execute_shell — opt-in only; reserved for high-trust automation

4. Graceful degradation, by design

MACS is engineered as a capability ladder, not a single UX. Missing terminal features downgrade cleanly, they never fail:

WezTerm sidecar ──▶ tmux split ──▶ inline render ──▶ handoff file ──▶ clipboard ──▶ CLI summary
       full power                                                              universal baseline

Every transport carries the same bridge contract. m doctor reports which rung you are currently on.

5. Unified command surface

m                           # toggle cockpit (open / recall / fold)
m wb                        # open the workbench explicitly
m doctor                    # diagnostics & capability report
m version --json            # release / runtime / protocol / schema alignment
m protocol startup_snapshot # structured boot diagnostics
m protocol selector_tree    # inspect safe navigation nodes
m migrate                   # upgrade current project to latest runtime
m update                    # refresh the global runtime
m nr / m nrep               # plan & report long-running agent sessions

6. Multi-layer state model

Layer	Purpose	Scope
Global router	`m` / `macs` entrypoints, host detection	Machine
Project runtime	SQLite inbox-cache, migration logs, sidecar bridge	Repository
Shared runtime	Protocol rendering, typed models, capability detection	Propagated
Protocol	Versioned envelope contract	Cross-process
Memory	`.agent-memory/` layered context (local-only)	Operator

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MACS Architecture                       │
├─────────────────────────────────────────────────────────────┤
│  L5  Cockpit UX            sidecar · inline · workbench · CLI
├─────────────────────────────────────────────────────────────┤
│  L4  Protocol Envelope     versioned · diffable · fallback-aware
├─────────────────────────────────────────────────────────────┤
│  L3  Shared Runtime        rendering · models · capabilities
├─────────────────────────────────────────────────────────────┤
│  L2  Project Runtime       SQLite inbox · migration · bridge
├─────────────────────────────────────────────────────────────┤
│  L1  Global Router         m / macs · host detect · transport
└─────────────────────────────────────────────────────────────┘

See ARCHITECTURE.md for the full layer model, source-of-truth order, Warp/AI-host boundaries, and the fallback strategy.

Quickstart

Initialize a project

bash init-macs.sh

Install globally

bash install-global-macs.sh

Use it anywhere

m                    # open the cockpit
m version --json     # verify alignment
m doctor             # verify terminal capabilities
m migrate            # sync project to latest runtime

Requirements: Python 3.10 / 3.11 / 3.12, a POSIX shell, a terminal (TTY).

Protocol surface

A minimal startup_snapshot response looks like:

{
  "protocol_version": "1.x",
  "schema_version":   "1.x",
  "runtime_version":  "0.3.x",
  "capabilities": {
    "host":      "claude-code",
    "pane":      "sidecar-capable",
    "transport": ["wezterm", "tmux", "inline", "handoff-file", "clipboard"]
  },
  "status":  "ok",
  "fallback": null,
  "payload":  { /* host-specific */ }
}

When capability drops (capabilities.pane = inline-only, missing transport, etc.), the same envelope is returned with status: "degraded" and a populated fallback branch — so callers never have to guess whether to retry or downgrade.

Repository layout

.agent/                  per-project runtime, hooks, schema, profile
macs_runtime/            reusable Python: models, contract, rendering
runtime/                 canonical protocol & workbench scripts
tests/                   regression suite (44+ unittest cases)
assets/                  branding (banner, logo)
init-macs.sh             self-contained project initializer
install-global-macs.sh   global installer
m / macs                 entrypoints

Development

# Shell validation
bash -n init-macs.sh install-global-macs.sh .agent/scripts/agent-cli.sh

# Python unit tests
python3 -m unittest discover -s tests -v

Roadmap

m / macs global + local entrypoints
Passive cockpit with CLI fallback
Protocol-driven discovery & dispatch
WezTerm-first sidecar orchestration
Dual-pane AI-CLI workbench (Claude Code & Codex CLI)
Plugin extensibility hooks (internal only; marketplace out of scope)

Philosophy

Terminal first. The terminal is the only universal IDE. MACS never asks you to leave it.
Human-perspective cockpit. Discover, display, jump, dispatch — never silently take ownership.
Protocol-driven. Every action is a versioned envelope. No free-form prompt coupling.
Fallback is a feature. Degraded mode is product behavior, not error recovery.

Contributing · Security · License

CONTRIBUTING.md — how to open issues, PRs, and release notes
SECURITY.md — responsible disclosure
CHANGELOG.md — versioned change log
MIT License

Built for the terminal. Designed for humans. Protocol-driven for agents.

multi-agent-collaboration-system

Links

README