Matrix OS

The AI operating system where software writes itself.

Matrix OS is an AI-native operating system where software doesn't exist until you need it. You speak, and applications materialize -- generated in real time, saved as real files, yours to keep, inspect, and modify. The AI isn't a feature bolted onto the side. It IS the kernel.

Matrix OS at the Claude Code Birthday Party at Anthropic HQ (Feb 2026) -- Top 20 finalist

Built for the Anthropic "Built with Opus 4.6" Hackathon (Feb 10-16, 2026) where it placed in the top 20. Now being built into a production-ready platform. The entire system -- kernel, shell, platform, website, and this README -- was written with Claude Code.

---

The Idea

Every OS you've ever used works the same way: someone wrote the software months before you touched it. They decided what it looks like, what it does, what you're allowed to change.

Matrix OS starts from a different premise: what if the software didn't exist until the moment you needed it?

You open Matrix OS and see a clean surface. You tell it what you need, and the system writes it into existence. Not a template. Not a widget from a library. Real software, generated for you, tailored to your request, saved as files you own.

And it goes further. Matrix OS is also your personal AI assistant, your messaging platform, your social network, and your game console -- unified under one identity, one file system, one AI kernel. We call this Web 4.

Terminal (1970s) -> GUI (1980s) -> Web (1990s) -> Mobile (2000s) -> AI Assistants (2020s)
  -> Matrix OS / Web 4 (2026)

---

What It Does

Generate apps from conversation. Say "I need an expense tracker" and a fully functional expense tracker appears on your desktop -- styled to your theme, persisted to your file system, ready to use.

5 specialized agents. Builder generates apps. Researcher gathers information. Deployer ships modules. Healer detects and fixes failures. Evolver grows new capabilities.

Self-healing. Break something? The OS detects the problem, diagnoses it, and repairs it automatically.

Self-expanding. The OS writes its own capabilities. New agents, new skills, new tools -- all generated on demand.

Multi-channel. Talk to your OS from the web desktop, Telegram, WhatsApp, Discord, or Slack. Same kernel, same identity, same file system.

Voice interface. Talk to your OS with voice -- text-to-speech, speech-to-text, and telephony support via Twilio. Multiple TTS providers (Edge TTS, ElevenLabs, OpenAI) with automatic fallback.

Finder-class file browser. Full file management with column view, preview panel, inline rename, trash with restore, search (filename + content), and drag-and-drop.

Social network. Profiles, posts, comments, likes, follows, and activity feeds. Built on Postgres with real-time updates. Foundation for federated social via Matrix protocol.

Messages. Real-time messaging built on Matrix protocol with Conduit homeserver integration.

IDE-grade terminal. Split panes, multiple tabs, integrated Claude Code sessions, and layout persistence.

Canvas desktop. Infinite pan/zoom workspace with app grouping, minimap, and spatial organization.

Proactive. Cron jobs, heartbeats, scheduled tasks. The OS doesn't just respond -- it anticipates.

SOUL identity. Every instance has a personality defined in ~/system/soul.md. It shapes how the AI thinks, communicates, and acts.

20 built-in skills. Summarize, research, budget tracking, image generation, web search, code review, and more. Users can create their own skills from conversation.

Personalized onboarding. Conversational setup adapts to your role (student, developer, entrepreneur). Proposes apps, skills, and personality. Builds everything after confirmation.

Desktop customization. 6 theme presets, custom backgrounds (patterns, gradients, wallpapers), configurable dock, AI-generated app icons.

Observability. Prometheus metrics for gateway, platform, and proxy. Ready for Grafana dashboards and alerting.

Cloud-native + Multi-tenant. Sign up at matrix-os.com, get your own instance at yourname.matrix-os.com. Each user gets an isolated Docker container with persistent storage.

Documentation site. Public docs at matrix-os.com/docs built with Fumadocs.

---

Architecture

Browser (localhost:3000)              Telegram / WhatsApp / Discord / Slack
  |-- Next.js shell (desktop UI)        |-- Channel adapters
  |                                     |
  +------------- Gateway (localhost:4000) ---------------+
                  |-- WebSocket (chat, file watcher, terminal, voice)
                  |-- REST API (messages, files, social, themes, layout)
                  |-- Channel manager, cron, heartbeat
                  |-- Prometheus metrics (/metrics)
                  |
                  +---> Dispatcher ---> Kernel (Claude Agent SDK)
                                          |-- Builder agent (generates apps)
                                          |-- Researcher agent (gathers info)
                                          |-- Deployer agent (ships modules)
                                          |-- Healer agent (fixes breakage)
                                          |-- Evolver agent (grows the OS)

The core metaphor maps precisely to computer architecture:

Computer	Matrix OS
CPU	Claude Opus 4.6
RAM	Agent context window
Kernel	Main agent with tool access
Processes	Sub-agents via Task tool
Disk	File system (~/apps, ~/data, ~/system)
System calls	26 IPC tools via MCP server
Device drivers	MCP servers
IPC	File-based coordination + SQLite task queue

The Web 4 Vision

Matrix OS is the foundation for Web 4 -- a unified platform where your OS, messaging, social media, AI assistant, apps, games, and identity are all one thing.

