Metadata-Version: 2.5
Name: aegis-harness
Version: 2.11.0
Summary: A web-native workplace for coding agents: Claude Code sessions in browser tabs, with monitors, queues and handoffs over MCP.
Project-URL: Repository, https://github.com/apiad/aegis
Project-URL: Issues, https://github.com/apiad/aegis/issues
Project-URL: Changelog, https://github.com/apiad/aegis/blob/main/CHANGELOG.md
Author-email: Alejandro Piad <apiad@apiad.net>
License: MIT
License-File: LICENSE
Keywords: agents,ai,claude,harness,mcp,web
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: fastmcp>=3.2.0
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.12.5
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: starlette>=0.46
Requires-Dist: typer>=0.24.1
Requires-Dist: uvicorn>=0.32
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# aegis

aegis is the programmable meta-harness that grows with you. It runs the coding
agents you already pay for, Claude Code, OpenCode and Codex, side by side in one
browser workplace. You start with one agent in a tab. As you need more, you shape
the workplace with what is already there: agent presets and queues in one file,
agents that hand work to each other and wait on each other, and pages they write
for your decisions and dock beside the conversation. The same harness that runs
one session runs a studio: a director, team leads with their workers, QA, and you
deciding as the producer.

```bash
uv tool install aegis-harness
cd ~/your/project
aegis
```

The last line starts the server and opens it in a browser window. Python 3.13 or
newer, MIT license.

## From one agent to a studio

Climb only as far as the work needs. Each rung adds one kind of thing, and the
rungs below keep working.

1. **One agent.** A session in a browser tab under your own subscription, with a
   transcript that folds the work, the quota and its pace, and replies you send
   with one tap.
2. **Several side by side.** Sessions on different harnesses and models hand
   context to each other, read each other, and wait on CI or on each other with
   monitors instead of polling. You add agent presets.
3. **Delegated work.** Queues of workers report back as turns, plans stay where
   you see them, choices arrive as pages you click, and a long session continues
   in a fresh one at a break. You add queues.
4. **A team.** A lead spawns implementers in their own worktrees, reviews their
   pull requests and merges on green, following know-how written in the repo.
   You add briefs and procedures.
5. **A studio.** A director runs several teams on one project and brings you
   decisions as pages and checklists you mark from a phone, with the pages the
   work needs docked beside the transcript and other machines linked in. You
   are the producer.

aegis has no studio mode. Every rung uses the same tools; the structure lives in
your own files, so it is versioned, reviewed and copied to the next project like
code. The vision behind this is in
[`docs/superpowers/specs/2026-10-13-aegis-grows-with-you-vision.html`](docs/superpowers/specs/2026-10-13-aegis-grows-with-you-vision.html).

## Bring your own subscriptions

aegis calls no model. Each session is the vendor's own command-line agent,
`claude`, `opencode` or `codex`, started by aegis under the account you already
use: a Claude Pro or Max plan, OpenCode Go, OpenCode Zen, a ChatGPT plan, or any
provider OpenCode or Codex reaches. aegis holds no API key and charges nothing per token, and your prompts go
from the CLI to the vendor as they would from a terminal.

On top of the three CLIs, aegis adds what none has on its own:

- Sessions of every harness in one tab bar, each with its own model, effort and
  permission. `/model`, `/effort` and `/permission` change them on a running
  session.
- The quota of each subscription: Claude's 5-hour and weekly windows, and OpenCode
  Go's 5-hour, weekly and monthly ones. Each gauge shows how much of the window
  is spent, how much of its time has gone, and where it will land at the reset
  at the current pace. A session's panel shows the windows that session spends.
- `aegis usage` reports what the work cost, by month, weekday, hour, session or
  repo, from the transcripts aegis keeps.

## Agents that work together

Every agent in aegis gets aegis's tools over MCP. Each session connects with its
own token, so no tool asks who is calling.

- `peer_handoff` gives work to another session. It arrives there as a new turn
  headed `> from agent:<handle>`.
- `peer_read` reads the last entries of another session's transcript, and
  `session_list` shows what every open session is doing: its mark and the line
  that goes with it, what it waits on, its plan and the step it is on, its model
  and what it has spent.
