Runtime and toolchain
| Component | Choice | Notes |
|---|---|---|
| Runtime | Bun (>=1.2) | Native SQLite, instant startup, unified runtime |
| Language | Pure JavaScript ES2024+ | TypeScript fully eradicated — no build step for dev |
| Package manager | pnpm | Bun used only for runtime and bundling |
| UI build | Vite 7 → dist/control-ui/ | Lit 3 web components |
| Tests | Vitest | 738 suites, 6,140+ tests (unit + E2E) |
| Linter | oxlint + oxfmt | Not eslint |
No TypeScript means no build step during development. You can edit a source file and the change is live immediately under
bun --watch. This is intentional — a single-developer personal companion project gains nothing from a type compilation layer.Project structure
Data flow: inbound message
Every message from any channel follows this path through the gateway:Channel receives message
The channel extension (e.g., WhatsApp Baileys plugin) receives an inbound message from the external service.
callGateway RPC
The extension calls the gateway via
callGateway({ method: "chat", channel, peer, message }).Resolve session key
The gateway applies the DM policy and channel-peer combination to resolve (or create) a session key. Default scope is
per-channel-peer.Load session transcript
The encrypted session transcript is loaded from
~/.genosv1/agents/{uuid}/sessions/. NYXENC1 decryption happens transparently.Semantic memory prefetch
Relevant memory context is injected from the dual-backend memory system (QMD + SQLite). The query embedding is reused for tool filtering — zero extra API calls.
Semantic tool filtering
Tools are filtered by embedding similarity to the user’s intent. Core tools (read, write, exec, bash) always pass. Domain tools appear only when semantically relevant. Saves ~2,000–3,000 tokens per request.
Agent run (Pi embedded runner)
The Pi agent runner executes the model request: system prompt + tools + session context → model API → tool calls → results → final reply.
Reply streamed back to channel
The final response is delivered to the originating channel (e.g., WhatsApp).
Multi-agent system
Agents are isolated execution contexts. Each lives in~/.genosv1/agents/{uuid}/ — opaque 8-character hex directories that decouple identity from the filesystem. Renaming an agent is a config + session key operation — zero filesystem moves.
| Concept | Details |
|---|---|
| Tool profile | Inferred from agent name: coding, messaging, minimal, full |
| Session key | agent:{agentId}:main (always present) |
| A2A communication | Agents can message each other; ping-pong default: 2 turns (max 5) |
| Input provenance | external_user vs inter_session — agents know who is talking |
| Smart model routing | boost tool auto-escalates to the advanced model mid-conversation |
Security layers
| Layer | Implementation |
|---|---|
| Encryption at rest | NYXENC1 (AES-256-GCM, PBKDF2 100K iterations) |
| Key management | macOS Keychain → env → .env fallback |
| Biometric auth | WebAuthn / Touch ID |
| DM policy | Pairing (6-digit code) / allowlist / closed |
| Tool execution | Approval gates per tool category |
| Channel restrictions | Messaging channels cannot run shell commands |
| Filesystem | Transparent write/edit encryption |
| Audit | Tamper-evident HMAC checksums |
| Secrets | Buffer zeroing after use |
| OS hardening | Spotlight and Time Machine exclusion |
| Auto-lock | 30-minute vault timeout |
Key design decisions
Bun runtime. Bun provides native SQLite (bun:sqlite), instant startup, and a unified runtime that handles both server execution and bundling. No Node.js compatibility shims required for core functionality.
TypeScript eradication. Pure ES2024+ JavaScript with no compilation step. The codebase runs directly under Bun during development. This is a deliberate tradeoff: zero build friction at the cost of static typing — correct for a product that values iteration speed over large-team coordination.
Conversational configuration. 12+ UI tabs replaced with config_manage (30 actions, 190 blueprints). Configuration is conversation — users say what they want, the agent applies validated changes with automatic coercion and cross-field checks.
Tests. 738 suites, 6,140+ tests across unit and E2E, run with Vitest. The test matrix covers gateway startup, channel integration, memory compaction, security audit, and agent-to-agent communication.
Further reading
Gateway
Full gateway startup sequence and configuration.
Memory system
TOON compaction, vector search, and semantic prefetch.
Extensions
Channel extension tiers and the plugin SDK.
Configuration
All config sections, blueprints, and the config_manage tool.