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.
Built for the Anthropic "Built with Opus 4.6" Hackathon (Feb 10-16, 2026). The entire system -- kernel, shell, platform, website, and this README -- was written with Claude Code.
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.
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.
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.
Browser (localhost:3000) Telegram / WhatsApp / Discord / Slack
|-- Next.js shell (desktop UI) |-- Channel adapters
| |
+------------- Gateway (localhost:4000) ---------------+
|-- WebSocket (chat, file watcher, terminal)
|-- REST API (messages, files, themes, layout, settings)
|-- Channel manager, cron, heartbeat
|
+---> 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 (WAL mode) |
| Channels | node-telegram-bot-api, @whiskeysockets/baileys, discord.js, @slack/bolt |
| Federation | Matrix protocol (matrix-js-sdk) |
| Validation | Zod 4 |
| Testing | Vitest (1,012 tests, TDD, 86 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
packages/platform/ # Multi-tenant orchestrator (Hono :9000, Drizzle, dockerode)
packages/proxy/ # Shared API proxy (Hono :8080, usage tracking)
shell/ # Next.js 16 frontend (desktop shell)
www/ # matrix-os.com (Next.js on Vercel, Clerk auth)
home/ # File system template (copied on first boot)
tests/ # Vitest test suites (86 files)
specs/ # Architecture specs (31 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 # 1,012 tests (~11s)
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:3000The 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_AUTH_TOKEN |
Bearer token for cloud auth | -- |
PORT |
Gateway port | 4000 |
FAL_API_KEY |
AI icon generation (fal.ai) | -- |
1,012 tests passing across 86 test files. 40K lines of TypeScript. 18 completed phases.
- Phase 1: Monorepo, pnpm workspaces, Vitest, TypeScript strict
- Phase 2: SQLite/Drizzle schema, system prompt builder, agent parser, first-boot
- Phase 3: Kernel (Agent SDK V1 query+resume), IPC MCP server (26 tools), hooks (8 hooks), gateway (Hono HTTP+WS), 5 agent prompts
- Phase 4: Next.js desktop shell -- window management, ChatPanel, AppViewer, Dock, Terminal (xterm.js), InputBar, ResponseOverlay, state persistence, message queuing
- Phase 5: Self-healing -- heartbeat loop, healer sub-agent, backup/restore, activity log
- Phase 6: Self-evolution -- protected files hook, watchdog, evolver prompt
- Phase 7: Concurrent kernel dispatch -- serial queue, maxConcurrency, process registration, conflict avoidance
- Phase 9: SOUL identity + Skills -- soul.md, identity.md, user.md, 20 skills with frontmatter + TOC, load_skill tool
- Phase 10: Multi-channel messaging -- ChannelAdapter interface, ChannelManager lifecycle, Telegram adapter, channel-aware dispatcher
- Phase 11: Cron + Heartbeat -- CronService (interval/once/cron), CronStore, manage_cron tool, HeartbeatRunner with active hours
- Phase 12: Onboarding -- persona engine (7 roles), setup plan, provisioner, Mission Control (kanban/grid), Cmd+K command palette
- Phase 8A: Single-user cloud -- Dockerfile, docker-compose, systemd, auth middleware
- Phase 8B: Multi-tenant platform -- Hono orchestrator, Drizzle, dockerode, Clerk auth, admin dashboard, Cloudflare Tunnels
- Phase 9 P0: Observability + Safety -- interaction logger (JSONL), logs endpoint, safe mode agent
- Phase 9 P1: Identity + Sync -- handle registry (@user:matrix-os.com), profile endpoints, git sync, mobile responsive, PWA
- Phase 25: Security hardening -- content wrapping, SSRF protection, audit tool, sandbox
- Phase 31: Desktop customization -- 6 theme presets, backgrounds, dock config, AI-generated icons, settings UI
- Phase 13: Linux distro + Docker deployment
- 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, 1,012 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.