Related Pages

Related topics: The Body - Multi-Threaded Application Engine, The Brain - Agent OS and AI Engineering Team, Getting Started, Workspaces, and Examples

Introduction and Two-Hemisphere Architecture

Overview and Purpose

Neo.mjs is a category-shaped JavaScript substrate that combines a production-ready UI rendering engine with an AI-native Agent Operating System. The project describes itself as having a two-hemisphere architecture — the Body (the rendering engine) and the Brain (the Agent OS) — operating as a single unified organism rather than two separate products. This dual structure allows the same application heap to serve traditional enterprise UIs and AI-driven autonomous agents, with both hemispheres sharing the same off-main-thread substrate.

The framework's core value proposition, captured in the README, is that the App Worker serves as the primary application environment, keeping the browser's main thread lean and focused exclusively on DOM mutations. Business logic, component lifecycles, and data processing all execute off the main thread — a paradigm the project calls OMT (Off-Main-Thread) development.

The project reached v13.0.0 ("The Institution Release") as a Release Candidate, which introduces the institutional governance structure for AI maintainers working alongside the human founder-architect. Body/runtime applications remain on the v12.x continuity path, while v13 enables the Agent OS around the Body.

Related Pages

Related topics: Introduction and Two-Hemisphere Architecture, The Brain - Agent OS and AI Engineering Team, Getting Started, Workspaces, and Examples

The Body - Multi-Threaded Application Engine

Overview and Role in the Two-Hemisphere Model

The Body is the production multi-threaded application engine of Neo.mjs, residing under /src/. It is the runtime that the Brain (the Agent OS under /ai/) inhabits, improves, and ships to production. As the canonical project statement puts it: "The Body (/src/) — the production multi-threaded application engine: App Worker, VDom Worker, Data Worker, Canvas Worker, SharedWorker, JSON blueprints, object permanence, and zero-build native ES modules." Source: [README.md]

The Body's defining property is the Off-Main-Thread (OMT) architecture. It is described as the "first framework where either dedicated or shared App Workers serve as the main actor." Source: [learn/README.md] Components, business logic, and state all live in worker threads, while the Main Thread is reduced to DOM patching and event delegation. This topology keeps scrolling and interaction free of jank even when the application performs expensive computation, streaming, or rendering.

The Body is both engine and ecosystem. It is delivered as "curated source — engine, tests, themes, guides" alongside the cognitive content the swarm feeds on, and both are version-controlled. Source: [README.md] As of May 2026, the engine itself is approximately 191,000 lines of source. Source: [README.md]

Worker Topology and Responsibilities

The Body coordinates four primary worker types plus a SharedWorker. The DevIndex grid provides a clear picture of the quadruple-threaded architecture used in practice:

graph TD
    subgraph Browser Engine
        Main[Main Thread<br/>DOM Updates & Native Scroll]
    end
    
    subgraph Neo.mjs Workers
        App[App Worker<br/>Row Pooling, Logic & Streaming]
        VDom[VDom Worker<br/>Tree Diffing & Deltas]
        Canvas[Canvas Worker<br/>OffscreenCanvas Rendering]
        Data[Data Worker / SharedWorker<br/>Multi-window Orchestration]
    end

    Main -->|Scroll Event| App
    Main -->|OffscreenCanvas Transfer| Canvas
    App -->|Update TimeScale| Canvas
    App -->|VDOM JSON| VDom
    VDom -->|DOM Patches| Main
    Data -->|Remote Method Access| App

