@kl-c/matrixos

MaTrixOS

Version: 0.1.2 (Phase 7 — release-ready) | License: Proprietary KL-Consulting | Repo: private (shirofx/MaTrixOS)

MaTrixOS is an agentic OS — an orchestration layer on top of OpenCode, built as a clean fork of OMO (oh-my-openagent) v4.18.1. It extends OpenCode with 16 agents, a multi-platform messaging gateway (Telegram / Discord / WhatsApp), a business-profile system, a self-improvement learning loop, and an anti-loop watchdog for resilience.

Install

bunx @kl-c/matrixos install

The interactive setup wizard walks you through provider selection, config generation, and OpenCode plugin registration.

Runtime model (no separate platform binaries)

MaTrixOS does not publish per-platform binary packages (e.g. @kl-c/matrixos-linux-x64). The launcher (bin/matrixos.js) runs the bundled CLI directly via bun from this package's dist/cli/index.js. This keeps bunx @kl-c/matrixos install fully self-contained — no extra native binary download required. Bun 1.3+ is the only supported runtime (install: curl -fsSL https://bun.sh/install | bash).

What's in v0.1.1

16 agents

Morpheus (orchestrator) · Neo (junior) · Tank · The Oracle · The Keymaker · Agent Smith · The Operator · Ghost · Link · The Analyst · Trinity (design) · Cypher (SEO/copy) · Sentinel (QA) · Mouse (docs) · Dreamer (memory) · Architect (self-improvement).

Multi-channel messaging gateway

• Telegram (via grammy v1.44)
• Discord (via discord.js v14)
• WhatsApp (via @whiskeysockets/baileys 7 — sandbox-by-default to avoid account bans)
• Unified envelope, per-sender rate-limiting, allowlist security, append-only audit log
• Anti-loop watchdog: same (channel, sender, text) repeated ≥3 times in 10s → drops the message + audit

Business profiles + Mini-OS Generator

Define profiles per métier (trader, plombier, etc.) or generate a new one with matrixos generate <metier>. Profiles merge their own agents / skills / hooks / tools / MCPs with cycle + missing-ref detection.

Self-improvement learning loop

• matrixos apply-learnings — synthesizes .omo/rules/matrix-learnings.md from learnings.jsonl (dry-run by default, --apply to write)
• L1 permanent rules (confidence ≥ 80% AND occurrences ≥ 3) · L2 tentative (≥ 60% / ≥ 2)
• Stats the gateway audit log to propose new learnings automatically

CLI

@kl-c/matrixos install                   # Interactive setup wizard
matrixos doctor                    # Health diagnostics
matrixos boulder                   # Work-state progress inspector
matrixos apply-learnings [--apply] # Synthesize auto-learnings rule file (dry-run by default)
matrixos skill audit [--json]      # 4-scope skill audit (duplicates / broken / missing desc)
matrixos upstream check [--json]   # OMO upstream release report (read-only, no auto-merge)
matrixos refresh-model-capabilities
matrixos version

Inherited from OMO v4.18.1

• Hash-Verified Edits (LINE#ID hashes, zero corruption on stale reads)
• Team Mode (lead + up to 8 parallel members, opt-in via team_mode.enabled)

Quality

• bun run typecheck — clean globally (0 error, 0 warning)
• bun test — 9801 pass / 76 fail (76 pre-existing OMO legacy migration debt, unrelated to MaTrixOS Phase 3–7)
• 109 new tests added in Phase 3–6.6, all green
• No as any / @ts-ignore in MaTrixOS-authored code

Development

bun test                    # Test suite
bun run typecheck           # Typecheck all packages
bun run build               # Build the plugin bundle (dist/)

Documentation

• Full spec: CAHIER_DES_CHARGES.md (12 features, 1700+ lines)
• Project state: breadcrumb.md — always read first in a new session
• Decisions (ADRs): decisions/
• Release notes: RELEASE-NOTES-v0.1.0.md
• Roadmap (v0.2.0+ backlog): decisions/ROADMAP-phase6-gaps.md

Architecture

matrixos/                              # workspace root
├── packages/                          # 22 sibling packages
│   ├── omo-opencode/                  # THE OpenCode plugin adapter
│   ├── matrix-gateway-core/           # Phase 3: multi-channel messaging
│   ├── learning-loop/                 # Phase 5: L1→L2 learning store
│   ├── utils/ model-core/ prompts-core/ rules-engine/ agents-md-core/
│   ├── omo-config-core/ delegate-core/ telemetry-core/ skills-loader-core/
│   ├── team-core/ hashline-core/ ...  # +12 more core packages
│   └── shared-skills/                 # Cross-harness SKILL.md bundle
├── bin/                               # Platform-detection shim (matrixos.js)
├── script/                            # Build automation
└── postinstall.mjs                    # Simplified MaTrixOS postinstall

Conventions

• Runtime: Bun 1.3+ (never npm/yarn/pnpm for the root workspace)
• TypeScript: strict mode, ESNext, bun-types. No as any, @ts-ignore, @ts-expect-error in MaTrixOS code
• Tests: bun test, co-located *.test.ts, given/when/then style, injectable ports for any I/O
• Factory pattern: createXXX() everywhere
• Self-upgrade safety (D-006): all mutating self-improvement actions default to dry-run; require explicit --apply

License

Proprietary KL-Consulting. All rights reserved. Repository is private.