Agent Institution — mission control for your own standing team of AIs.
Start with the Institution guides for a tour of the cockpit, its data states, and the native vessel.
Agent cards, health and lifecycle controls, and the activity stream in a populated visual scenario.
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?.
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 hereneomjs/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.
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;
- Overview, Focus, and Review perspectives over the same cockpit state;
- dockable and pop-out panes backed by Neo.mjs object permanence and SharedWorker topology;
- a cold, unanswered state when no Fleet transport has supplied a read.
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.
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.
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-startWebpack prints the selected loopback origin. Open the Agent Institution route on that origin:
http://localhost:<reported-port>/apps/agentos/index.html
The browser app boots without a Brain checkout, but it ships no sample fleet: the cockpit reads "not answered yet" until a Fleet transport answers, and an empty registry shows the first-agent call to action. 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.
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-visualInstitution CI runs the isolated unit, component, and E2E contracts from this repository alone.
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 -- --listThe 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:nlThe 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.
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.
For an installed copy, see Updating an installed app. The current development build needs whole-app replacement; it has no automatic update feed yet. The packaging procedure is for maintainers and records the explicit Product, pinned Engine and Brain inputs.
For privacy warnings during agent launch, see macOS permissions, including the current effect of quitting FM on its launched peers.
- 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
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.
MIT — Agent Institution, its native harness, product tests, and visual assets.