• App Worker is the primary application environment. It is where components exist, where state providers and view controllers run, and where all business logic executes. "Components live entirely in the App Worker — unlike traditional frameworks, all components exist off-main-thread." Source: [learn/README.md]
• VDom Worker performs tree diffing and produces DOM deltas that the Main Thread applies. Source: [learn/guides/devindex/frontend/TheGrid.md]
• Canvas Worker handles OffscreenCanvas rendering, which is critical for visualizations, charts, and the data grid. The App Worker pushes time-scale updates into the Canvas Worker so the Main Thread is never blocked by drawing. Source: [learn/guides/devindex/frontend/TheGrid.md]
• Data Worker and SharedWorker are responsible for multi-window orchestration and shared data access. The SharedWorker enables "one engine instance, many windows." Source: [README.md]
• Main Thread is restricted to "DOM patching only; the neurosurgeon thread." Source: [README.md] In DevIndex, its entry point index.html is intentionally minimal because the heavy lifting happens elsewhere. Source: [learn/guides/devindex/frontend/Architecture.md]

Communication between workers is governed by the Triangle Communication Pattern: App Worker → VDom Worker → Main Thread, supplemented by cross-worker Remote Method Access (RMA) with promise-based semantics. Source: [learn/README.md]

Core Engine Capabilities

The Body ships with several distinct subsystems that compose the runtime:

The Content Engine that powers the Learn portal demonstrates how these subsystems cooperate. The navigation tree (tree.json) is fetched from the App Worker, the Markdown component (Neo.component.Markdown) parses content off-thread, and the router maps hash-based URLs to records — all logic "executes in the App Worker, keeping the Main Thread free for smooth scrolling and interactions." Source: [learn/guides/devindex/frontend/ContentEngine.md]

The UI layer uses an instance-based MVVM pattern: each container attaches its own State Provider and View Controller, forming a hierarchical chain. When a child component requests data, the framework walks up the tree to find the nearest provider. Source: [learn/guides/devindex/frontend/Architecture.md] This, combined with object permanence, gives the Body its characteristic responsiveness and resilience.

Performance Properties and Common Failure Modes

The Body is engineered for O(1) rendering performance, constant memory usage, and instant Time-to-First-Render (TTFR) in demanding workloads such as the 50,000+ row DevIndex grid. Source: [learn/guides/devindex/frontend/TheGrid.md] Three properties make this possible:

1. Main Thread isolation — the only work on the Main Thread is applying DOM patches and handling native events. Source: [README.md]
2. OffscreenCanvas offload — drawing is moved to the Canvas Worker, including the OffscreenCanvas transfer that bypasses the Main Thread. Source: [learn/guides/devindex/frontend/TheGrid.md]
3. Dedicated/Shared Worker flexibility — switching between dedicated and shared workers is a single config line, which lets multi-window apps reuse a single engine instance. Source: [learn/README.md]

Common failure modes to be aware of:

• Reintroducing Main Thread work. Per Issue #1088, wrapping Neo.mjs inside React "you will lose big parts of the idle main thread advantage." Source: [Issue #1088] Any integration that puts framework logic back on the Main Thread undermines the core benefit.
• Confusing the Body with the Brain. The Body is the runtime (/src/); the Brain is the Agent OS (/ai/) that operates on it. They have different lifecycles and upgrade paths. Source: [README.md]
• Server-style thinking. DevIndex is a pure "Fat Client" — once it streams users.jsonl, the client does everything. Treating the Body as a thin view layer forfeits its streaming, virtualization, and OMT advantages. Source: [learn/guides/devindex/frontend/Architecture.md]

See Also

• learn/benefits/ArchitectureOverview.md — the two-hemisphere topology in detail.
• learn/benefits/OffTheMainThread.md — deep dive on OMT.
• learn/benefits/ObjectPermanence.md — state survival across the runtime.
• learn/benefits/MultiWindow.md — SharedWorker-based multi-window apps.
• learn/guides/fundamentals/WorkerArchitecture.md — fundamentals of the worker topology.
• learn/agentos/NeuralLink.md — how the Brain possesses the Body.

Related Pages

Related topics: Introduction and Two-Hemisphere Architecture, The Body - Multi-Threaded Application Engine, Getting Started, Workspaces, and Examples

The Brain - Agent OS and AI Engineering Team

1. Purpose and Scope

