XYZZY

XYZZY is an open-source multi-agent platform for team collaboration scenarios, with the core goal of letting multiple humans and multiple AI agents work together in the same "room" while preserving complete work evidence.

Purpose and Positioning Modern AI tools are often a "single-player game": one person, one conversation, one context. But real work happens in teams. XYZZY treats collaboration as a first-class citizen, letting multiple participants share the same event history, artifacts, tasks, and decisions, persisted to SQLite and driven by WebSocket for real-time synchronization. Agents can produce results in parallel branches, humans select or exclude results, and an immutable decision brief and the chain of evidence behind it are ultimately published.

Main Capabilities

• Persistent rooms and event sourcing: every operation is an ordered event, and all state is driven by the event history.
• Multi-agent orchestration: supports spawning, pausing, resuming, and redirecting agents, as well as delegating tasks between agents.
• Human in the loop: agents' operations must request and await human approval or rejection before execution.
• Artifact version management: can create artifacts such as documents and code and maintain versions.
• File attachments: supports uploading images to messages, limited by XYZZY_MAX_ATTACHMENT_BYTES.
• Selective synthesis: explicitly include or exclude agent outputs, publishing an immutable decision brief.
• Evidence ontology: typed, reviewable Decision → Claim → AgentOutput relationships.
• Finite-element reasoning: permission-aware "why" and decision-evidence answers, supporting precise drill-down.
• Decision tracking: records and audits architecture and product decisions.
• Shared memory: room-level, workspace-level, and organization-level memory.
• Real-time collaboration and reconnection: WebSocket broadcasts all room events; on reconnection, provides a full state snapshot plus incremental event replay.
• Governance and provability: operations wait for human approval before execution; the room event log uses a hash chain, and tampering with or deleting a row breaks all subsequent hashes, verifiable via the audit CLI. Decisions link to underlying Claims and AgentOutputs, and synthesis results can be drilled down to specific runs.
• Optional NEXUS integration: adapts the lightweight agent runtime NEXUS to multi-person contexts via NexusAgentBridge, providing capabilities such as AgentExecutor, Budget, PolicyEngine, and StateStore; enabled by setting XYZZY_NEXUS_PATH, and when not set, the bridgeConnect to a directly run configured model provider.

How to use Running locally requires Python 3.11 or higher; the database is a file, so no service needs to be started in advance. There are corresponding installation commands for macOS/Linux and Windows PowerShell; the demo workspace can also be run with Docker. Demo mode requires no account and no configuration; with one click you enter a workspace that is already in the middle of decision-making: it includes channel conversations, a branch with two expert outputs for comparison, and a published decision brief with a complete evidence chain. When the demo has no API key configured, the expert outputs and brief will show a clearly marked "SIMULATED workflow output", but the collaboration mechanism is the same.

In terms of configuration, except for /api/v1/health and several pre-credential OIDC endpoints, all /api/v1 routes require a Bearer token. Credentials are stored in the database and kept hashed, one per token row, and can be revoked without restarting; the operator CLI can mint and revoke credentials. XYZZY_LOCAL_MODEL_BASE_URL can be set to point experts to any OpenAI-compatible chat-completions server (such as Ollama, LM Studio, vLLM, llama.cpp server); this setting takes precedence over OPENAI_API_KEY. Model credentials are not accepted from API requests, are not written to SQLite, and are not included in agent output.

Use cases Suitable for scenarios where a team needs to make technical or product decisions together with multiple AI agents and wants to preserve an auditable evidence chain. Also suitable for teams that want to run locally or on their own infrastructure and use local models instead of hosted APIs.

Limitations and notes

• The hash chain can only prove that the log is internally consistent; it cannot distinguish an honest history from a complete rewrite by the holder of the database file.
• The event log is append-only; deleting personal data cannot directly delete rows, and must be implemented through tombstone markers and content replacement.
• Single-process by default; when scaling, XYZZY_REDIS_URL must be set, and all processes must share a real local filesystem; network filesystems such as NFS/SMB are not supported.
• Rate limiting is counted per process; multi-replica deployments need to allocate budgets at the load-balancing layer.
• The current repository gate is 1,284 tests (1,283 passing, 1 skipped when OPENAI_API_KEY is absent) plus Ruff format/checkand strict mypy.
• The license is Apache 2.0.