XYZZY

XYZZY is an open-source, self-hosted multiplayer AI workspace built by Project-Nexus-YR and licensed under Apache 2.0. It lets multiple humans and AI agents share a persistent "room" — a common event history, artifacts, tasks, and decisions — backed by SQLite with WebSocket-driven real-time sync. The project is actively maintained, with a live demo available at xyzzy.yasserameur-dev.workers.dev and a Docker image published to GitHub Container Registry.

What It Is

XYZZY addresses a gap the README describes plainly: "Modern AI tools are single-player: one human, one chat, one context. Real work happens in teams." The tool creates a shared workspace where agents branch out in parallel, humans review and selectively include or exclude outputs, and the room publishes an immutable Decision Brief with a full evidence chain. It runs as a single Python process against a SQLite file, making it deployable without external services.

Architecture and Core Design

XYZZY is built on FastAPI with a layered architecture:

• Browser layer communicates via WebSocket and REST API
• Service layer handles state machines, input validation, and authorization
• RealtimeHub manages pub/sub with lock-protected mutations and queue delivery
• NexusAgentBridge adapts the optional NEXUS agent runtime for multi-agent orchestration
• Repository layer provides 16 typed repositories with atomic event sequencing
• Database layer uses aiosqlite in WAL mode with full transaction support

The event log is hash-chained — each event is hashed against the one before it — making the audit trail tamper-evident by construction. A CLI tool lets operators verify the chain at any time.

Human-in-the-Loop Governance

A defining design choice is that agent actions wait for human approval before executing. The README describes this as "governed": what an agent may do is re-read from the room's own state at the moment it acts, so revoking access or leaving a room takes effect immediately, even mid-task. Delegation chains are bounded to four levels deep, cycles are refused by name, and a delegate's authority is always the intersection of its own permissions and its asker's — re-read from durable rows at spend time.

Evidence Ontology and Decision Tracking

Every Decision links to the Claims and AgentOutputs behind it, forming a typed, reviewable Decision → Claim → AgentOutput chain. The "Bounded Meta" feature answers "why" and decision-evidence questions with permission-aware drill-down. This makes the synthesis inspectable down to the specific agent run that produced it — the README's framing of "keeps the receipts."

Deployment and Scaling

XYZZY is designed to run as a single Python process with no external service dependencies for basic use:

• Local models: supports Ollama, LM Studio, vLLM, and llama.cpp via XYZZY_LOCAL_MODEL_BASE_URL
• SSO: optional OIDC integration with configurable session management and backchannel logout
• A2A protocol: speaks Google's Agent-to-Agent (A2A) v0.3.0 for interoperability with agents built on other runtimes
• Horizontal scaling: add Redis (XYZZY_REDIS_URL) to fan out events across multiple server processes
• Observability: Prometheus metrics at /metrics, health probe at /api/v1/health

Without an OPENAI_API_KEY, the server runs a clearly labelled simulator so collaboration mechanics remain testable without a real API credential.

Current Status

The repository reports 954 passing tests covering unit, integration, concurrency, security, failure injection, and regression suites, run on every push via GitHub Actions CI. The project was created in August 2026 and last pushed in September 2026. It carries zero open issues and is published under Apache 2.0 with source fully available.