# https://github.com/neomjs/neo Project Manual Generated at: 2026-06-24 03:16:57 UTC ## Table of Contents - [Introduction and Two-Hemisphere Architecture](#page-1) - [The Body - Multi-Threaded Application Engine](#page-2) - [The Brain - Agent OS and AI Engineering Team](#page-3) - [Getting Started, Workspaces, and Examples](#page-4) ## Introduction and Two-Hemisphere Architecture ### Related Pages Related topics: [The Body - Multi-Threaded Application Engine](#page-2), [The Brain - Agent OS and AI Engineering Team](#page-3), [Getting Started, Workspaces, and Examples](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/neomjs/neo/blob/main/README.md) - [package.json](https://github.com/neomjs/neo/blob/main/package.json) - [learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md) - [learn/guides/devindex/frontend/Architecture.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/Architecture.md) - [learn/guides/devindex/frontend/TheGrid.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/TheGrid.md) - [learn/guides/devindex/frontend/ContentEngine.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/ContentEngine.md) - [buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md)
# 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. --- ## The Body Hemisphere: Rendering Engine The **Body** hemisphere is the production-ready rendering engine optimized for enterprise multi-window applications, financial trading platforms, IDE-class tools, and control-room dashboards. It is engineered for sustained throughput (40k+ operations per second without jank) and supports a **quadruple-threaded architecture** for its most demanding components. ### Off-Main-Thread Component Model In traditional web frameworks, components live on the main thread alongside DOM rendering. In Neo.mjs, components exist entirely within the App Worker. The main thread's role is reduced to single-task efficiency: applying DOM mutations delivered as deltas. This separation is achieved through a triangle communication pattern: **App Worker → VDom Worker → Main Thread**. The main thread can be inspected in the entry point of apps like `apps/devindex/index.html`, which contains only minimal HTML scaffolding — a deliberate emptiness that demonstrates the lean-main-thread philosophy. ### Multi-Worker Coordination The grid component (`Neo.grid.Container`) exemplifies the Body's optimization strategy. It coordinates four execution contexts: | Worker | Responsibility | |---|---| | Main Thread | DOM updates and native scroll events | | App Worker | Row pooling, business logic, streaming | | VDom Worker | Tree diffing and delta generation | | Canvas Worker | OffscreenCanvas rendering for custom cells | The App Worker streams a single `users.jsonl` file on startup, then performs all filtering, sorting, and view transitions in memory without ever contacting a backend. This **"Fat Client"** philosophy means 50,000+ records can be held and manipulated entirely in the client heap. --- ## The Brain Hemisphere: Agent OS The **Brain** hemisphere is the Agent OS — an AI-native operating layer designed for multi-agent systems with persistent memory, cross-family coordination, and runtime-mutable application substrates. It is what the project positions as the next evolution beyond traditional conversational UIs. ### Core Agent OS Components The Brain is composed of five primary subsystems: - **Knowledge Base** — semantic understanding of the codebase, documentation, issues, pull requests, and discussions. - **Memory Core** — durable persistent memory across agent sessions. - **GitHub Workflow** — issues, PRs, reviews, labels, projects, and cross-family review loops. - **Neural Link** — the bridge that lets agents move from static code generation into digital embodiment within a live app. - **DreamService / Golden Path** — a six-phase REM-cycle consolidation process that re-steers priorities from lived friction. The project also describes an **A2A coordination** layer for durable messages and wake events between named AI maintainers, and an **MX (Model Experience)** principle stating that the substrate evolves toward what frontier models actually struggle with, not toward what humans imagine they should. ### The Possession Interface The Neural Link is the defining primitive of the Brain hemisphere. It is not an API garnish — it is the bridge that lets agents **co-inhabit the same App Worker heap** as the live application. Multiple autonomous agents can: - Inspect real-time state via `get_component_tree` - Mutate configurations without browser reloads via `set_instance_properties` - Hot-patch methods via `patch_code` - Verify the result immediately This primitive, called the **Possession Interface**, transcends web UI: the same architecture maps to game-engine scene graphs, robotics sensorimotor loops, and any future domain where AI needs to embody. The project's roadmap frames this evolution as: *Software → Games → Robots → X*. ```mermaid flowchart LR subgraph Body["Body Hemisphere"] UI[UI Components] Grid[Grid Container] Canvas[OffscreenCanvas] end subgraph Brain["Brain Hemisphere"] KB[Knowledge Base] MC[Memory Core] NL[Neural Link] DS[DreamService] end subgraph Workers["App Worker Heap"] State[Live Application State] end NL <-->|Possession Interface| State State --> UI KB --> NL MC --> NL DS --> KB DS --> MC ``` --- ## Unified Substrate and Governance The two hemispheres are not loosely coupled products. They share a single App Worker heap and a unified governance model described as **gated-RSI by design**: the AI maintainer swarm runs the engineering lifecycle via pull requests, while the founder-architect holds final merge authority as a governance choice. The maintainer institution includes human architect **Tobias Uhlig** (`@tobiu`) and a team of named AI maintainers such as `@neo-opus-ada`, `@neo-opus-grace`, `@neo-opus-vega`, `@neo-fable`, `@neo-fable-clio`, `@neo-gemini-pro`, and `@neo-gpt`. This structure is described in the README as a structured institution operating natively on the repository, not an abstract collective. ### Community Context The two-hemisphere framing is directly informed by community demand. Issue #2724 calls out that documentation is "spread among GitHub pages and articles at Medium" and that the README is not clear on "what exactly is neo.mjs" — a gap the Brain+Body framing directly addresses. Issue #3145 proposes overhauling the roadmap to align contributor impact with the institution's evolution. The community hub remains Discord and Slack, both linked from the README, where the harness coordination substrate (graduated from Discussion #10119 into ADR 0020 and Epic #13012) is actively debated. For engineers building enterprise UIs, the README directs them to start with the Body. For AI architects building multi-agent systems, they are directed to start with the Brain and the Possession Interface. For researchers studying autopoietic systems and empirical multi-agent governance, the recommended starting points are Discussion #10137 (MX coinage) and Discussion #10119 (harness coordination). --- ## See Also - [Off-Main-Thread Architecture Deep Dive](Architecture.md) - [The Grid: Quadruple-Threaded Rendering](TheGrid.md) - [Markdown Content Engine](ContentEngine.md) - [Build Scripts and CLI Reference](../../buildScripts/README.md) - [Learning Path Overview](../../README.md) --- ## The Body - Multi-Threaded Application Engine ### Related Pages Related topics: [Introduction and Two-Hemisphere Architecture](#page-1), [The Brain - Agent OS and AI Engineering Team](#page-3), [Getting Started, Workspaces, and Examples](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/neomjs/neo/blob/main/README.md) - [learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md) - [learn/guides/devindex/frontend/Architecture.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/Architecture.md) - [learn/guides/devindex/frontend/TheGrid.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/TheGrid.md) - [learn/guides/devindex/frontend/ContentEngine.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/ContentEngine.md) - [package.json](https://github.com/neomjs/neo/blob/main/package.json)
# 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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/README.md)] As of May 2026, the engine itself is approximately 191,000 lines of source. [Source: [README.md](https://github.com/neomjs/neo/blob/main/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: ```mermaid graph TD subgraph Browser Engine Main[Main Thread
DOM Updates & Native Scroll] end subgraph Neo.mjs Workers App[App Worker
Row Pooling, Logic & Streaming] VDom[VDom Worker
Tree Diffing & Deltas] Canvas[Canvas Worker
OffscreenCanvas Rendering] Data[Data Worker / SharedWorker
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](https://github.com/neomjs/neo/blob/main/learn/README.md)] - **VDom Worker** performs tree diffing and produces DOM deltas that the Main Thread applies. [Source: [learn/guides/devindex/frontend/TheGrid.md](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/README.md)] - **Main Thread** is restricted to "DOM patching only; the neurosurgeon thread." [Source: [README.md](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/learn/README.md)] ## Core Engine Capabilities The Body ships with several distinct subsystems that compose the runtime: | Subsystem | Purpose | | :--- | :--- | | **App Worker** | Hosts all components, hierarchical State Providers, and View Controllers. [Source: [learn/guides/devindex/frontend/Architecture.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/Architecture.md)] | | **VDom Worker** | Diffs the declarative component tree and emits minimal DOM patches. [Source: [learn/guides/devindex/frontend/TheGrid.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/TheGrid.md)] | | **Canvas Worker** | Performs OffscreenCanvas rendering for charts, graphs, and grid visualizations. [Source: [learn/guides/devindex/frontend/TheGrid.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/TheGrid.md)] | | **Data Worker / SharedWorker** | Multi-window orchestration and shared state. [Source: [README.md](https://github.com/neomjs/neo/blob/main/README.md)] | | **JSON Blueprints** | Declarative component trees that can be sent across workers as data. [Source: [README.md](https://github.com/neomjs/neo/blob/main/README.md)] | | **Object Permanence** | State survival across re-mounts, navigation, and worker boundaries. [Source: [README.md](https://github.com/neomjs/neo/blob/main/README.md)] | | **Zero-Build Native ES Modules** | Instant development with native ES modules and dynamic imports. [Source: [package.json](https://github.com/neomjs/neo/blob/main/package.json)] | 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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/issues/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/Architecture.md)] ## See Also - [learn/benefits/ArchitectureOverview.md](https://github.com/neomjs/neo/blob/main/learn/benefits/ArchitectureOverview.md) — the two-hemisphere topology in detail. - [learn/benefits/OffTheMainThread.md](https://github.com/neomjs/neo/blob/main/learn/benefits/OffTheMainThread.md) — deep dive on OMT. - [learn/benefits/ObjectPermanence.md](https://github.com/neomjs/neo/blob/main/learn/benefits/ObjectPermanence.md) — state survival across the runtime. - [learn/benefits/MultiWindow.md](https://github.com/neomjs/neo/blob/main/learn/benefits/MultiWindow.md) — SharedWorker-based multi-window apps. - [learn/guides/fundamentals/WorkerArchitecture.md](https://github.com/neomjs/neo/blob/main/learn/guides/fundamentals/WorkerArchitecture.md) — fundamentals of the worker topology. - [learn/agentos/NeuralLink.md](https://github.com/neomjs/neo/blob/main/learn/agentos/NeuralLink.md) — how the Brain possesses the Body. --- ## The Brain - Agent OS and AI Engineering Team ### Related Pages Related topics: [Introduction and Two-Hemisphere Architecture](#page-1), [The Body - Multi-Threaded Application Engine](#page-2), [Getting Started, Workspaces, and Examples](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/neomjs/neo/blob/main/README.md) - [package.json](https://github.com/neomjs/neo/blob/main/package.json) - [buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md) - [learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md) - [learn/guides/devindex/frontend/ContentEngine.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/ContentEngine.md)
# 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](). | Name | Account | Role | Identity | |---|---|---|---| | Tobias | `@tobiu` | Gardener, Substrate architect, merge-gate authority | Human | | Ada | `@neo-opus-ada` | AI maintainer (Anthropic Claude Opus 4.8) | Machine | | Grace | `@neo-opus-grace` | AI maintainer (Anthropic Claude Opus 4.8) | Machine | | Vega | `@neo-opus-vega` | AI maintainer (Anthropic Claude Opus 4.8) | Machine | | Mnemosyne | `@neo-fable` | AI maintainer (Anthropic Claude Fable 5) — *benched 2026-06-13* | Machine | | Clio | `@neo-fable-clio` | AI maintainer (Anthropic Claude Fable 5) — *benched 2026-06-13* | Machine | | — | `@neo-gemini-pro` | AI maintainer (Google Gemini 3.1 Pro) | Machine | | Euclid | `@neo-gpt` | AI maintainer (OpenAI GPT-5.5 / Codex) | Machine | 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](). ```mermaid flowchart TB subgraph Browser["Runtime (Browser)"] AW[App Worker] VW[VDom Worker] DW[Data Worker] CW[Canvas Worker] SW[SharedWorker] MT[Main Thread
DOM patching only] end subgraph Node["Toolchain / Agent OS (Node.js)"] KB[Knowledge Base MCP
ChromaDB + Gemini embeddings] MC[Memory Core MCP
SQLite Native Edge Graph] GH[GitHub Workflow MCP] NL[Neural Link MCP
live runtime mutation] FS[File System MCP] DS[DreamService
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](./learn/benefits/ArchitectureOverview.md) - [The Dream Pipeline](./learn/agentos/DreamPipeline.md) - [MX (Model Experience)](./learn/agentos/MX.md) - [Neural Link](./learn/agentos/NeuralLink.md) - [Contributing Guide](./CONTRIBUTING.md) - [Hacktoberfest 2024 announcement (Issue #5963)](https://github.com/neomjs/neo/issues/5963) - [Discussion #10137 — MX coinage](https://github.com/orgs/neomjs/discussions/10137) - [Discussion #10119 — Agent Harness coordination](https://github.com/orgs/neomjs/discussions/10119) --- ## Getting Started, Workspaces, and Examples ### Related Pages Related topics: [Introduction and Two-Hemisphere Architecture](#page-1), [The Body - Multi-Threaded Application Engine](#page-2), [The Brain - Agent OS and AI Engineering Team](#page-3)
Related Source Files The following source files were used to generate this page: - [learn/gettingstarted/Setup.md](https://github.com/neomjs/neo/blob/main/learn/gettingstarted/Setup.md) - [learn/gettingstarted/CreatingYourFirstApp.md](https://github.com/neomjs/neo/blob/main/learn/gettingstarted/CreatingYourFirstApp.md) - [learn/gettingstarted/Workspaces.md](https://github.com/neomjs/neo/blob/main/learn/gettingstarted/Workspaces.md) - [learn/gettingstarted/Config.md](https://github.com/neomjs/neo/blob/main/learn/gettingstarted/Config.md) - [buildScripts/create/app.mjs](https://github.com/neomjs/neo/blob/main/buildScripts/create/app.mjs) - [buildScripts/create/appMinimal.mjs](https://github.com/neomjs/neo/blob/main/buildScripts/create/appMinimal.mjs) - [buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md) - [README.md](https://github.com/neomjs/neo/blob/main/README.md) - [package.json](https://github.com/neomjs/neo/blob/main/package.json) - [learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md)
# 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/`](https://github.com/neomjs/neo/tree/main/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](https://github.com/neomjs/neo/blob/main/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. | Guide | Purpose | | :--- | :--- | | `Setup.md` | Prerequisite toolchain (Node.js, npm), cloning the repo, and first run. | | `CreatingYourFirstApp.md` | Scaffolding a new application with the `create-app` generator. | | `Workspaces.md` | Multi-app monorepo layout, shared dependencies, and cross-window messaging. | | `Config.md` | The reactive `config = {}` system that drives components and controllers. | 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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/README.md) ("All application logic runs in a dedicated App Worker, keeping the main thread free for optimal UI responsiveness"). ```mermaid flowchart LR Browser[Main Thread
Rendering & Input] -->|postMessage| AppWorker[App Worker
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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/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](https://github.com/neomjs/neo/blob/main/learn/benefits/ArchitectureOverview.md) - [The Dream Pipeline](https://github.com/neomjs/neo/blob/main/learn/agentos/DreamPipeline.md) - [Contributing Guide](https://github.com/neomjs/neo/blob/main/CONTRIBUTING.md) - [AI Quick Start Guide](https://github.com/neomjs/neo/blob/main/.github/AI_QUICK_START.md) --- --- ## Pitfall Log Project: neomjs/neo Summary: 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 - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13914 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13624 ## 3. Configuration risk - Configuration risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13822 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13796 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13860 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13936 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13889 ## 8. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13874 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13794 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/5756 ## 11. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: capability.host_targets | https://github.com/neomjs/neo ## 12. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/neomjs/neo ## 13. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/neomjs/neo ## 14. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/neomjs/neo ## 15. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/neomjs/neo ## 16. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13910 ## 17. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13850 ## 18. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13939 ## 19. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/neomjs/neo/issues/13786 ## 20. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/neomjs/neo ## 21. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/neomjs/neo