Multi-Agent Workbench
A local-first control room for orchestrating multiple coding agents as one disciplined team.
Run one agent, you get a chatbot. Put several agents with real roles in the same room — and gate their actions behind your decisions — you get a team.
Multi-Agent Workbench is the room.
The Problem
CLI coding agents are powerful, but each one is a lonely terminal: you prompt, it works, you review, repeat.
Chaining them means copy-pasting context, losing track of who decided what, and trusting an agent to edit your
repository without any guardrails.
Multi-Agent Workbench turns that into a structured collaboration system:
- One room, many agents — Claude Code, Codex CLI, generic PTY CLIs, and (soon) GLM/Cursor/Harness-style agents work side by side under explicit roles.
- Roles with teeth — each agent is bound to an editable role card that defines its permissions, speaking style, and decision boundaries.
- Your decisions are the gates — an orchestrator drives the flow, but execution, risky commands, and merges stop at you.
- Everything is recorded — an append-only event log is the source of truth, so every message, decision, approval, and diff is auditable and replayable.
- Your repo stays safe — code-writing agents work inside isolated git worktrees, and changes reach your main workspace only through a review flow you control.
Local-first by design: no accounts, no cloud, no telemetry. It runs on your machine, against your project, with files you can read.
What's in the Box
| Capability |
Status |
Details |
| 🗣️ Task Rooms |
✅ shipped |
Browser-based rooms with goal, members, timeline, decisions, approvals, artifacts |
| 🤖 Persistent PTY agents |
✅ shipped |
Long-lived agent sessions that survive UI refreshes, with status tracking and raw terminal logs |
| 🧩 Agent-agnostic adapters |
✅ shipped |
generic-pty, codex-cli, claude-cli with automatic command discovery; registry extensible via a documented interface |
| 👥 Role cards & task templates |
✅ shipped |
Human-readable YAML files — 6 roles, 4 templates, editable and versionable |
| ⚙️ Orchestrator with decision gates |
✅ shipped |
Rule-driven engine raises blocking decision requests before execution; pluggable strategy layer |
| 🛡️ Risk-based approvals |
✅ shipped |
Low/medium/high risk classification with approve / reject / modify resolution and full history |
| 🌳 Worktree isolation & diff review |
🔶 in progress |
One git worktree per executing agent, diff-stat scanning, patch/merge review flow |
| 📦 Durable artifacts |
✅ shipped |
Markdown task reports, decision logs, patches — written as readable files, not just database rows |
| ⚡ Real-time updates |
✅ shipped |
SSE event streaming from the backend to every open room |
| 🔍 Event sourcing |
✅ shipped |
23 event types, projected into timeline, decisions, terminals, artifacts, and diff views |
Architecture
A local event-driven stack. The browser never touches a PTY directly — every action goes through the API,
is recorded as an event, and is projected into views.
flowchart LR
subgraph Browser
UI[React Workbench UI]
end
subgraph Server["Fastify Backend (127.0.0.1:3020)"]
API[REST API]
SSE[SSE Realtime Broker]
ORCH[Orchestrator Engine]
SESS[PTY Session Manager]
ADAPT[Agent Adapter Registry]
APPR[Approval Service]
WORK[Worktree Manager]
ART[Artifact Service]
CFG[Role & Template Registries]
end
DB[(SQLite Event Store)]
PTY[Persistent PTY Processes]
WT[Isolated Git Worktrees]
FILES[Markdown Artifacts]
UI <--> API
UI <--> SSE
API <--> DB
API <--> CFG
SSE <--> DB
ORCH --> SESS
SESS --> ADAPT
ADAPT --> PTY
PTY --> DB
ORCH <--> APPR
APPR <--> UI
WORK --> WT
WORK --> DB
ART --> FILES
ART --> DB
Why event sourcing?
The event log is the single source of truth. Raw PTY output, agent messages, decisions, approvals, worktree
updates, and artifacts are all append-only events. The UI state you see — the chat timeline, the pending
decisions, the terminal drawers — is derived, not stored. That gives you:
- A complete audit trail — reconstruct why a change happened, not just what changed.
- Crash recovery — platform state rebuilds from the log; crashed agent sessions restart with an injected summary.
- Separation of signal and noise — raw terminal traffic is recorded but projected into drawers, keeping the timeline readable.
Agent Compatibility
Adapters turn wildly different agent systems into one common interface: start command, input formatting,
output parsing, capabilities, and lifecycle.
| Adapter |
Agent |
Kind |
Maturity |
Notes |
generic-pty |
Any terminal CLI |
pty-cli |
✅ MVP |
Configure any command; use for scripts, fake agents, or CLIs without a dedicated adapter |
codex-cli |
Codex CLI |
pty-cli |
✅ MVP |
Auto-discovers codex/codex.exe; structured <agent-message> output |
claude-cli |
Claude Code |
pty-cli |
✅ MVP |
Auto-discovers claude/claude.exe; structured <agent-message> output |
glm-cli |
GLM CLI |
pty-cli |
🗓️ Planned |
Waiting on a stable local command and IO contract |
cursor-agent |
Cursor-style agents |
editor-bridge |
🗓️ Planned |
Requires a local bridge contract |
harness-agent |
Harness-style agents |
cloud-api |
🗓️ Planned |
Requires API credentials and a remote lifecycle model |
Adapters declare capabilities honestly — including that approval interception is not yet a complete sandbox.
Isolation, audit logs, and visible terminal output are the current safeguards. Full details in
docs/agent-compatibility-matrix.md.
Roles, Templates, and Structured Speech
Agents don't free-chat into the void. They speak a structured protocol — group-chat for humans,
typed events for the platform:
<agent-message intent="proposal">
We should extract the adapter registry behind an interface before adding the GLM adapter.
</agent-message>
Role cards are plain YAML with real permissions:
id: reviewer
name: Reviewer
description: Finds risks, contradictions, missing tests, and unsafe assumptions.
permissions:
can_edit_files: false
can_request_decision: true
can_execute_commands: false
speaking:
default_intents: ["critique", "risk", "question"]
verbosity: concise
Six roles ship out of the box — Orchestrator, Architect, Implementer, Reviewer, Researcher, Summarizer —
plus four task templates: Architecture Design, Code Implementation, Code Review, and Research Discussion.
Because everything is YAML, you can version your team's roles like code.
Quick Start
Prerequisites: Node.js 20+, npm, and (optionally) a real CLI agent such as Codex CLI or Claude Code.
# 1. Install dependencies
npm install
# 2. Start the backend (Fastify API on 127.0.0.1:3020)
npm run dev
# 3. In a second terminal, start the web app (Vite on 127.0.0.1:5173)
npm run dev:web
Open http://127.0.0.1:5173 and:
- Create a task with the Architecture Design template.
- Open the task room and pick an adapter preset from the runtime panel.
- Start an agent — try a Generic PTY command that prints
<agent-message intent="status">Ready</agent-message> for a zero-dependency smoke test.
- Watch its messages land in the timeline; drill into raw output in its terminal drawer.
- Trigger a decision request, resolve it, then generate the task report and check
.multi-agent/tasks/<task-id>/report.md.
For real agents, read docs/adapter-runtime-local-setup.md first —
the workbench provides worktree-friendly runtime controls and visible logs, not a complete command sandbox.
Development commands
npm test # Vitest across the workspace
npm run typecheck # tsc project references across server, web, shared
npm run build # production build of all workspaces
Repository Layout
multi-agent-workbench/
├── apps/
│ ├── server/ # Fastify API, event store, PTY runtime, orchestrator, approvals
│ └── web/ # React + Vite workbench UI
├── packages/
│ └── shared/ # @maw/shared — event protocol, projections, API types (single source of truth)
├── docs/
│ ├── superpowers/ # design spec & MVP implementation plan
│ ├── agent-compatibility-matrix.md
│ ├── adapter-development.md
│ └── adapter-runtime-local-setup.md
└── .multi-agent/ # role cards, task templates (runtime data is gitignored)
Server modules — EventStore · TaskRoomService · SessionManager · AgentRegistry ·
RoleRegistry · TemplateRegistry · OrchestratorEngine · ApprovalService · WorktreeManager ·
ArtifactService · SseBroker
UI views — Task List · Create Task · Task Room · Agent Roster · Message Timeline ·
Decision Panel · Approval Panel · Terminal Drawer · Artifact Panel · Diff Review
Roadmap
- ✅ Phase 1 — Room skeleton · web app, API, SQLite event store, single PTY agent, live timeline
- ✅ Phase 2 — Multi-agent & roles · role/template registries, multiple agents per room, structured messages, turn assignment
- ✅ Phase 3 — Decisions & approvals · blocking decision gates, risk-based approvals, audit views
- 🔶 Phase 4 — Worktrees & diff review · per-agent worktrees, diff scanning, patch/merge flows (in progress)
- 🗓️ Phase 5 — Compatibility expansion · GLM CLI, editor bridges, cloud/platform adapters
- 🗓️ Phase 6 — Hardening · crash recovery, sandboxing, sample packs, contribution guide
Documentation
License
Released under the MIT License — an OSI-approved permissive license.
You are free to use, modify, and distribute this project for any purpose, including commercial,
as long as the copyright notice is preserved.
Copyright (c) 2026 sjc88661
Multi-Agent Workbench 是一个本地优先的控制室，用于让多个编程 agent（如 Claude Code 和 Codex CLI）在明确的角色下协同运行，执行有风险的操作之前需要你的批准。