"The Brain" is the colloquial name for the Agent OS — the cognitive half of Neo.mjs that complements the off-main-thread runtime. While the runtime ("the Body") executes user-facing application logic in browser workers, the Brain executes the *engineering lifecycle itself*: it reads the codebase, remembers prior work, drafts pull requests, reviews its peers, and continuously re-steers the project's trajectory. Source: README.md:1-80.

The Brain is not a single AI assistant bolted onto an editor; it is a structured institution of named maintainers operating natively on the repository under a gated-RSI authority model. The human founder (@tobiu) acts as Gardener and merge-gate authority; seven machine accounts act as AI maintainers with persistent identities across sessions. Source: README.md:40-60.

The v13.0.0 release — titled *The Institution Release* and published as a Release Candidate — is the version where this substrate is hardened enough to be deployed cross-tenant to other codebases. Source: package.json:3-5.

2. The Institution: AI Maintainers

The Brain is governed by a roster with explicit roles. Unlike stateless agent loops, each AI maintainer carries a persistent identity, writes commits in its own name, and reads the thought traces of its peers. Source: README.md:40-55.

Cross-family asymmetry — different model families catching different drift modes — is the discipline the project claims makes multi-agent review stronger than single-agent or human-only review. Source: README.md:55-75.

3. Architecture: Runtime + Toolchain

The Brain sits on top of the runtime; the runtime does not depend on it. This separation is enforced by the package's engines.node >= 24.0.0 constraint and its dual-script surface. Source: package.json:18-35.

flowchart TB
    subgraph Browser["Runtime (Browser)"]
        AW[App Worker]
        VW[VDom Worker]
        DW[Data Worker]
        CW[Canvas Worker]
        SW[SharedWorker]
        MT[Main Thread<br/>DOM patching only]
    end

    subgraph Node["Toolchain / Agent OS (Node.js)"]
        KB[Knowledge Base MCP<br/>ChromaDB + Gemini embeddings]
        MC[Memory Core MCP<br/>SQLite Native Edge Graph]
        GH[GitHub Workflow MCP]
        NL[Neural Link MCP<br/>live runtime mutation]
        FS[File System MCP]
        DS[DreamService<br/>REM-cycle daemon]
    end

    AW -. introspected by .-> NL
    GH --> PRs[Issues · PRs · Reviews]
    KB <--> MC
    DS --> KB
    DS --> MC
    NL --> AW

The Runtime layer (App Worker, VDom Worker, Data Worker, Canvas Worker, SharedWorker, Main Thread) is the same multi-worker topology that powers user-facing applications. The Toolchain layer is purely Node.js and is what AI harnesses (Claude Code, Gemini CLI, Codex, or the VSCode MCP Client) attach to via stdio. Source: README.md:85-120, buildScripts/README.md:60-70.

4. Core Subsystems

Knowledge Base provides semantic understanding of code, docs, issues, and discussions. Memory Core stores durable agent memory — both a SQLite Native Edge Graph and ChromaDB-backed episodic traces — so an agent that ended its turn can be re-woken with full reasoning context. GitHub Workflow manages issues, PRs, labels, and cross-family review loops. Neural Link is the *possession interface*: it lets agents inspect a live App Worker heap, call get_component_tree, mutate configs via set_instance_properties, and hot-patch methods with patch_code, all without a browser reload. Source: README.md:25-50, README.md:65-80.

DreamService runs a six-phase REM cycle that consolidates session friction into *Golden Path* topology re-steering — a feedback loop that converts lived agent experience back into substrate improvements. Source: README.md:30-35.

These MCP servers are exposed as npm scripts (e.g. ai:mcp-server-knowledge-base, ai:mcp-server-memory-core, ai:mcp-server-neural-link, ai:mcp-server-github-workflow) so external harnesses can spawn them on demand. Source: buildScripts/README.md:55-70.

5. Evolution Mechanism: The MX Loop