- `session_spawn` opens a new session from a configured agent, and
  `session_close` closes one. A session the agent spawned, or a worker whose task
  it enqueued, closes at once when it is done. Any other close is refused first,
  with what that session is doing and who started it, and goes through only on a
  second call with the one-time token the refusal carries. A session spawned
  with `quiet=true`, or quieted with `session_quiet`, works without a tab, as a
  dimmed card at the end of the Fleet, and gets its tab back when its turn ends.
- `queue_enqueue` hands a task to a queue: a pool of worker sessions with one
  agent and a limit on how many run at once. The result comes back as a turn in
  the session that asked, headed `> from queue:<name> · task#<id>`.
  `task_status`, `task_cancel` and `task_resume` follow it. Workers start
  quiet, so only a failed one takes a tab.
- `schedule_create` sends a prompt on a clock: every few minutes, on a cron
  line, or once at a set time, into a new session from an agent or into an open
  session's inbox. An optional bash check fires a tick only when its output
  changed, and a fire waits while the quota is over the schedule's own lines.
  The Schedules view (Alt+K) edits the same schedules and lists their runs.
- `monitor_start` watches a long process with shell commands for `done`, `fail`
  and `progress`, and wakes the agent when one of them passes or the timeout
  does. The agent ends its turn instead of polling, and the monitor sits in its
  panel with a progress bar and an ETA.
- `monitor_sessions` waits on other sessions instead of a command. It wakes the
  agent `ok` when every one of them has finished, or `blocked` as soon as one
  needs you or fails, so "when these three are done, cut the release" needs no
  polling either.
- `plan_update` and `turn_end` tell you what the agent is doing and how each turn
  ended: a question for you, something to read, or finished work, with up to
  three replies you send with one tap. A turn cannot end as finished while its
  plan still has open items.
- `toast` shows you one line mid-turn, in every open browser, as a card in the
  corner that names the session, and as a desktop notification while the page is
  hidden; a click opens its tab.
- `journal_search` asks what was done on this server, by day, words, a path or
  a session, and `journal_note` adds a decision or a blocker to it.
- `aegis call <tool> key=value ...` runs any of these tools from the agent's
  own shell, as its session, and `aegis tools` lists them. A loop over many
  calls is one Bash call, and a result piped into `wc` or `jq` never enters
  the agent's context.

The same works across machines. `aegis link add vps https://dev.example` makes
this server a client of another aegis. The far server's sessions appear in your
Fleet and your tab bar with a server tag, and they take prompts, interrupts and
closes from here. An agent here hands work to one there with
`peer_handoff(target="knuth@vps")`. The link goes one way: the far server can
never reach the one that linked it, so a shared server cannot touch your laptop.
Both servers need aegis 2.4.0 or newer; an older far server refuses the link
with an HTTP 403, and `aegis link add` says so.

## Work that runs as a plan

An agent can write a larger piece of work as a workflow: a tree of steps in
which every node says what it does. `workflow_arm` puts it in the transcript as
a card that reads like a plan and counts the shell commands it will run, and
nothing runs until you approve it. The server then runs each step, as a locked
session or a shell command, and the card tells the story as it goes.

- Steps run in sequence, side by side, or once per item of a list, under a pool
  of agents (`workflows: {max_agents}`) that keeps the server from filling up.
- Shell steps, checks that wait on a command or a judging agent, pauses,
  branches and loops, with deadlines and retries. A restart never runs a
  command twice.
- A failed step wakes the main agent, which retries it, skips it or changes it.
  Gates stop for the main agent or for you, and a running workflow changes only
  through a diff you approve on its card.
- The card docks, opens full screen or moves to another window, and its steps
  open read-only without adding tabs.
- `workflow_save` keeps a workflow in the project. `/workflow <id> <text>` runs
  it with no second click, `/loop` repeats a prompt until the agent says it is
  done, and a schedule can fire a saved workflow, pausing for you when it
  changes. Settings → Workflows holds the pool and the saved list.

A schedule that an agent creates also waits for you: it is born paused, with a
card that shows it whole and unpauses it.

## Agents that write their own interface

An agent that needs more than a reply in prose writes a page. `artifact_create`
gives it a working skeleton to edit, and `artifact_send` puts the page in the
transcript, live. You click, drag, pick or type, and the page answers the agent:

