<p align="center">
  <img src="docs/design/assets/chip.svg" width="56" alt="musterd" />
</p>

**Agents that work as a team alongside you.**

Agents and the people they work with are named members of one team. The record shows what landed and who stands behind it: every piece of work names who did it and who accepted it.

Your agents and the people you work with join one team as named members — across any harness, framework, model, or surface. Humans are first-class members, not approvers. Every act on the roster carries a member's name, and who occupies a seat is what the harness observed, not what the agent declared. A member can decline, and a lane records who claimed it, which model did it, and who accepted it. The record shows the chain. musterd names the work that goes through the team; it does not contain the agent.

[![license: MIT](https://img.shields.io/badge/license-MIT-E1AD01)](./LICENSE) [![mcprush security grade: A](https://img.shields.io/badge/mcprush%20security-A-E1AD01)](https://mcprush.com/musterd/musterd-mcp) · [Contributing](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · [Security](./SECURITY.md) · [Privacy](./PRIVACY.md) · [SPEC](./SPEC.md) · [Roadmap](./ROADMAP.md) · [Architecture](./docs/architecture/00-overview.md)

> Status: **v0.3, designed in the open.** Packages ship on their own semver (`npm view @musterd/cli version`) — the protocol version names the trust model, not the package release. Local-first. No account, no cloud, no phone-home. See [PRIVACY.md](./PRIVACY.md).

<!-- Demo GIF — record with: vhs docs/flagship.tape (see docs/demo.md) -->
![flagship demo: one human + two agents on three surfaces](./docs/assets/flagship.gif)

<sub>A scripted walkthrough — real server, protocol, presence, and CLI rendering; the agents' lines are scripted. See [docs/demo.md](./docs/demo.md) for the [full cut](./docs/assets/flagship-full.gif) and how to record the real 3-pane version.</sub>

## The wedge nobody else covers

- **MCP** connects an agent to *tools*.
- **A2A** connects an agent to another agent, *per request*.
- Neither models a **persistent team with identity, presence, and humans as peers.** That's musterd.

A **Member** is an identity, not a session. **Presence** is where that member is currently attached — a Claude Code session, a Codex session, a CLI, later an app — like a person on desktop + phone. The team server routes messages to wherever members are present; offline members get a durable **Inbox**. Coordination outlives any single task or session.

## Quickstart

<!-- GENERATED INSTALL: edit content/install.data.ts, then pnpm install:gen -->
You need Node 22 or later, and an agent tool you already use.

```bash
# 1. Install the command line tool.
npm install -g @musterd/cli
# Or with Homebrew: brew install SandRiseStudio/musterd/musterd

# 2. Run it in your project’s folder.
cd your-project
musterd init

# 3. Start a chat with your agent there, then take the tour.
musterd tour
```
<!-- /GENERATED INSTALL -->

`musterd init` is the one-command path: it finds the agent tools you already use (Claude Code, Codex, Cursor, OpenCode, Grok), asks if it can configure the musterd MCP server for you, then shows a live spinner that flips to `● Ada is online via claude-code` the instant your agent connects. Then it offers a five-minute tour (`musterd tour`): you give your agent a small lane, judge what comes back, and read the record it leaves.

Then bring your work in: ask your agent to **"bring this repo's work into musterd"**. Its `musterd-import` skill reads the repo (and its GitHub issues, if `gh` is signed in), writes a file of goals and lanes, and shows you `musterd import`'s preview. Nothing is created until you say yes and it runs `musterd import save`. You can also fill in a CSV yourself — see `musterd help import`.

To give each member a job, from a built-in role like `designer` or one you build yourself, see [Give your agents a role](https://musterd.io/docs/roles).

> Claude Code is registered at its **project-local scope** (keyed by the folder), so it works whether you use the **terminal** (`claude`) or the **editor extension** in VS Code / Cursor — just open that same folder and start a new chat (reload the window if it was already open; check with `/mcp`).

Any MCP-capable harness joins by running the **`@musterd/mcp`** adapter with the member's environment (`musterd init` writes it for the harnesses it finds) — its agent becomes a Member with the team tools — the six core (`team_join`, `team_leave`, `team_send`, `team_inbox_check`, `team_status`, `team_members`) plus the lane, goal, seat-memory and report tools (18 total). The adapter is dormant until it calls `team_join` (explicit activation), and acting (`team_send`/`team_inbox_check`) is gated on having joined. Harness-agnosticism for free.

## Collaboration acts

Messages carry a typed **Act**, grounded in the [Co-Gym](https://arxiv.org/abs/2412.15701) collaboration-act taxonomy — not ad-hoc text:

`message` · `status_update` · `request_help` · `handoff` · `accept` · `decline` · `wait` · `resolve` · `steer` · `challenge` · `defer`

`resolve` closes a thread when its work is done — the open-vs-done axis that makes threads computable as work items. Typed acts and durable inboxes are the point: [MAST](https://arxiv.org/abs/2503.13657) found ~**79% of multi-agent failures are coordination failures** — lost context in handoffs, misalignment — not capability failures. musterd is exactly that coordination layer: explicit identity, durable inboxes, typed acts instead of improvised handoffs.

## Principles

> The bet that agents-as-teammates beats agents-as-tools is empirical, not just stylistic: in controlled study, collaborative agents beat fully autonomous ones on real-user preference (86% / 74% / 66% across three tasks), and removing the notification protocol — forcing turn-taking — more than halves the win rate. See [`research-foundation.md`](./docs/design/research-foundation.md) (Co-Gym, [arXiv:2412.15701](https://arxiv.org/abs/2412.15701)).

1. **Humans are members, not approvers.** Same envelope, same acts, same inbox as agents — no bolted-on "human-in-the-loop" mode.
2. **An agent is an identity, not a session.** Sessions come and go; the member persists. Presence is where you are, not who you are.
3. **Teams are persistent.** Coordination outlives any single task or session.
4. **Protocol over framework.** We don't run your agent — we connect it. Small core, adapters at the edge.
5. **One member does the work; the team does the coordination.** Multi-agent isn't magic — gains over a single strong agent are often marginal, and most failures are coordination failures. musterd never forces decomposition: a team of one agent (plus optionally a human) is first-class, even default. Add members for true parallelism, separate surfaces, or human collaboration — not to split tasks for its own sake.
6. **Local-first.** SQLite + a local daemon. No account, no cloud required to use it. Telemetry is off until you point an OTLP endpoint; the product does not phone home ([PRIVACY.md](./PRIVACY.md)).
7. **Secure by default.** Identities are claimed, not assumed: occupying a seat takes an authorized, audited step, and the safe defaults (live approval, least-privilege credentials, dormant sessions) are the defaults — convenience is an explicit opt-in. _(The seat/grant model — agent key + admin grants + human credentials — shipped in v0.3: [`membership-model.md`](./docs/design/membership-model.md), [`security.md`](./docs/design/security.md), [SPEC Appendix A](./SPEC.md).)_

   The boundary is explicit: musterd does not yet sandbox agent tools, encrypt its SQLite database at rest, use mTLS, or sign its audit log. See [SECURITY.md](./SECURITY.md) for supported versions, private vulnerability reporting, and the current security boundary.

## How it fits with MCP, A2A, Fleet, CrewAI

| | what it is | musterd's relation |
|---|---|---|
| **MCP** | agent ↔ tools | musterd *uses* MCP as its universal join adapter; it is not a tool server |
| **A2A** | agent ↔ agent, per-request | musterd adds the *persistent team*: identity, presence, durable inbox, humans as peers |
| **Fleet / orchestrators** | run & schedule agent fleets | musterd doesn't run agents; it's the coordination membrane they talk through |
| **CrewAI / frameworks** | build a multi-agent app in one framework | musterd is cross-framework: members join over MCP or the WS/HTTP protocol, whatever harness they live in |

## Packages

| package | what |
|---|---|
| [`@musterd/cli`](./packages/cli) | the CLI + daemon launcher (human surface); installs the `musterd` command |
| [`@musterd/server`](./packages/server) | the team server: SQLite store, WS + HTTP API, presence + inbox |
| [`@musterd/mcp`](./packages/mcp) | the universal harness adapter (one MCP server, 18 tools) |
| [`@musterd/protocol`](./packages/protocol) | shared types + zod schemas — the wire contract |
| [`@musterd/telemetry`](./packages/telemetry) | shared OTLP bootstrap for server, MCP, and CLI |

The protocol is the only thing imported across boundaries; the server is replaceable by anything that speaks `SPEC.md`.

## Glossary

**Team** — a named, persistent group of Members; a standing roster, not a project (reused across folders). **Member** — a durable identity (`agent`/`human`), not a session. **Presence** — where a Member is currently attached. **Surface** — a kind of place a Member can be present (`cli`, `claude-code`, `codex`, …). **Act** — the typed intent of a message. **Workspace** — where a Member stands: **every member stands in a Workspace of their own**, `~/musterd/<team>/<repo>/<member>` (ADR 447). `musterd agent <name>` gives an agent an isolated workspace backed by a `git worktree` (it writes code); `musterd human <name>` gives a person one the same way (what they need is somewhere their identity resolves, so `musterd board` and `musterd send` are simply them, with no `--as` and nothing pasted). The team root `~/musterd/<team>` is the roof over that team's trees and holds no identity. (Canonical definitions: [`docs/design/brand.md`](./docs/design/brand.md) §5; the four-layer model: [`docs/design/install-topology.md`](./docs/design/install-topology.md).)

## Development

```bash
pnpm install
pnpm -r build
pnpm test            # unit + integration + scenarios
pnpm test:scenarios  # the flagship 3-pane scenario (Scenario C)
```

Contributors and implementing agents: start with [`CONTRIBUTING.md`](./CONTRIBUTING.md), then [`AGENTS.md`](./AGENTS.md) and [`docs/architecture/00-overview.md`](./docs/architecture/00-overview.md). The docs are prescriptive and the deviation/ADR protocol is enforced — docs and code never disagree at the end of a commit.

Changes land through **one enforced git workflow** ([ADR 106](./docs/decisions/106-unified-git-workflow.md)): branch from `main`, open a PR, and squash-merge once the `gates` CI is green — `main` is protected (PR-only, linear history). The playbook is in [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`AGENTS.md`](./AGENTS.md).

## License

[MIT](./LICENSE).