multi-agent-discuss README

The project's README from github.com/sjc88661/multi-agent-discuss. As one markdown file: README.md.

Multi-Agent Workbench

A local-first control room for orchestrating multiple coding agents as one disciplined team.

Status TypeScript Fastify React Node.js Tests License: MIT

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:

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:

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:

  1. Create a task with the Architecture Design template.
  2. Open the task room and pick an adapter preset from the runtime panel.
  3. Start an agent — try a Generic PTY command that prints <agent-message intent="status">Ready</agent-message> for a zero-dependency smoke test.
  4. Watch its messages land in the timeline; drill into raw output in its terminal drawer.
  5. 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

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-discuss (sjc88661/multi-agent-discuss)

Searching Database…

213 ·GitHub
Multi-agent-discuss
Что это?Multi-Agent Workbench — это локальный (local-first) центр управления для совместного запуска нескольких кодинг-агентов (вроде Claude Code и Codex CLI) под явными ролями, где рискованные действия выполняются только с вашего одобрения.
Это библиотека для импорта или приложение для запуска?Это готовое к запуску локальное веб-приложение: сервер на Node.js плюс браузерный интерфейс, а не библиотека или SDK, которые вы импортируете в свой код.
Как это запустить?Установите Node.js 20+ и npm, запустите dev-скрипты сервера и веба (`npm run dev -w apps/server`, `npm run dev:web`), затем откройте приложение и создайте комнату задач по одному из встроенных шаблонов, чтобы запустить агента.
Нужен ли заранее API-ключ или установленный кодинг-агент?Ни аккаунт, ни API-ключ не нужны, потому что всё работает локально. Чтобы оркестрировать настоящего агента, нужен установленный Codex CLI или Claude Code, либо можно проверить весь поток универсальной PTY-командой без зависимостей.
Полностью ли оно изолирует то, что агенты могут сделать с моим репозиторием?Пока не полностью — авторы адаптеров открыто признают, что перехват одобрений не является полноценной песочницей, а изоляция каждого агента в git worktree с ревью диффов в роадмапе всё ещё помечена как 'in progress'.
Куда уходят мой код и данные чатов?Никуда, кроме вашей машины: нет ни аккаунтов, ни облачной синхронизации, ни телеметрии — журнал событий лежит в локальном хранилище SQLite, а агенты работают в локальных git worktree.
Каких кодинг-агентов реально можно подключить прямо сейчас?Универсальные PTY CLI, Codex CLI и Claude Code (через claude-cli) уже поставляются и работают. GLM CLI, мосты к редакторам в стиле Cursor и облачные агенты в духе Harness запланированы, но пока недоступны.
Зачем логировать всё событиями вместо обычной базы данных?Событийный журнал, в который можно только дописывать, — единственный источник истины: он даёт полный журнал аудита, восстановление после сбоя повторным проигрыванием журнала и отделяет шумный сырой вывод терминала от читаемой шкалы чата.
Какие роли можно назначать агентам?Из коробки идут шесть ролей — Orchestrator, Architect, Implementer, Reviewer, Researcher и Summarizer — каждая определена как редактируемая YAML-карточка роли под версионным контролем с настоящими разрешениями.
Как мои файлы защищены от агента, который ведёт себя плохо?Агенты, пишущие код, работают внутри изолированных git worktree, и их изменения попадают в основное рабочее пространство только через процесс ревью с допусками по уровню риска (одобрить, отклонить или изменить).
What are similar projects?openrig, hyperfide, emdash, buzz, turnstone, agent-orchestrator, gastown, agent-weave
Which topics is it in?pty, event-sourcing, sse, git-worktrees, event-driven, audit-log, codex-cli, multi-agent-systems, yaml, coding-agents, sandbox, orchestration
Creator
sjc88661
Size
0.2 MB
Stars
213
Updated
CommitSep 10
Age
2mo
Commits · 90 Days