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.
Watch the demo
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.
Matrix OS at the Claude Code Birthday Party at Anthropic HQ (Feb 2026) -- Top 20 finalist
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)
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.
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 |
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
| 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) |
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
- Node.js 24+
- pnpm (
corepack enable && corepack prepare pnpm@latest --activate) ANTHROPIC_API_KEYenvironment variable
pnpm installbun 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# 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:3000Requires 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 containerThe gateway boots the home directory at ~/matrixos/ on first run.
| 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) | -- |
2,807 tests passing across 214 test files. 100K+ lines of TypeScript. Platform is live at matrix-os.com.
- 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: Documentation site -- Fumadocs at matrix-os.com/docs
- Phase 34A: Prometheus metrics -- gateway, platform, and proxy instrumentation
- Phase 35: Canvas desktop -- infinite pan/zoom, app grouping, minimap
- Phase 44: Docker-primary development -- non-root user, su-exec, identity from env
- Phase 46: Voice system -- TTS (Edge/ElevenLabs/OpenAI), STT (Whisper), telephony (Twilio)
- Phase 48: File browser -- Finder-class with column view, preview, trash, search
- Phase 50: Postgres app data layer -- Kysely, per-app schemas, bridge API
- Social: Social network -- profiles, posts, comments, likes, follows, activity feeds, messages
- Memory system (spec 052): Postgres-backed semantic memory with pgvector, interaction logging, LLM extraction
- Everything Is a File -- apps, profiles, config, AI personality -- all files. Sync = git. Share = send a file. Backup = copy a folder.
- Agent Is the Kernel -- Claude Agent SDK V1
query()withresume. The AI has full system access. It writes software, manages files, communicates with other AIs. - Headless Core, Multi-Shell -- the core is a gateway + kernel. Web shell, mobile app, Telegram bot, voice interface -- all shells.
- Self-Healing and Self-Expanding -- the OS fixes itself and grows new capabilities on demand.
- Simplicity Over Sophistication -- the simplest implementation that works.
- TDD -- tests first, 2,807 passing, targeting 99-100% coverage.
- Web 4 Vision -- the north star for the unified AI OS platform
- Matrix OS Vision -- the full product vision
- DeepWiki Documentation -- AI-generated docs for the codebase
Matrix OS. Software that doesn't exist until you need it. And once it does, it's yours.