neo-agent-institution

Agent Institution — mission control for your own standing team of AIs.

The checked-in visual golden exercises the honest offline/static-roster state; a connected Brain supplies live fleet state.

What is the Institution?

Neo.mjs is a professional, end-to-end AI engineering team whose Body, Brain, and operator product
live in focused open-source repositories.

One model in one context window can be productive, but it has one distribution of blind spots and
forgets the institution when the session closes. Neo.mjs instead gives named maintainers durable
memory, peers from different model families, the right to challenge, and cross-family review under
a human merge gate.

The Institution makes that team operable. Agent Institution is the application where an operator
sees the roster, health, work, memories, messages, wake state, and lifecycle controls of an agent
team. This repository is the product source; the app is the intended starting point for running
the institution.

Other teams do not rent Neo's maintainers. They run their own agents, identities, credentials,
projects, memory, and review culture on the same operating model. Read the canonical organization
story in What Is Neo.mjs?.

The organization map

• neomjs/neo — Body / Engine: the multi-threaded application
  runtime Agent Institution is built on.
• neomjs/neo-agent-brain — Brain / Agent OS:
  institutional memory, repository knowledge, coordination, and runtime services.
• neomjs/neo-agent-institution — Agent Institution: the operator-facing product. ← You are here
• neomjs/devindex — DevIndex: the GitHub meritocracy
  index, its application, and its data factory.
• neomjs/neo-agent-skills — Skills: the canonical
  installable working discipline shared by the repositories.

What Agent Institution operates

The current cockpit includes:

• a fleet roster with provider/family identity, health, freshness, and lifecycle state;
• activity, task, memory, mailbox, wake, and catch-up surfaces;
• account and agent-definition setup with explicit credential boundaries;
• instance/tenant switching and reason-carrying connection state;
• Fleet, Focus, and Review perspectives over the same cockpit state;
• dockable and pop-out panes backed by Neo.mjs object permanence and SharedWorker topology;
• an honest static/offline fallback when no Fleet transport is connected.

Lifecycle controls act through the connected Brain/Fleet service; the UI does not import or copy
Brain implementation. The current source path remains apps/agentos for compatibility, but the
product and repository identity is Agent Institution.

Architecture

Operator → Agent Institution (this repository)
              ├─ renders on → neo.mjs Engine
              ├─ operates   → neo-agent-brain over the Fleet transport
              └─ applies    → neo-agent-skills in each maintained repository

• Engine is a pinned package dependency. Institution imports Body classes from neo.mjs; it
  does not carry an Engine source mirror.
• Brain is an explicit sibling runtime. Full-contract tests and the native harness receive an
  absolute NEO_AGENTOS_RUNTIME_ROOT; cwd and guessed sibling paths are not authority.
• Institution owns the product. Application source, themes, Electron shell, product tests, and
  visual goldens live here.

Browser quickstart

Requirements: Git and Node.js 24 or newer.

git clone https://github.com/neomjs/neo-agent-institution.git
cd neo-agent-institution
npm install
npm run server-start

Webpack prints the selected loopback origin. Open the Agent Institution route on that origin:

http://localhost:<reported-port>/apps/agentos/index.html

The browser app can render its static roster without a Brain checkout. Live state and lifecycle
actions require a reachable Fleet transport from a configured Brain deployment.

npm install resolves the pinned Engine package and materializes the public Skills surface. It
does not grant Neo maintainer identity or copy private credentials into the checkout.

Contributor mode vs. live institution mode

Public contributor workflow

Ordinary contributors can install, run the browser app, and execute the isolated suites without a
Brain checkout, Docker, or Neo maintainer credentials:

npm run test-unit
npm run test-components
npm run test-e2e
npm run test-visual

Institution CI runs the isolated unit, component, and E2E contracts from this repository alone.

Brain-connected maintainer workflow

The full cross-repository contract uses an explicit absolute Brain checkout:

NEO_AGENTOS_RUNTIME_ROOT=/absolute/path/to/neo-agent-brain npm run test-unit
NEO_AGENTOS_RUNTIME_ROOT=/absolute/path/to/neo-agent-brain npm run test-e2e -- --list

The cockpit's Neural Link witnesses (test/playwright/e2e/agentos/*NL.spec.mjs plus
FleetGridKeyboardA11y — docking, drill, pop-out, tear-out, rail reveal, perspective presets,
liveness, N-window, viewer wake, the activity pool, the empty fleet, catch-up, memories, the
operator mailbox, the card at vessel widths, keyboard selection) run in no CI job. They are the
product's proof surface, so run them locally before and after any dock, cockpit-chrome, or
Engine-pin change:

NEO_AGENTOS_RUNTIME_ROOT=/absolute/path/to/neo-agent-brain npm run test-e2e:nl

The script reaches every Neural Link witness under test/playwright/e2e/agentos/ — a suffix
match, not a prefix, so a new witness joins the battery by its name, and a red one announces
itself instead of falling outside the glob. Add -- --headed for the honest receipt. The battery's
one long-standing red has closed: FleetCockpitDockNL's Review-preset arm, the FLIP-settle hold
(#103) — the projection staged the detail pane in the right band and un-hid it on the settle, which
did not always land within the wait — is green headless and headed at engine pin 7e8b32e421, since
Review docks the inspector as a center column (#133), a real split child rather than a revealed rail
member; the engine half of the settle was neomjs/neo#18297. A red there is a regression to triage,
not a race to re-run. FleetGridKeyboardA11y's
reorder step went green with #99 — cards and list items key by record, so a joiner sorting ahead
moves the focused node instead of replacing it (the Engine of #98 sorts a joiner by its tier, which
is what exposed the positional ids). FleetGridScaleNL went green with #98 — the Engine writes its
unfiltered projection inside the mutation (neomjs/neo#18269), so the roster's fold decides on the
whole batch and the cards it renders are the records it holds; AddAgentJourneyNL went green with
#74. FleetActivityStreamBurstNL and the FleetCockpitDockNL presets arm went green with Engine
pin 7 (#120), and the seven vessel witnesses (pop-out, tear-out, N-window, kinetic, drill,
permanence) read the Engine's tear-out owner since that pin: ownership through isVesselOwned /
isVesselPending, the return by closing the vessel window — never a consumer disconnect seam.

Live maintainer seats also require their own local GitHub token, remote MCP bearer, and agent
identity configuration. For Neo's team these include GH_TOKEN, NEO_MCP_REMOTE_TOKEN, and
NEO_AGENT_IDENTITY; other institutions supply their own values and identities. Never commit
tokens, .env values, or generated seat configuration.

Native harness status

The optional Electron shell lives under harness/. It is the native vessel
around the same Agent Institution app, not a second UI and not a Brain source owner.

The post-split packaged launcher is transitional: #4
owns explicit product/Engine/Brain roots, checkout launch without accidental Brain loading, and
pack-stage closure. Until that ticket lands, this README does not claim a downloadable or
one-command packaged Institution.

Read next

• The canonical Neo.mjs Introduction
• The Brain / Agent OS
• The Engine / Body
• The canonical Skills package
• Agent Institution product direction — D#10119
• Institution Cockpit design epic

Contributing

Work targets dev; main is release-only. Every pull request must reference an existing
Institution issue. Product identity
changes require cross-family review before merge.

License

MIT — Agent Institution, its native harness, product tests, and visual assets.