os-moda: Instructions file for Claude Code

CLAUDE.md - osModa

What this is

osModa: NixOS distribution with AI-native system management. The agent runs via Claude Code SDK with full root-level access to the entire system via structured daemons.

The agent has FULL system access. Root. All files. All processes. All APIs. The sandbox exists for UNTRUSTED third-party tools, not for the agent itself.

Current state

• osmoda-gateway v1.3.0 (stable) — named chats (multiple distinct persistent conversations per server: each chatId → its own --resume session + transcript + native compaction; ChatRegistry at state/chats.json; /chats REST list/create/rename/archive; legacy/main chatId maps to the original conversation for zero-move migration) + cross-chat awareness (a bounded, deterministic since-cursor digest of OTHER chats' notable tool-rows — sourced from the gateway's own per-chat transcripts, NOT the agentd ledger — injected into the turn + surfaced as a "caught up on N changes" chip; per-peer cursors commit only on a successful turn; zero token overhead for single-chat work). Runtime: claude-code is the default chat driver (token streaming + named chats + OAuth/API key); the ws-relay runs in gateway mode for both drivers (so named chats work for openclaw-via-gateway too); openclaw-native bypass is behind install.sh --advanced-openclaw-native. (gateway-owned canonical transcript [JSONL per session, GET /sessions/:agent/:key/transcript] + durable MEMORY.md auto-load into the system prompt + transcript re-seed when a runtime session is missing/swapped; sessions disk-persisted, runtime-tagged, healthCheck-gated swaps, optional CodeGraph MCP server; tool-target hints in the chat action log). Both drivers now honor the two-text-channel streaming contract: planning/preamble text streams on interim_text (collapsible thinking panel) and only the authoritative final answer is promoted as text_bulk (+ interim_commit_final + phase:answering). This fixed the claude-code fragmentation bug where every preamble before a tool was treated as a final answer — the gateway no longer flushes an assistant transcript row per tool_use, so one logical turn = exactly one persisted assistant entry (no more stacked "Task completed" stubs on replay). The dashboard replay accumulates agent rows into one turn (heals pre-fix transcripts). Stop reliability: the ws-relay accepts both chat_abort and abort, the dashboard Stop button halts the UI client-first/unconditionally, and abort SIGTERM→SIGKILLs the claude process-group (0.5 s kill, verified). claude-code is the recommended chat runtime — it streams token text + live tools with native session history + auto-compaction; openclaw buffers per-round and cannot token-stream.
• Spawn-app API v1.3.x (latest documented v1.3.1; internal ~v1.3.35 with chat persistence + watchdog + Engine UX + 3-col detail grid + heartbeat body-limit fix + single-source chat replay + smooth streaming reveal + live tool-action targets)
• Claude Code CLI ^2.1.175 pin (newest 2.x; refuses anything <2.x via gateway healthCheck). Default model claude-opus-4-8; claude-fable-5 / claude-mythos-5 (Project Glasswing) selectable.
• claude-code is the DEFAULT runtime (canonical as of 2026-06-10) — token streaming + persistent named chats + cross-chat awareness + OAuth-or-API-key; it is what the fleet actually runs. install.sh:87, osmoda.nix:77, and the README all agree on this default. OpenClaw remains a fully-supported, Engine-tab-selectable peer (the original osModa design, kept as the BYOK/multi-provider executive option). The osmoda-bridge (92 system tools) is installed as a native OpenClaw plugin via openclaw plugins install <path> --link --dangerously-force-unsafe-install (forced — it's our tier-0 bridge: child_process + daemon sockets are its purpose) against a compiled dist/index.js whose manifest declares contracts.tools (a 2026.5 requirement). Runtime invocation: openclaw agent --agent <id> --local --json --model <provider>/<model> --session-id <id> --message; auth written as the 2026.5 AuthProfileSecretsStore ({version:1,profiles:{<id>:{type:"api_key"|"token",provider,...}}} — accepts API key OR OAuth-as-token); non-default agent ids auto-registered. Verified live: 77+ osModa tools load into a real openclaw turn through the gateway (full completed reply pending a credential that isn't usage-capped). healthCheck() probes the agent subcommand; swaps are gated.
• CodeGraph (colbymchenry/codegraph, MIT, pure-WASM tree-sitter + SQLite) installed on every spawn as an optional MCP server (env-gated OSMODA_CODEGRAPH_ENABLED=1). Gives the agent codegraph_search/context/callers/callees/impact/node/explore/files/status — a pre-indexed code knowledge graph for ~90% fewer grep/Read calls. Auto-indexes /opt/osmoda (self-modification awareness), /workspace/* (spec-kit), /srv/* (deployed apps) via osmoda-codegraph-index.timer (30-min sync); spec-kit init/implement hook into it. Security-audited 2026-05-20. Full phased plan in docs/planning/CODEGRAPH-INTEGRATION.md.