aegis
A web-native workplace for coding agents. aegis serve runs Claude Code sessions on
your machine and serves them to browser tabs; agents in it get monitors, queues of
workers and handoffs over MCP.
Install and run
uv tool install aegis-harness
cd ~/your/project # the nearest ancestor with .aegis.yaml is the root
aegis # serves, and opens it in a browser app window
aegis is aegis serve --window: once the server listens it opens the URL in a
Chromium-family browser with --app=, a window without tabs or address bar (the
desktop default if it is Chromium-family, else the first Chrome, Chromium, Edge or
Brave found; --browser or AEGIS_BROWSER picks another). Run it again while the
server is up and it only opens another window. Plain aegis serve opens nothing and
prints the URL instead, for systemd and remote hosts.
aegis serve --port 8742 --host 127.0.0.1 are the defaults. The token is kept in
.aegis/state/token and reused across restarts; delete the file to rotate it.
Anything but loopback must be asked for with --host.
aegis serve -d (--detach) starts the server in the background, in its own
session, so it outlives the terminal or the SSH connection without tmux or screen.
It returns once the port listens and prints the URLs, the pid and how to stop it;
the output goes to .aegis/state/serve.log and the pid to .aegis/state/serve.pid.
A server that dies while booting is reported with the end of its log, and the
command exits 1. With --window the window opens once it listens. For a host that
must survive reboots, run plain aegis serve under systemd instead.
Behind a reverse proxy, name the public origin: aegis serve --origin https://dev.example (repeatable) accepts sockets whose Host is dev.example and
whose Origin is exactly that origin, and prints the public URL with the token.
Keep --host on loopback and let the proxy terminate TLS. Anyone with the token
drives agents that may run with full permission on that machine, so put a second
lock in the proxy (basic auth, or a login), and do not proxy /mcp: agents reach
it on loopback.
Configuration
aegis reads two maps from .aegis.yaml at the root:
default_agent: opus
agents:
opus: {model: opus, effort: high, permission: full}
haiku: {model: claude-haiku-4-5-20251001, effort: low, permission: read}
queues:
general: {agent: opus, max_parallel: 5}
permission is read (plan mode), write (accept edits), auto or full
(bypass permissions). Only Claude Code profiles run today.
What you get
- Sessions in tabs. The tab bar is the server's open sessions, the same in every browser; each browser orders them by drag. Fleet is the home view: a card per session and the archive below it.
- Lazy resume. A restart brings sessions back stopped; the next prompt resumes
each with
claude --resume. Stop ends a process and keeps the tab; Close archives the session for every browser; Reopen brings it back. - A transcript that reads well. Tool rows with one-line verdicts, failures open, diffs for edits, rendered Markdown, a prompt sent mid-turn shown pending until Claude reads it, Esc to interrupt. Three themes: Ink, Logbook, Syalia.
- Files from agents. An agent hands you a file with
file_send; it shows in the transcript as a card with a preview (images, PDF, HTML, Markdown, text, audio, video), Open and Download. A browser on the server's own desktop also gets Open natively, which runsxdg-open(openon macOS, orAEGIS_OPENER). aegis keeps a copy and serves it at an unguessable/files/link. - Gauges. The Fleet view carries session counts, CPU, RAM and disk, and your Claude and OpenCode Go quota windows with the share already spent and where the window is heading; the session sidebar shows Claude's two windows.
- Which aegis. The top bar and the sidebar show the running version (the commit, for a build from git) and the latest release on PyPI.
- Tools for agents at
/mcp, namedmcp__aegis__<verb>:monitor_start,monitor_cancel,monitor_list,queue_enqueue,task_status,task_cancel,task_resume,peer_handoff,peer_read,session_list,session_rename,file_send,quota_read,meta. Each session'sclaudeconnects with its own token, so no tool asks who is calling.
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 the last release of it.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for aegis-harness 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aegis_harness-2.1.0.tar.gz | 428.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aegis_harness-2.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 796.8 kB
Release files / aegis_harness-2.1.0.tar.gz
| Download URL | aegis_harness-2.1.0.tar.gz |
|---|---|
| Size | 428.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31dcb5572127ff3ef5a7896b995b77ef3442a26fa3262a8b6da0857e76472952
|
|
BLAKE2b-256 checksum How to use checksums |
7a7ce1c27bd3404b17197a48384698f8ef974680a13820d8a3b4ade750f5462f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aegis_harness-2.1.0-py3-none-any.whl
| Download URL | aegis_harness-2.1.0-py3-none-any.whl |
|---|---|
| Size | 368.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9bb5c16f92e94251c39f0979b4e7a61e5e87ed4edb3a8e318e0ee1a9f5e0e80e
|
|
BLAKE2b-256 checksum How to use checksums |
d488777daf4aa380ac1e7f860048473ff687c3ecab409a813743a247670ec6c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
