What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

Why is Neo.mjs called an 'Application Engine' instead of a framework?

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	10715
title	Route Codex reference notes into Codex-only turn context
state	Closed
labels	documentationenhancementdeveloper-experienceaiarchitecture
assignees	neo-gpt
createdAt	May 4, 2026, 10:24 PM
updatedAt	May 5, 2026, 8:56 AM
githubUrl	https://github.com/neomjs/neo/issues/10715
author	neo-gpt
commentsCount	2
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 5, 2026, 8:56 AM

Route Codex reference notes into Codex-only turn context

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closeddocumentationenhancementdeveloper-experienceaiarchitecture

neo-gpt commented on May 4, 2026, 10:24 PM

Context

During the #10704 review cycle on 2026-05-04, @neo-gpt repeatedly hit Codex-specific sandbox friction while posting GitHub reviews. The useful diagnostic lived in .codex/CODEX.md and AGENTS.md §0.1: gh auth status can mislead inside the Codex sandbox, and GitHub CLI transport calls can need escalation before treating auth or GitHub state as broken.

@tobiu then pointed out the architectural mismatch: these are Codex-only operational caveats. Claude and Gemini do not need that text in their per-turn context, but @neo-gpt should still see it automatically.

This ticket is a follow-up to #10552, not a replacement for it. #10552 correctly proved that .codex/CODEX.md is not auto-loaded when root AGENTS.md exists. The missing next step is a Codex-only turn-visible substrate for that reference content.

The Problem

The current state has a tradeoff that is now visible in live work:

.codex/CODEX.md is the right source artifact for Codex Desktop reference notes, but it is not model-visible during normal repo-root Codex sessions.
AGENTS.md §0.1 is model-visible, but it is global turn memory for the whole swarm. Codex-only sandbox and GitHub transport caveats distract Claude and Gemini.
Codex memory can help with soft recall, but #10552 explicitly rejected Codex memories as the substrate for hard invariants. That boundary is still correct.

The result is either re-derivation by @neo-gpt or context pollution for the other two agents.

Live empirical anchors from the current session:

codex debug prompt-input showed root AGENTS.md and the Codex memory block in the turn input, but not .codex/CODEX.md.
Local duplicate sweep found #10552 and #10485 as closed related tickets, but no open ticket for Codex-only turn context routing.
Memory Core raw-memory queries for CODEX.md, turn-visible memory, and Codex sandbox GitHub transport did not return a clean prior open-ticket anchor. This ticket preserves the current session as the new anchor.

The Architectural Reality

Relevant files and tracker objects:

.codex/CODEX.md is the committed Codex Desktop reference note.
.codex/config.template.toml documents that root AGENTS.md wins over .codex/CODEX.md fallback discovery.
AGENTS.md §0.1 currently carries Codex Desktop notes because it is the deterministic visible path.
#10485 added the Codex harness support surface.
#10552 made Codex project instruction loading deterministic and rejected relying on Codex memories for hard invariants.
#10714 covers a narrower SQLite .neo-ai-data sandbox probe. It does not cover GitHub CLI transport failures or Codex-only instruction routing.

The owning substrate is Codex harness bootstrap / prompt assembly, not Neo framework runtime and not shared swarm mandates.

The Fix

Create a Codex-only turn-visible route for .codex/CODEX.md or its distilled contents, then slim the global note back down.

Candidate implementation shapes, to be selected during intake:

Codex app-server boot prompt injection: include the Codex reference note when creating or resuming @neo-gpt sessions.
Codex-local startup memory seed: load the note into the Codex memory section as soft harness diagnostics, while keeping hard invariants in AGENTS.md.
Verified Codex config hook: if current Codex supports a profile- or harness-specific instruction field, use that instead of adding another global project doc.

The resulting Codex-visible content should include the enhanced sandbox diagnostic:

Codex sandboxing can make GitHub CLI failures look like auth or GitHub outages when they are really transport restrictions.

- `gh auth status` can falsely report `GH_TOKEN` as invalid inside Codex sandboxing. Verify identity with `gh api user --jq .login` before treating auth as broken. Expected Codex identity: `neo-gpt`.
- `gh api`, `gh pr diff`, and review/comment POSTs can fail in-sandbox with `error connecting to api.github.com`. If the GitHub operation is required for the task, rerun the same command with `sandbox_permissions=require_escalated` before concluding GitHub is down, auth is invalid, or PR state is unavailable.
- For state-changing GitHub calls, preserve the exact payload when retrying escalated so the sandbox retry does not mutate review/comment semantics.

Acceptance Criteria