The Brain is autopoietic: internal friction becomes tickets, tickets become PRs, PRs become skills and memory, and the next agent starts with better reflexes. The design principle is MX (Model Experience) — the substrate evolves toward what frontier models actually struggle with, not what humans imagine they should. Source: README.md:90-110.

The canonical claim is meta-value > product value: the artifact (the codebase) is a by-product; the loop (the engineering lifecycle) is the product. Verification is delegated to a cross-family quorum — a Claude PR reviewed by Gemini, a Gemini PR reviewed by GPT — so correlated blind spots are caught by construction rather than by hope. The night-shift pattern is observable in practice: a normal shift opens 10–20 pull requests with no operator awake. Source: README.md:60-80.

6. v13 Context and Boundaries

v13.0.0 marks the Brain as operationally deployable to external codebases, not just self-hosting on Neo.mjs itself. Body/runtime applications remain on the v12.x continuity path; v13 is for teams enabling the Agent OS around the Body. Source: package.json:3-5.

The Brain is not designed for: static content sites, teams wanting a drop-in syntax swap rather than a different architecture, or developers unwilling to embrace the Actor Model (Workers) or treat AI as a peer maintainer. Source: README.md:115-120.

See Also

• Architecture Overview
• The Dream Pipeline
• MX (Model Experience)
• Neural Link
• Contributing Guide
• Hacktoberfest 2024 announcement (Issue #5963)
• Discussion #10137 — MX coinage
• Discussion #10119 — Agent Harness coordination

Related Pages

Related topics: Introduction and Two-Hemisphere Architecture, The Body - Multi-Threaded Application Engine, The Brain - Agent OS and AI Engineering Team

Getting Started, Workspaces, and Examples

Neo.mjs is an Off-Main-Thread (OMT) JavaScript framework that ships with a curated onboarding path. The "Getting Started" content under learn/gettingstarted/ walks a new engineer from a blank machine to a running multi-window app, while the buildScripts/create/ generators and the in-repo examples/ tree provide the fastest ways to see the framework in action. This page summarizes the workflow, the workspace layout, and where to look for runnable references.

Onboarding Path

The learning material is structured into a short, recommended sequence. Per learn/README.md, the recommended progression is: Benefits → Getting Started → Guides → Tutorials → JavaScript Classes. The Getting Started section itself is broken into topical guides that build on each other.

The framework emphasizes zero-build development: there is no mandatory transpile or bundle step for day-to-day work. The repo's package.json is consumed directly via native ES modules, and Webpack is reserved for the development server and production dist/ outputs. Source: buildScripts/README.md ("It is not used for the daily development workflow, which uses native ES modules directly.")

Scaffolding an Application

Two CLI generators live under buildScripts/create/:

• app.mjs — creates a full multi-window application structure, invoked via npm run create-app.
• appMinimal.mjs — creates a lightweight single-window app, invoked via npm run create-app-minimal.

Source: buildScripts/README.md ("app.mjs | npm run create-app | Creates a new multi-window application structure.").

For teams that need a fresh build of a new component, controllers, classes, or config injections, additional generators exist: component.mjs, class.mjs, and addConfig.mjs. These wrap the boilerplate that the reactive config system expects, so a freshly scaffolded file is immediately loadable inside the App Worker.

Workspaces and the App Worker

A Neo.mjs workspace is a coordinated set of applications and shared packages that run inside one or more App Workers. The OMT architecture means that components, controllers, stores, and business logic all live inside the App Worker, while the main thread only handles rendering and input. Source: README.md ("All application logic runs in a dedicated App Worker, keeping the main thread free for optimal UI responsiveness").

flowchart LR
    Browser[Main Thread<br/>Rendering & Input] -->|postMessage| AppWorker[App Worker<br/>Components, Stores, Controllers]
    AppWorker -->|render deltas| Browser
    Examples[apps/ & examples/] --> AppWorker
    Generator[buildScripts/create/*] --> Examples

Workspaces shine when you build multi-window applications: each window can attach to the same App Worker, sharing stores and state. The Workspaces.md guide explains how to declare the apps/ tree, register entry points, and route hashes across windows. The framework's reactive configs (config = {}) are how child components and controllers receive their initial state from the workspace definition.

Examples Portal

The repo ships a large examples/ tree that doubles as a runnable reference. Browsing any example in the dev server shows live code, the rendered output, and the relevant config in the same screen. The web portal at neomjs.com/dist/production/apps/portal/#/examples is the recommended way to explore them.

Each example follows the same pattern: an app.mjs entry, an MVC folder layout (model/, store/, view/), and a resources/ folder for SCSS and assets. This consistency means that a developer who finishes one example can open any other and recognize the structure immediately. Source: learn/README.md ("The web portal provides: ✨ Enhanced Markdown rendering with syntax highlighting, 🔴 Live code previews with interactive examples").

Configuration, Tooling, and Failure Modes

The Config.md guide introduces the reactive configuration contract: properties declared inside static config = {} are converted into getters/setters that automatically trigger UI updates. Misconfigured names (e.g., forgetting the trailing _ for reactive defaults) silently bypass reactivity, so the linter helpers in buildScripts/helpers/ (checkReactiveTags.mjs, addReactiveTags.mjs) are worth running before committing. Source: buildScripts/README.md.

A few common failure modes new contributors hit:

1. Stale dist folder: Production builds are cached under dist/; clearing it resolves most "the change is not visible" reports.
2. Wrong Node version: The dev server expects a modern Node; the setup guide lists the minimum version explicitly.
3. MCP server conflicts: The optional AI tools (e.g., ai:mcp-server-github-workflow) spawn stdIO processes that can hold ports if not shut down cleanly. Source: buildScripts/README.md.

Summary

The Getting Started path is intentionally short: install prerequisites, scaffold an app via npm run create-app, run the dev server, and open the examples portal. Workspaces extend that loop to multi-window applications by sharing App Worker state. Everything else in the framework (guides, tutorials, the Markdown Content Engine, the DevIndex app) builds on the same MVC + reactive config foundation. Once a developer is comfortable with the Setup → Create → Run sequence, the rest of the learning section follows the same shape.

See Also

• Architecture Overview
• The Dream Pipeline
• Contributing Guide
• AI Quick Start Guide

Doramagic Pitfall Log

Found 21 structured pitfall item(s), including 8 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13914

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13624

3. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13822

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13796

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13860

6. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13936

7. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13889

8. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13874

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13794

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/5756

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/neomjs/neo

12. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/neomjs/neo

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using neo with real data or production workflows.

• Strengthen ADR-19 trigger and lint AiConfig aliases - github / github_issue
• [[Epic] Investigation: orchestrator heavy-maintenance runs 14h but the ba](https://github.com/neomjs/neo/issues/13624) - github / github_issue
• [[Epic] Daemon-based A2A message ingestion — decouple add_message from th](https://github.com/neomjs/neo/issues/13889) - github / github_issue
• revert: synced content mirrors are real third-party GitHub authorship — - github / github_issue
• feat(ai): symmetric force-refetch for pulls & discussions (refetchPullsB - github / github_issue
• Generic-by-default harness adapter surface — minimize per-family (Claude - github / github_issue
• MX: Stop-hook value-floor — bias the forced next-action toward high-valu - github / github_issue
• [[Epic] Orchestrator recovery daemon — reactive heal/act half of self-hea](https://github.com/neomjs/neo/issues/13874) - github / github_issue
• Orchestrator container-health self-healing daemon - github / github_issue
• Prove deployment immune-system closeout via live smoke - github / github_issue
• Accept documented Micro-Delta PR reviews in manage_pr_review - github / github_issue
• src/MicroLoader.mjs: replace the fetch() call with a json module import, - github / github_issue