osmoda — osModa (bolivian-peru/os-moda)

osModa is a genuine NixOS-based operating system distribution with an AI-native system management layer — 10 Rust daemons, 91+ structured MCP tools, a TypeScript gateway (osmoda-gateway) with pluggable runtime drivers for Claude Code and OpenClaw, and a self-teaching skill engine (osmoda-teachd). Unlike every other framework in this corpus, osModa is not a Claude Code harness or a methodology — it is an actual operating system that installs to bare metal or cloud VMs, replacing the host OS with NixOS and deploying its daemons via systemd. The agent has root-level access to the entire system through structured MCP tool calls; every mutation is SHA-256 hash-chained to a tamper-proof SQLite audit ledger; NixOS atomic rollback provides safe-rollback for all system state changes. A pre-indexed code knowledge graph (CodeGraph, tree-sitter + SQLite via WASM) gives the agent navigational awareness of codebases without grep.

Compared to the seeds, osModa is unlike any seed archetype — it is closest to the MCP-anchored toolserver pattern (claude-flow Archetype 3) but taken to the extreme: rather than bundling MCP tools as a plugin, osModa is the compute substrate that MCP tools control. The specific delta from claude-flow is: actual OS ownership (not just agent orchestration), NixOS transactional state (not just file state), self-teaching (teachd learns from agent behavior), and CodeGraph pre-indexing.

Overview — osModa (bolivian-peru/os-moda)

Origin

osModa was built to solve the "missing infrastructure half" of AI agent frameworks. From the README:

"Every AI agent framework assumes your infrastructure is someone else's problem. They give you an agent that can think — but nowhere for it to live."

The project is in public beta — described as "a working system deployed on real servers, not a demo."

Philosophy

From README:

"osModa is the other half: the machine itself is AI-native. 91 structured tools across 10 Rust daemons give the AI typed, auditable access to the entire operating system. No shell parsing. No regex. system_health returns structured JSON. Every mutation is SHA-256 hash-chained to a tamper-proof ledger."

Architecture thesis: "Why NixOS? Every system change is a transaction. Every state has a generation number. Rolling back is one command. This makes AI root access meaningfully safer than on any traditional Linux distribution."

Three Trust Tiers

From CLAUDE.md:

TIER 0: Claude Code + agentd (full system, root-equivalent)
  ↓ grants capabilities to ↓
TIER 1: Approved apps (sandboxed, declared capabilities)
  ↓ even more restricted ↓
TIER 2: Untrusted tools (max isolation, no network, minimal fs)

Target Users

• Solo developers running their own servers (self-healing at 3am)
• AI agent builders who need infrastructure
• Small teams tired of on-call rotations
• "Anyone building an AI workforce" — osModa is the compute substrate for agents

Runtime Architecture

OpenClaw is the DEFAULT/executive runtime (as of 2026.5.20); Claude Code is a fully-supported peer selectable via the Engine tab. The osmoda-bridge (91 system tools) is installed as a native OpenClaw plugin or as an MCP server for Claude Code.

Architecture — osModa (bolivian-peru/os-moda)

Distribution

• Type: Full NixOS operating system distribution (not an app or plugin)
• Install (NixOS flake):

  inputs.os-moda.url = "github:bolivian-peru/os-moda";
  imports = [ os-moda.nixosModules.default ];
  services.osmoda.enable = true;
  

• Install (any Linux, experimental):

  curl -fsSL https://raw.githubusercontent.com/bolivian-peru/os-moda/main/scripts/install.sh | sudo bash
  

  ⚠️ Converts Ubuntu/Debian to NixOS — destructive, irreversible operation.

Required Runtime

• Bare metal server, cloud VM (Hetzner, DigitalOcean, AWS), or QEMU/KVM
• x86_64 or aarch64
• 2 GB RAM minimum (4 GB recommended), 20 GB disk
• NOT supported: Docker, LXC, WSL, OpenVZ, any container runtime (lacks systemd)

10 Rust Daemons (crates/)

Gateway

