aegis serve runs Claude Code and OpenCode sessions on your machine and serves them to browser tabs: a Fleet view, shared tabs, a transcript per session, and an archive. The agents in it get monitors, queues of workers and handoffs over MCP, and an inbox that delivers what those produce.
uv tool install aegis-harness
cd ~/your/project
aegisThe last line serves and opens a browser window. Version 2.3.0 on PyPI, MIT licence, Python 3.13 or newer.
Scroll. The window on the right follows the feature you are reading.
Each tab and Fleet card carries one of six marks: working, needs you, error, review, waiting or done. The Fleet orders cards by that mark and puts the ones that block on you first, oldest wait on top. Alt+J goes to the session that has waited longest.
aegis knows what you have read on every browser. The page title counts the sessions that need you, and a review you already read drops out of the group.
A tool row closes on a one-line verdict, a failure in red. The output and the diff load when you open a row. Agent prose renders as Markdown in a reading face. A prompt sent mid-turn shows as pending until the agent reads it, and Esc interrupts.
The sidebar carries what the agent reported: its plan with the item it is on, its monitors with their progress and ETA, the context window as a bar, the cost so far, and your Claude quota windows. Hovering a monitor opens its readings chart and each of its checks with the last exit code, so a check that cannot run shows red instead of looking like one still waiting.
An agent ends each turn by saying how it ended and may offer up to three replies, which you send with one tap. /model, /effort and /permission switch a running session; / opens a menu that completes them, and an unknown command is refused rather than sent as a prompt. Alt+M dictates into the box, transcribed in the browser.
Over MCP an agent starts a monitor with a bash done condition and is woken when it holds, hands a self-contained task to a fresh worker on a queue, reads a peer's transcript or hands it an instruction, and gives you a file that shows as a card with a preview. What those produce comes back as an inbox entry in the transcript.
Below 760 px the tabs get their own row, the side panel becomes a drawer, and touch targets are 44 px. Chrome installs aegis from its menu as an app named after the server. A return to one of the last eight tabs, or a reconnect after the phone slept, sends only what changed.
The Fleet band carries the session counts, the host's CPU, RAM and disk, the average context of the live sessions, and your Claude and OpenCode Go quota windows: the share already spent, where the window is heading at this pace, and when it resets.
The hang is a race. The test awaits recv() with no timeout, and when the server closes first that await never returns. Three of twenty runs hit it here, so CI hits it about once a day.
String to replace not found in file. String: msg = await ws.recv()
Two fixes pass locally. Capping the wait at 25 s fails the run loudly instead of hanging it. Mocking the socket removes the race from the test but also the thing it tests. I lean to the cap.
done: gh run view 4821 --json status -q .status | grep -qv in_progress progress: gh run view 4821 --json jobs -q '[.jobs[]|select(.status=="completed")]|length*100/6'
The run finished: 6 of 6 jobs completed, conclusion success.
Migration 0042 adds the audit table with its two indexes. The migration test passes forward and back. Committed on the branch as 3f9c2a1.
aegis reads .aegis.yaml at the root of your project. An agent is a preset of harness, model, effort and permission; a queue names the agent its workers run as and how many run at once. The new tab starts from a preset and can change any field for that session. aegis init writes a first file from the harnesses installed on the machine, aegis doctor names every problem by its place in the file, and the server follows the file as it changes.
default_agent: opus
agents:
opus: {harness: claude-code, model: opus, effort: high, permission: full}
reviewer:
harness: claude-code
model: opus
effort: max
permission: read
priming: |
You review changes for correctness and report findings by severity.
local: {harness: opencode, model: ollama/qwen3:32b, effort: medium, permission: write}
queues:
general: {agent: opus, max_parallel: 5}
recap: {agent: opus}Permission is read for plan mode, write to accept edits, auto, or full to bypass permissions. The optional recap names the agent that writes a two-sentence recap when you come back to a tab after a while.
Every session's harness connects to /mcp with its own token, so no tool asks who is calling. The tools are named mcp__aegis__<verb>.
Ink is the warm dark palette of the terminal app aegis used to be. Logbook is a daylight lab notebook with times in the margin. Syalia is the house design system, with tool calls as chips.
The hang is a race in recv().
Ink
The hang is a race in recv().
Logbook
The hang is a race in recv().
Syalia
aegis serve listens on loopback at port 8742 and prints a URL with a token. Opening it once signs that browser in: the token moves into an HttpOnly cookie that lasts a year. aegis serve -d detaches and outlives the terminal or the SSH connection. Behind a reverse proxy, --origin https://dev.example names the public origin, and the proxy terminates TLS. Agents reach /mcp on loopback, so do not proxy it. A restart brings sessions back stopped, and the next prompt resumes each one.