aegis: Instructions file for Codex

aegis

aegis is a web-native workplace for coding agents. aegis serve runs Claude Code, OpenCode and Codex sessions on one machine and serves them to browser tabs: a Fleet view, shared tabs, a transcript per session, and an archive. Agents in it get aegis's tools over MCP: monitors, queues of workers, handoffs, reading a peer, and an inbox that delivers what those produce. It is published on PyPI as aegis-harness, and it is the workplace Alex and his agents use for multi-agent work in this workspace.

Until 2.0 aegis was a terminal app. That tree lives under legacy/ as reference: not packaged, not tested, not launchable. Read it to learn how something was done; never import it. Its design is legacy/DESIGN.md.

Read this file, then DESIGN.md, then the know-how doc for the job in front of you. This file changes when aegis's goals change. Nothing in it should be made false by a commit that adds a module, a tool or a test.

What done means

A change is done when:

1. the tests that cover the change pass locally, and nothing more: run the test files you touched and their neighbours while you iterate, plus make lint-docs when a doc or help page changed. The whole suite is CI's job, not yours;
2. CI is green on the PR. It runs the whole hermetic suite, slow and browser tests included, with format, lint, typecheck, rift and the changelog check, and compares the bench of the PR's base and head in its job summary. Copy that table into the PR body: CI warns on a regression and never fails on one, so a reader has to look at it;
3. it has been exercised in a browser against an aegis serve started after the change, and, for a change to how agents use aegis, by the make test-live case that covers it, run on its own (-k), not the whole live suite;
4. DESIGN.md describes the code as it now is;
5. a user-visible change has a changelog.d/ fragment and updates or adds its help page under src/aegis/help/, and a change to how the pieces fit has its spec under docs/superpowers/specs/, with a status that matches the code;
6. before a release, Alex has smoke-tested that version himself. Offer him the guided smoke test then, not per PR: the build under test runs through bin/aegis-dev beside his own aegis, and an agent inside it walks him through what changed since the last tag, simplest first, asking after each step whether it works. File what the tour finds as issues unless the fix on main is trivial. Every check above is a proxy; his hands on the build are the gate, and a release he has not run is not done.