• Federated identity via Matrix protocol: @you:matrix-os.com (human) + @you_ai:matrix-os.com (AI agent)
• AI-to-AI communication: your AI talks to other AIs via Matrix rooms with custom event types
• Peer-to-peer sync: git is the sync layer -- all devices are equal peers
• App marketplace: apps are files -- distribution is file sharing
• Multiplayer games: generate games from conversation, play against humans or AIs
• E2E encrypted: Olm/Megolm encryption on all AI-to-AI and human-to-human communication

---

Tech Stack

Layer	Technology
Language	TypeScript 5.5+, strict mode, ES modules
Runtime	Node.js 24+
AI	Claude Agent SDK V1 (query() + resume), Opus 4.6
Frontend	Next.js 16, React 19
Backend	Hono (HTTP/WebSocket gateway)
Database	SQLite via Drizzle ORM (kernel), Postgres via Kysely (social/app data)
Channels	node-telegram-bot-api, @whiskeysockets/baileys, discord.js, @slack/bolt
Federation	Matrix protocol (matrix-js-sdk), Conduit homeserver
Voice	Edge TTS, ElevenLabs, OpenAI TTS/Whisper, Twilio
Validation	Zod 4
Observability	Prometheus metrics (prom-client)
Testing	Vitest (2,807 tests, TDD, 214 test files)
Package mgr	pnpm (install), bun (scripts)

---

Project Structure

packages/kernel/     # AI kernel (Agent SDK, agents, IPC tools, hooks, SOUL, skills)
packages/gateway/    # Hono HTTP/WebSocket gateway + channels + cron + heartbeat + voice
packages/platform/   # Multi-tenant orchestrator (Hono :9000, Drizzle, dockerode, social API)
packages/proxy/      # Shared API proxy (Hono :8080, usage tracking)
shell/               # Next.js 16 frontend (desktop shell, file browser, terminal, canvas)
www/                 # matrix-os.com + /docs (Next.js on Vercel, Clerk auth, Fumadocs)
home/                # File system template (apps, agents, skills -- copied on first boot)
tests/               # Vitest test suites (214 files)
specs/               # Architecture specs (35+ specs)
docs/                # Reference documentation
distro/              # Docker, cloudflared, systemd deployment configs

---

Getting Started

Prerequisites

• Node.js 24+
• pnpm (corepack enable && corepack prepare pnpm@latest --activate)
• ANTHROPIC_API_KEY environment variable

Install

pnpm install

Run Tests

bun run test              # 2,807 tests (~35s)
bun run test:watch        # Watch mode
bun run test:integration  # Integration tests (needs API key, uses haiku)
bun run test:coverage     # Coverage report

Start Development

# All at once (gateway + shell):
bun run dev

# Or individually:
bun run dev:gateway   # Gateway on http://localhost:4000
bun run dev:shell     # Shell on http://localhost:3000

Docker Development (Primary)

Requires OrbStack on macOS.

bun run docker          # Dev only (gateway + shell with HMR)
bun run docker:full     # + proxy, platform, conduit
bun run docker:all      # + observability (Grafana, Prometheus, Loki)
bun run docker:stop     # Stop all containers (preserves data)
bun run docker:logs     # Tail dev container logs
bun run docker:shell    # Shell into container

The gateway boots the home directory at ~/matrixos/ on first run.

Environment Variables

Variable	Description	Default
ANTHROPIC_API_KEY	Required for AI features	--
MATRIX_HOME	Home directory path	~/matrixos/
MATRIX_HANDLE	User handle	dev
MATRIX_AUTH_TOKEN	Bearer token for cloud auth	--
PORT	Gateway port	4000
FAL_API_KEY	AI icon generation (fal.ai)	--
DATABASE_URL	Postgres connection (social/app data)	--

---

Current Status

2,807 tests passing across 214 test files. 100K+ lines of TypeScript. Platform is live at matrix-os.com.

Completed

• Phases 1-6: Core OS -- monorepo, kernel (Agent SDK V1 query+resume), IPC MCP server (26 tools), 8 hooks, Hono gateway, Next.js desktop shell, self-healing, self-evolution
• Phase 7: Concurrent kernel dispatch -- serial queue, maxConcurrency, process registration
• Phase 8: Cloud deployment -- single-user Docker + multi-tenant platform (dockerode, Clerk auth, Cloudflare Tunnels, admin dashboard)
• Phase 9: SOUL identity + skills + observability -- 20 skills, handle registry (@user:matrix-os.com), interaction logger, safe mode, git sync, mobile responsive, PWA
• Phase 10: Multi-channel messaging -- Telegram adapter, channel-aware dispatcher, formatForChannel
• Phase 11: Cron + Heartbeat -- CronService, CronStore, manage_cron tool, HeartbeatRunner
• Phase 12: Onboarding -- persona engine (7 roles), setup plan, provisioner, Mission Control, Cmd+K palette
• Phase 25: Security hardening -- content wrapping, SSRF protection, audit tool
• Phase 31: Desktop customization -- 6 themes, backgrounds, dock config, AI-generated icons
• Phase 33: Docume