Matrix OS Documentation
The AI operating system where software writes itself.
Matrix OS is an AI-native operating system built on the Claude Agent SDK. You describe what you need in natural language -- it writes the software, saves it as files you own, and runs it on your desktop.
Built on Claude Agent SDK
The Agent SDK's query() with resume IS the kernel. Five specialized agents handle building, researching, deploying, healing, and evolving the system. Everything is persisted as files in ~/matrixos/.
Quick Start
Clone and install
git clone https://github.com/hamedmp/matrix-os.git
cd matrix-os && pnpm installSet your API key
export ANTHROPIC_API_KEY=sk-ant-...Choose Your Path
Getting Started
Prerequisites, installation, and your first conversation with the AI kernel.
Agent System
The five core agents, SOUL identity, and the skills system.
Architecture
How the kernel, gateway, dispatcher, and shell fit together.
IPC Tools & Hooks
The 26 tools agents use to interact with the system, and the hook lifecycle.
Core Principles
Everything Is a File
Apps, config, agents, skills, themes, SOUL identity -- all stored as real files in ~/matrixos/. Back up your OS by copying a folder.
Agent Is the Kernel
Claude Agent SDK query() with resume IS the kernel. Every user action flows through AI agents that understand context and take action.
Headless Core, Multi-Shell
The core works without a UI. The web desktop, Telegram, WhatsApp, Discord, Slack, and CLI are all shells that connect to the same kernel.
Self-Healing and Self-Expanding
The Healer agent detects and repairs failures from git snapshots. The Evolver agent creates new agents, skills, and capabilities on demand.
Architecture at a Glance
Web 4 Vision
Matrix OS is the foundation for Web 4: your AI runs on all your devices, syncs via peer-to-peer git, communicates through federated identity (@you:matrix-os.com), and your AI agent has its own identity (@you_ai:matrix-os.com) that negotiates with other AIs on your behalf via the Matrix protocol.
Read the full Web 4 vision.
More Resources
- DeepWiki -- AI-generated documentation from source code
- GitHub -- Source code and issues
- Whitepaper -- The full Web 4 vision
How is this guide?