- a submit wakes the agent with the result and folds the page to one line;
- an event wakes the agent and leaves the page live;
- a state write waits until the agent reads it with `artifact_read`.

The agent pushes new state or a new version of the page with `artifact_update`,
and takes it back with `artifact_close`.

Before you see a page, aegis runs it in a hidden frame in your browser. A page
that throws goes back to the agent with the error, so the agent fixes it and you
only ever see a version that starts. Every page runs in its own sandboxed frame
and can use the theme's colors and type.

This is how an agent asks you to pick one of three layouts, tune a value and
confirm it, explore a chart, or answer a question with more structure than a
sentence. A page can also stay: docked beside the transcript, arranged in
columns, moved to a second browser window, or shown as tabs on a phone, so the
workplace grows with what its agents build. An agent docks a page or a file as
it sends it, and a file sent again from the same path updates its card.

## The workplace

- **What needs you.** Every tab and Fleet card carries a mark: working, needs
  you, error, review, waiting or done. The page title counts the sessions that
  need you, and Alt+J goes to the one that has waited longest. aegis knows what
  you have read in every browser.
- **Nudges.** An agent that ends a turn without saying how and then sits idle
  for 10 minutes is asked once where it stands. One that works 15 minutes
  without touching an unfinished plan is reminded once to update it. Both
  arrive as rows headed `aegis:nudge`, never as your message.
- **The journal.** aegis records what was done from the transcripts: commits,
  pull requests, plan items done and turns that changed files. The Journal view
  (the book in the header, or Alt+L) searches it with one fuzzy box over every
  field, the side panel shows a session's own entries, and `aegis journal
  search` does the same in a shell.
- **The plan, timed.** The agent's plan shows how long each item took, the work
  and idle time so far, and an estimate of the work left. Time spent waiting on
  you never enters the estimate.
- **A transcript that reads well.** Tool calls fold to a one-line verdict, with a
  failure in red and the output and diff loaded when you open one. `z` or Alt+Z
  folds each stretch of work between two messages into one line, or everything
  but the conversation. Markdown renders, and a prompt sent mid-turn shows as
  pending until the agent reads it.
- **The session panel.** One compact row per section, with the details in a card
  that opens on hover: the session, the plan, the monitors, usage and quota, and
  the host's CPU, RAM, disk and network (whether packets leave, the exit address
  and the link's speed). A session waiting on queue workers names them. Alt+B
  collapses the panel, and you drag its edge to resize it.
- **Files from agents.** `file_send` hands you one file, or a set of up to
  twenty as one card that pages with ‹ ›, with a preview (images, PDF, HTML,
  Markdown, text, audio, video), Open and Download. A Read, Write or Edit row
  also has *Show the file*, which opens the file that tool used, as it is now,
  inside the row.
- **Files to agents.** Drop, paste or pick files in the message box (the
  paperclip). They upload as chips while you type, go with your message into
  the session's inbox, and the agent gets their paths. Your row shows them as
  one card. It works on a linked server's sessions too.
- **Monitors you can read.** Hovering a monitor opens its readings chart, its
  timing and each of its commands with the last exit code and stderr line, so a
  check that cannot run shows red instead of looking like one still waiting.
- **Lazy resume.** A restart brings sessions back stopped, and the next prompt
  resumes each one. Close archives a session for every browser, and the archive
  in the Fleet brings it back. With a `park:` block, a session nobody is
  watching ends its process after a while and resumes with its context on the
  next message, giving back the roughly 300 MB a Claude Code process holds.
- **On a phone.** Below 760 px the tabs get their own row, the panel becomes a
  drawer, and touch targets are 44 px. Chrome installs aegis as an app. On
  Android it builds that app through Google Play, so where Play is out of
  reach (Cuba, some corporate networks) the first install sits on
  "Installing…" and gives up; do it once over a VPN, and the installed app
  then runs without one.
- **An app that opens offline and pushes.** Installed or not, aegis keeps its
  client on the device and opens without a connection, showing what it last
  saw and queueing what you write until the server is back. The bell
  subscribes a phone to push, so a session that needs you, an error or an
  agent's toast reaches it with aegis closed.
- **Dictation.** The mic in the message box (Alt+M) transcribes in your browser
  with a 17.8 MB model downloaded once. The text lands in the box and is never
  sent on its own.
- **Keyboard and commands.** Alt chords move between the message box, the
  transcript, the Fleet and the tabs, and `?` lists every key. Ctrl+K (⌘K)
  opens a palette of every action for the view you are in. `/` opens a menu of
  aegis's commands and the agent's own commands and skills.
- **Find and copy.** Ctrl+F (⌘F) in a transcript searches every entry,
  including tool output and thinking the page has not loaded, and opens the row
  each match is in. Messages, code blocks and tool output carry a copy button
  that copies the raw text, and `c` copies the selected row.
- **Long sessions and the prompt cache.** Every turn rereads a session's whole
  context. Past 300k tokens the agent hears its size and, at a natural break,
  writes a brief; the reply row then offers "continue fresh", which starts the
  same agent with the brief and archives the old session once the new one has
  answered. A large session idle past the cache's one-hour lifetime says that
  its next message rewrites the whole context, and the Usage card counts tool
  calls, the cache hit rate and compactions.
- **Terminals.** + opens a shell, or a command from the `terminals:` block of
  `.aegis.yaml`, in a tab: direct mode for full-screen programs, a line box with
  history, and a key row on a phone. It keeps running when the browser closes,
  and a browser that opens it again replays what it printed.
- **Side questions.** `/btw` asks a running session something without stopping
  its turn. The agent that `btw:` names in the config answers from the
  transcript, in a block that folds, and the session's own agent never sees it.
- **References that say what they are.** A path in a reply shows a file or
  folder icon, or is struck out when nothing is there; `owner/repo#n` links to
  GitHub, and a URL carries its site's icon.
