# XYZZY

> Self-hosted multiplayer AI workspace where teams make hard technical decisions with AI agents, keeping a tamper-evident audit trail via hash-chained event logs and immutable Decision Briefs.

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.

## Features
- Persistent rooms with durable event sourcing
- Multi-agent orchestration: spawn, pause, resume, redirect, delegate
- Human-in-the-loop: request/approve/reject agent actions before execution
- Artifact versioning for documents, code, and other artifacts
- Selective synthesis: include/exclude outputs and publish immutable Decision Briefs
- Evidence ontology: typed Decision → Claim → AgentOutput relationships
- Bounded Meta: permission-aware decision-evidence answers with drill-down
- Hash-chained tamper-evident event log with audit CLI
- Shared memory: room-scoped, workspace-scoped, and org-scoped
- Real-time collaboration via WebSocket broadcasting
- Reconnect support: full state snapshot + incremental event replay
- OIDC SSO integration with session management and backchannel logout
- A2A v0.3.0 protocol support for cross-runtime agent interoperability
- Prometheus metrics endpoint
- Redis-based horizontal scaling
- Local model support via OpenAI-compatible endpoints (Ollama, LM Studio, vLLM, llama.cpp)
- Operator CLI for token minting, revocation, and user management
- Rate limiting per bearer token or peer address
- Docker and Docker Compose support with published container image

## Integrations
OpenAI API (Responses API), Ollama, LM Studio, vLLM, llama.cpp, NEXUS agent runtime, Redis (for horizontal scaling), OIDC identity providers (Keycloak and others), Google A2A protocol v0.3.0, Prometheus, Docker / Docker Compose

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/Project-Nexus-YR/XYZZY
- Documentation: https://github.com/Project-Nexus-YR/XYZZY#readme
- Repository: https://github.com/Project-Nexus-YR/XYZZY
- EveryDev.ai: https://www.everydev.ai/tools/xyzzy