• osmoda-gateway (TypeScript) — pluggable runtime driver interface; supports Claude Code and OpenClaw drivers; routes agent sessions to appropriate runtime; maintains MEMORY.md auto-loaded into system prompt; JSONL transcript per session.

Skills (20+, in skills/)

CodeGraph Integration

• Source: colbymchenry/codegraph (MIT, pure-WASM tree-sitter + SQLite)
• Installed: On every spawn as optional MCP server (env-gated OSMODA_CODEGRAPH_ENABLED=1)
• Indexes: /opt/osmoda (self-modification), /workspace/* (spec-kit), /srv/* (deployed apps)
• Auto-sync: osmoda-codegraph-index.timer every 30 minutes
• Tools: codegraph_search/context/callers/callees/impact/node/explore/files/status

Components — osModa (bolivian-peru/os-moda)

MCP Tools (91, served by osmoda-mcpd)

Categories inferred from daemon architecture:

System Management (agentd)

• system_health — structured JSON system health check
• service_status — service status queries
• shell_exec — sandboxed shell execution
• journal_logs — systemd journal access
• event_log — append-only hash-chained event log
• memory_store / memory_recall — persistent memory operations
• file_read — audited file read

Learning Engine (teachd)

• teach_context — retrieve historical patterns by context
• teach_patterns — retrieve learned patterns by confidence
• teach_optimize_suggest — suggest optimizations from learned data
• teach_optimize_apply — apply suggested optimizations

CodeGraph (osmoda-codegraph)

• codegraph_search — semantic code search
• codegraph_context — code context retrieval
• codegraph_callers / codegraph_callees — call graph navigation
• codegraph_impact — impact analysis
• codegraph_node / codegraph_explore — code graph exploration
• codegraph_files / codegraph_status — file and index status

Slash Commands

None (0 slash commands in .claude/commands/) — interaction is via MCP tools through the gateway.

Skills (20, in skills/)

See 02-architecture.md for full list. Skills are SKILL.md files with frontmatter including tools: lists specifying which MCP tools the skill uses, and activation: auto where applicable.

agentctl CLI Tool

agentctl — CLI for system management:

• agentctl verify-ledger — verify SHA-256 hash chain integrity of audit ledger
• Additional subcommands for agent control and system management

Scripts

Templates

Skills use tool call templates; templates/ directory present but content not enumerated in public docs.

State Files

Uniqueness — osModa (bolivian-peru/os-moda)

Differs From Seeds

osModa is categorically different from all 11 seeds. The closest structural parallel is claude-flow (Archetype 3 — MCP-anchored toolserver) in that both bundle large numbers of MCP tools (claude-flow: 305, osModa: 91) and use SQLite for state. However, the architectural divergence is fundamental: claude-flow is a npm package installed on top of an existing OS; osModa IS the OS. The specific deltas: (1) NixOS transactional state — all system changes are atomic transactions with instant rollback, making AI root access semantically safe in a way no other framework achieves; (2) 10 Rust daemons as system API — 91 structured tools replace ad-hoc shell commands with typed, auditable operations; (3) osmoda-teachd — a self-teaching engine that learns from agent behavior between conversations, with confidence-scored patterns; (4) SHA-256 hash-chained audit ledger — tamper-proof record of every system mutation with cryptographic verification.

Positioning

osModa is the only framework in this entire corpus that targets the "infrastructure substrate" problem rather than the "agent behavioral discipline" problem. All other frameworks assume you have a working computer and want to make the AI agent better at using it. osModa assumes you want a computer whose native language is structured AI tool calls.

Observable Failure Modes

1. NixOS barrier: Requires full OS replacement — incompatible with Docker, LXC, WSL, any container runtime; high adoption barrier
2. Public beta roughness: README explicitly states "expect rough edges and rapid iteration"
3. OpenClaw dependency: Default runtime is OpenClaw (not Claude Code), which is itself a nascent runtime — dependency on two non-mainstream pieces of infrastructure
4. Root access risk: Despite NixOS rollback safety, the audit ledger note "NixOS rollback covers OS state — not data sent to external APIs or deleted user data" leaves an important escape hatch
5. Single-node: No distributed consensus; mesh is for encrypted communication, not agent coordination