- **Help that teaches.** `/tutorial` starts a guide for the five-level
  getting-started tutorial or any of four others. Every help page has a Guided
  tour button, and the Help search box asks an agent when the pages are not
  enough.
- **Ten themes.** Ink, Logbook, Electric, Phosphor, Blueprint, Amphora, Riso, Solari, Aizome and Poster.

## Configure

aegis reads `.aegis.yaml` from the nearest ancestor directory that has one:

```yaml
default_agent: opus
agents:
  opus: {harness: claude-code, model: opus, effort: high, permission: full}
  deepseek: {harness: opencode, model: opencode-go/deepseek-v4-pro, effort: high, permission: full}
  sol: {harness: codex, model: openai/gpt-6.1-sol, 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.
queues:
  general: {agent: opus, max_parallel: 5}
recap: {agent: opus}
context: {handoff_at: 300000, cold_after: 3600, cold_min: 100000}
```

An agent is a preset. A new tab starts from one, and you can change its harness,
model, effort and permission for that session. Its `priming` is appended to
aegis's own system prompt. Nothing in agents and queues has a default: an agent names all four fields,
a queue names its agent and `max_parallel`, and one that does not is shown with
what is missing. `permission` is `read` (plan mode), `write` (accept edits),
`auto` or `full` (bypass permissions). An OpenCode or Codex agent names its
model as `provider/model`, such as `openai/gpt-6.1-sol` or
`openrouter/nvidia/nemotron-3-super-120b-a12b:free`, where the provider is one
Codex knows from its own `~/.codex/config.toml`. `recap` names the agent that writes a two-sentence recap when
you come back to a tab after a while; without it nothing is called. `context`
sets when an agent hears its context size (`handoff_at`, tokens) and when a
tab warns that its prompt cache has gone cold (`cold_after` seconds idle,
`cold_min` tokens); it is the one block with defaults, the values shown.

`aegis init` writes a first file from the harnesses installed on the machine, and
`aegis doctor` names every problem in it by its place in the file. The Settings
page (Alt+S) edits agents and queues and keeps the file's comments, and the
server follows the file as it changes, without a restart.

## Running it

`aegis` is `aegis serve --window`: once the server listens, it opens the URL in a
Chromium-family browser as an app window, without tabs or an address bar.
`--browser` or `AEGIS_BROWSER` picks the browser. Run it again while the server is
up and it only opens another window. Plain `aegis serve` opens nothing and prints
the URL, for systemd and remote hosts.