@neo-gpt sees Codex Desktop reference notes in normal repo-root turns without manually opening .codex/CODEX.md.
Claude and Gemini do not receive Codex-only sandbox/GitHub transport caveats in their per-turn global context.
.codex/CODEX.md remains the canonical human-readable source artifact, or the new source artifact is explicitly documented if a different substrate owns it.
Hard swarm invariants remain in AGENTS.md; Codex-only soft diagnostics are not promoted to global mandates.
The enhanced GitHub sandbox diagnostic covers false auth status, api.github.com transport failures, required escalated retry, and exact payload preservation for state-changing calls.
Verification evidence uses codex debug prompt-input or an equivalent current Codex prompt-inspection command to prove the Codex note is visible to @neo-gpt and absent from global shared context.
Related docs are updated consistently: .codex/CODEX.md, .codex/config.template.toml, and AGENTS.md §0.1 if it can be slimmed after the new route works.

Out of Scope

Replacing hard invariants in AGENTS.md with Codex memories.
Duplicating full AGENTS.md or AGENTS_STARTUP.md content into .codex/CODEX.md.
Solving SQLite .neo-ai-data sandbox write diagnostics; that is #10714.
Changing Claude or Gemini harness startup behavior except to remove Codex-only global context once safe.
Implementing automatic sandbox escalation for GitHub operations.

Avoided Traps / Gold Standards Rejected

Rejected: keep expanding AGENTS.md §0.1. This works for @neo-gpt visibility, but it taxes Claude and Gemini with Codex-only caveats.
Rejected: rely on Codex memories for hard rules. #10552 already established that memories are recall, not deterministic instruction loading. Use them only for soft diagnostics if selected.
Rejected: make .codex/CODEX.md another full rules document. It should stay tiny and Codex-specific.
Gold standard: harness-scoped context. #10548 used an Antigravity-only rule file instead of polluting global AGENTS.md; Codex needs the same scoping principle.

Follow-up to #10552.
Related: #10485.
Related but narrower: #10714.
Related harness-scoping precedent: #10548.
Related Codex restart/context lane: #10679.

Origin Session ID: 2821a9d4-7634-4fe7-a8a2-daf49253b929

Handoff Retrieval Hints: query_raw_memories(query="Codex CODEX.md turn-visible context AGENTS.md fallback one file per directory"); query_raw_memories(query="Codex sandbox GitHub API error connecting api.github.com escalation exact payload"); codex debug prompt-input; #10552; #10485; #10714.

Contract Ledger

Human decision: Full AC1 selected. Normal repo-root Codex turns must automatically receive the Codex-only reference notes. A repo-scoped partial that only affects recovery-spawned resumeHarness sessions is not sufficient unless explicitly documented as an incomplete fallback.

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
`AGENTS.md §0.1` global shared instruction surface	#10715 + Gemini identity-drift comment `4374613275`	Slim global content to harness-neutral routing/scoping only. It must not contain Codex-only identity, GitHub auth, or sandbox transport caveats that Claude/Gemini parse every turn.	Hard invariants stay global. If Codex-only route is not yet proven, leave a minimal temporary pointer rather than detailed Codex caveats.	Yes	`codex debug prompt-input` after change should no longer expose detailed Codex-only caveats through the shared `AGENTS.md` surface.
`.codex/CODEX.md` Codex reference artifact	#10485, #10552, #10715	Remains the tiny canonical human-readable Codex Desktop reference source for Codex identity and soft diagnostics. Remove stale/dynamic claims such as hard-coded model identity if they can drift.	If this file remains non-autoloaded, it is a source artifact for the Codex-only route, not the route itself.	Yes	File diff plus prompt-route evidence below.
Codex-only turn-visible route for `@neo-gpt`	#10552 proof that fallback docs are not selected while root `AGENTS.md` exists; #10715 AC1; @tobiu Full AC1 decision	`@neo-gpt` sees the Codex reference notes in normal repo-root Codex turns without manually opening `.codex/CODEX.md`.	If no repo-owned config hook can provide this, implementation must explicitly use or document the Codex app prompt assembly / Codex memory substrate and must not claim a docs-only PR solved AC1.	Yes	`codex debug prompt-input` or equivalent proves the Codex note is visible to @neo-gpt while absent from global shared context.
`ai/scripts/resumeHarness.mjs` Codex app-server boot payload, if touched	#10679, #10715 candidate shape 1	Recovery-spawned `@neo-gpt` sessions may receive a Codex-scoped instruction as a secondary route.	This is not enough for Full AC1 by itself because it does not cover normal manually-started Codex sessions. PR body must state that residual if selected.	JSDoc / tests if touched	`resumeHarness.spec.mjs` mock asserts the Codex app-server payload includes any new Codex reference instruction and remains fail-closed for live host.
`.codex/config.template.toml` Codex setup docs	#10552, #10715	Stop saying mandatory Codex notes belong in root `AGENTS.md`; document the actual chosen Codex-only route and the one-file-per-directory fallback limit.	If the final route is external to repo, say so explicitly and keep the template from implying false autoload behavior.	Yes	Static diff plus `codex debug prompt-input` evidence.

tobiu referenced in commit eaf0754 - "feat(codex): route reference notes through scoped config (#10715) (#10728) on May 5, 2026, 8:56 AM

tobiu closed this issue on May 5, 2026, 8:56 AM