Contributing

Set up Matrix OS for development, understand repository conventions, run the relevant checks, and contribute changes through the project review workflow.

Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.

Getting Set Up

Fork and clone

Terminal

git clone https://github.com/hamedmp/matrix-os.git
cd matrix-os

Install dependencies

Terminal

corepack enable && corepack prepare pnpm@latest --activate
pnpm install

Verify your environment

Terminal

bun run test     # Should pass 993+ tests
bun run dev      # Gateway on :4000, Shell on :3000

Development Rules

TDD: Write failing tests first, then implement (Red -> Green -> Refactor)
TypeScript strict mode: No any types, full type safety
ES modules: "type": "module" everywhere
Minimal comments: Code should be self-documenting
Production topology: customer runtime is per-user VPS with host services and local Postgres, not the legacy shared user-container path
No emojis in code or docs unless explicitly requested
Kysely/PostgreSQL for all database access
pnpm for installing, bun for running scripts

Commit Conventions

All commits and PR titles use Conventional Commits:

Prefix	Use
`feat:`	New feature
`fix:`	Bug fix
`test:`	Adding or updating tests
`refactor:`	Code restructuring (no behavior change)
`chore:`	Dependencies, tooling, config
`ci:`	CI/CD changes
`docs:`	Documentation
`perf:`	Performance improvement

Commit messages should be concise and focus on why, not what.

Spec-Driven Development

Major features start with a spec in specs/. Each spec directory contains:

spec.md -- architecture document describing the design
tasks.md -- task breakdown with IDs (e.g., T100-T105)

The spec numbering follows a sequential scheme:

Text

specs/003-architecture/   # Phase 3 (archive)
specs/004-concurrent/     # Phase 7: Multiprocessing
specs/005-soul-skills/    # Phase 9: SOUL + Skills
specs/006-channels/       # Phase 10: Multi-channel
...
specs/031-desktop-customization/  # Desktop theming

Read existing specs to understand the pattern before proposing new features.

Coordination Rules

When working on a spec:

Avoid modifying files outside your spec scope without lead approval
Shared files (ipc-server.ts, config.json, prompt.ts, server.ts) -- new additions should be additive, never modify existing structures
All tests must pass before declaring a task complete
Commit after each completed task group with descriptive messages

Keep the system prompt lean

The kernel system prompt must stay under 7K tokens. Use skills (demand-loaded) and knowledge files instead of bloating the base prompt.

Project Structure

Text

packages/kernel/     # AI kernel (Agent SDK, agents, IPC, hooks, SOUL, skills)
packages/gateway/    # Hono HTTP/WebSocket gateway + channels + cron + heartbeat
packages/platform/   # Control plane: Clerk auth, VPS provisioning/routing, integrations
shell/               # Next.js 16 web desktop (one of many shells)
www/                 # matrix-os.com website
home/                # File system template (copied on first boot)
tests/               # Vitest test suites (993+ tests)
specs/               # Architecture specifications
distro/              # customer VPS, cloudflared, systemd, and local dev configs

Environment Variables

Variable	Default	Description
`ANTHROPIC_API_KEY`	--	Required for kernel AI features
`MATRIX_HOME`	`~/matrixos/`	Home directory path
`MATRIX_AUTH_TOKEN`	--	Bearer token for web shell auth
`PORT`	`4000`	Gateway port
`NEXT_PUBLIC_GATEWAY_WS`	`ws://localhost:4000/ws`	Shell WebSocket URL
`NEXT_PUBLIC_GATEWAY_URL`	`http://localhost:4000`	Shell HTTP URL

Releases

Tags follow SemVer with v prefix (v0.1.0, v0.2.0). Pre-1.0: minor = features, patch = fixes.

Terminal

bun run test                                          # verify
git tag -a v0.X.0 -m "Description"                    # tag
git push origin v0.X.0                                # push tag

On this page