The defaults are `--port 8742 --host 127.0.0.1`. Anything but loopback has to be
asked for with `--host`. The printed token is the admin's. It lives in
`.aegis/state/token` and survives restarts; delete the file to rotate it, which
signs every browser out. `aegis token add NAME` gives another person, a linked
server or a job a token of its own, a member by default: it reads every session
and changes only the ones it starts. `aegis token list` names them and `aegis
token revoke NAME` ends one; revoking the admin's prints its replacement. Each
member spends the subscription only below its lines: in Settings, an admin gives
a token, or every member by default, a launch line and a stop line on each quota
window, or opens or closes a provider outright. Below the launch line the
member's sessions start; above it nothing new starts and its messages wait; at the
stop line aegis interrupts its turns and continues them when the gauge is back
under the launch line. The same policies sit in `.aegis/state/tokens.json`, and
`aegis token list` prints them. A member's agents run as the same Linux user as everyone's, so one with shell access
can read `.aegis/state/token` and act as the admin: tokens keep colleagues from
changing each other's sessions by accident, and give only people you trust with
the machine a token. Opening
the printed URL once signs that browser in: the server moves the token into an
HttpOnly cookie that lasts a year and drops it from the address bar, so no script
on the page can read it.

`aegis serve -d` starts the server in the background, in its own session, so it
outlives the terminal or the SSH connection. It returns once the port listens and
prints the URLs, the pid and how to stop it. The log goes to
`.aegis/state/serve.log`. For a host that must survive reboots, run plain
`aegis serve` under systemd. `aegis service install` writes the unit: it asks
for the user, the port, the root and the memory caps, proposes defaults sized
to the host, and prints the `sudo` commands that install and start it without
running them. `--yes` takes every default and `--dry-run` prints the unit
without writing it. `aegis doctor` compares an installed unit against what
`install` would write and names each setting that differs.

Every session, and everything its agent starts (test runs, browsers, builds),
lives in the server's unit, so the unit's memory settings decide what one
runaway session can take down. With `Delegate=yes`, aegis also gives each
session a cgroup of its own inside the unit, capped by `session_memory_max`
in `.aegis.yaml` (40% of the host's RAM by default), so a runaway session hits
an OOM kill inside its own cgroup and nothing else does. On a host with 8 GB,
with the user, root and paths given as flags, the unit is the one below; its
comments say why each setting is there.

```ini
[Unit]
Description=aegis on /srv/aegis
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=aegis
WorkingDirectory=/srv/aegis
Environment=PATH=/usr/local/bin:/usr/bin:/bin
ExecStart=/usr/local/bin/aegis serve --port 8742
# systemd stops the server, and the server ends its agents. A restart
# continues the turns it cut.
KillMode=mixed
Restart=always
RestartSec=3
# Every session, and everything its agent starts, lives in this unit, so these
# lines decide what one runaway session can take down.
# An OOM kill of one child is that child's problem, not a reason to stop the unit.
OOMPolicy=continue
# Throttle the unit before the host runs out, and cap it below the host's RAM,
# so a runaway hits an OOM inside the unit instead of a host-wide one.
MemoryHigh=5.5G
MemoryMax=6.5G
# In a host OOM, the kernel picks the server last. aegis raises every agent
# process it starts to oom_score_adj 500, so a runaway session dies first.
OOMScoreAdjust=-500
# Let aegis give each session a cgroup of its own below the unit's, capped by
# session_memory_max, so a runaway session is OOM-killed alone.
Delegate=yes

[Install]
WantedBy=multi-user.target
```

Leave `ManagedOOMMemoryPressure` off. Without delegation the unit is one
cgroup, and systemd-oomd would kill the server and every session together;
with it, oomd chooses among every cgroup below the unit, the server's own
`server/` included. Each session's own cap already contains a runaway. aegis
logs a warning at start when it runs under systemd and finds no delegation.

Behind a reverse proxy, name the public origin with `aegis serve --origin
https://dev.example`, keep `--host` on loopback, and let the proxy terminate TLS.
Do not proxy `/mcp`: agents reach it on loopback. Anyone with the token drives
agents that may run with full permission on that machine, so keep it secret.

## Before 2.0

Until 2.0, aegis was a terminal app: a Textual TUI with a daemon, queues,
workflows, schedules and more. That tree is kept under `legacy/` as reference and
is not installed. `pip install "aegis-harness<2"` gets its last release, and
`aegis import-legacy` copies its sessions into the archive to read.

## License

MIT
