Skip to content

Commit f32f349

Browse files
OneStepAt4timeOneStepAt4time
authored
docs: "Why Aegis" developer blog post (DevRel) (#3324)
Closes #3323. Developer-facing blog post explaining Aegis positioning, competitive landscape, technical architecture, and getting started.
1 parent 7eb9baa commit f32f349

1 file changed

Lines changed: 231 additions & 0 deletions

File tree

‎docs/blog/why-aegis-2026-05.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# Why Aegis: The Open-Source Middleware for AI Coding Agents
2+
3+
*Choosing a Claude Code orchestration tool? Here's why we built Aegis, what the alternatives get right (and wrong), and when middleware beats monoliths.*
4+
5+
---
6+
7+
You're a developer. You've discovered Claude Code and your productivity just doubled. You start a session, describe what you want, and the AI writes, debugs, and refactors code alongside you.
8+
9+
Then you hit scale. You want to run sessions from CI. You want your team to trigger tasks from Slack. You want to know *what the AI did last Tuesday at 3pm* without digging through terminal history.
10+
11+
That's when you start looking for orchestration. And that's when the landscape gets confusing.
12+
13+
## The Problem: CLI-Only Doesn't Scale
14+
15+
Claude Code is a CLI tool. It's fantastic for interactive use — one developer, one terminal, one task at a time. But the moment you need any of these, you're on your own:
16+
17+
- **Programmatic access** — create sessions from scripts, CI pipelines, or chat bots
18+
- **Multi-session management** — run 5 sessions in parallel, see which ones are idle, kill the stuck one
19+
- **Audit** — who approved that production database migration the AI suggested?
20+
- **Access control** — not everyone on the team should have admin access
21+
- **Observability** — metrics on token usage, cost, session duration, tool call frequency
22+
- **Integration** — webhooks, event streams, REST API endpoints your existing tools can call
23+
24+
You can cobble together shell scripts. You can run tmux in the background and pray. You can build a thin wrapper and call it a day. But you'll end up rebuilding the same things every team eventually needs.
25+
26+
That's the gap Aegis fills. Not another AI agent — **middleware** that makes your existing agent production-ready.
27+
28+
## The Landscape: What's Out There
29+
30+
The Claude Code orchestration space is crowded. Here are the options you're probably evaluating, what they get right, and where they fall short.
31+
32+
### cc-connect — Feature-Heavy, Enterprise-Light
33+
34+
**What it is:** Go binary with TOML config. 10+ agent backends, 11 chat platforms (including WeChat, QQ, DingTalk for the Asian market), natural language scheduling.
35+
36+
**What it gets right:**
37+
- Chat platform breadth — 11 platforms is impressive
38+
- Multi-agent support out of the box
39+
- Natural language cron ("every Monday at 9am, run the tests")
40+
- Simple binary download, zero Node.js dependency
41+
42+
**Where it falls short:**
43+
- **No REST API** — TOML config only. You can't create a session from a curl command. No CI/CD integration path.
44+
- **No audit trail** — no tamper-proof logging, no compliance story
45+
- **No enterprise auth** — token-only. No OIDC, no RBAC, no SSO
46+
- **No observability** — no Prometheus metrics, no OpenTelemetry tracing, no structured logging
47+
- **Not container-native** — Go binary, not Docker/Kubernetes ready
48+
49+
cc-connect is the right choice if you want to send messages to Claude Code from WeChat and don't need anything beyond that. But if you're building infrastructure, the lack of an API is a dealbreaker.
50+
51+
### OpenACP — ACP-Native but Thin
52+
53+
**What it is:** `curl | bash` install. 28+ agent backends (Claude Code, Codex, Gemini, and more). Telegram, Discord, Slack integration.
54+
55+
**What it gets right:**
56+
- Simplest install in the space — one command
57+
- Broadest agent support — 28+ backends
58+
- Budget limits per session
59+
- Skill system (brainstorming, TDD, debugging presets)
60+
61+
**Where it falls short:**
62+
- **No web dashboard** — CLI and Telegram only
63+
- **No enterprise auth** — no OIDC, no RBAC
64+
- **No audit trail** — no persistent logging
65+
- **No API** — no REST endpoints for external consumers
66+
- **Not deployable as infrastructure** — no Docker, no K8s
67+
68+
OpenACP is the most architecturally similar tool to Aegis. But it's missing the entire enterprise stack. If you need a dashboard, audit, or RBAC, you'll outgrow it fast.
69+
70+
### Verdent AI — Beautiful UX, Closed Ecosystem
71+
72+
**What it is:** Mac desktop app (Apple Silicon). Parallel agents, project memory, task decomposition. Italian-founded.
73+
74+
**What it gets right:**
75+
- **Parallel agents** — multiple agents working simultaneously on the same codebase. This is the #1 feature every competitor lists.
76+
- **Project memory** — remembers your preferences, learns over time. The AI gets better the more you use it.
77+
- **Task decomposition** — break features into subtasks automatically, prioritize, execute.
78+
- **ICSE 2026 Distinguished Paper** — academic credibility from their SEAlign behavioral alignment research.
79+
- **BYOK + Eco Mode** — bring your own API key, cost control mode.
80+
81+
**Where it falls short:**
82+
- **Mac only** — no Linux, no Windows, no Docker, no servers
83+
- **Closed source** — you can't audit the code, self-host, or extend it
84+
- **No API** — desktop app only. No CI/CD integration possible.
85+
- **No multi-user** — single-user app, no team collaboration
86+
- **No compliance** — no audit trail, no access control, no enterprise anything
87+
88+
Verdent AI is the best consumer AI coding tool we've seen. If you're a solo developer on a Mac who wants an AI pair programmer that remembers your style, it's genuinely excellent. But it's a consumer tool, not infrastructure.
89+
90+
## The Aegis Thesis: Middleware, Not Agent
91+
92+
Here's the core insight: **Aegis is not an AI agent.** It's the middleware that makes AI agents production-safe.
93+
94+
The other tools try to be everything — agent, orchestrator, UI, chat bot. Aegis does one thing: **sit between you and Claude Code and make it enterprise-ready.**
95+
96+
```
97+
Your tools → Aegis API → Claude Code
98+
(CI/CD, Slack, (REST + MCP) (ACP JSON-RPC
99+
dashboard, etc.) 108 endpoints over stdio)
100+
```
101+
102+
### What This Means in Practice
103+
104+
**Bring your own LLM.** Aegis doesn't pick models. It doesn't route between them. It orchestrates whatever agent you're running. Today that's Claude Code via ACP. Tomorrow it could be Codex or Gemini via the same runner abstraction. The API stays the same.
105+
106+
**MIT license.** Self-host on your infrastructure. Audit the code. Extend it with Fastify plugins. No vendor lock-in, no proprietary protocols, no "contact sales for enterprise features."
107+
108+
**Enterprise security from day one.** Not a premium add-on. Every endpoint has RBAC guards. OIDC/SSO for enterprise identity. Hash-chained audit trail. Sigstore release signing. Kubernetes + Helm deployment. These aren't checkboxes — they're architectural decisions that can't be bolted on later.
109+
110+
## Technical Depth: What's Under the Hood
111+
112+
### ACP — The Agent Control Protocol
113+
114+
Claude Code speaks JSON-RPC over stdio. Aegis wraps this in the Agent Control Protocol (ACP):
115+
116+
```
117+
Your curl command
118+
↓
119+
Aegis REST API (POST /v1/sessions/:id/send)
120+
↓
121+
ACP JSON-RPC client (stdio ↔ child process)
122+
↓
123+
Claude Code (running in a child process)
124+
↓
125+
Hooks → Permission evaluation → SSE broadcast → Audit log
126+
```
127+
128+
Every action goes through the same pipeline. Create a session, send a prompt, approve a permission — all routed through ACP, all logged, all observable.
129+
130+
### 35 MCP Tools
131+
132+
Connect Claude Code (or any MCP host) to Aegis and you get 35 tools:
133+
134+
- **Session lifecycle** — `create_session`, `send_message`, `kill_session`, `get_status`, `get_transcript`
135+
- **ACP control** — `acp_submit_prompt`, `acp_approve`, `acp_reject`, `acp_interrupt`, `acp_escape`
136+
- **Monitoring** — `server_health`, `get_session_metrics`, `get_session_summary`, `get_session_latency`, `capture_terminal`
137+
- **State** — `state_set`, `state_get`, `state_delete` (cross-session Memory Bridge)
138+
- **Pipelines** — `batch_create_sessions`, `create_pipeline`, `list_pipelines`
139+
- **Management** — `health`, `list_tools`, `swarm`
140+
141+
```bash
142+
# One command to connect
143+
claude mcp add aegis -- ag mcp
144+
```
145+
146+
### Session Lifecycle
147+
148+
Sessions go through well-defined states:
149+
150+
| State | What's happening |
151+
|-------|-----------------|
152+
| `pending` | Connecting to ACP runtime |
153+
| `working` | Agent is actively processing |
154+
| `idle` | Waiting for input |
155+
| `permission_prompt` | Agent needs approval for a tool call |
156+
| `compacting` | Context compression in progress |
157+
| `killed` | Stopped via API (terminal) |
158+
| `completed` | Finished normally (terminal) |
159+
| `crashed` | Terminated unexpectedly (terminal) |
160+
161+
Terminal states (`killed`, `completed`, `crashed`) retain sessions for audit — you can always go back and read the transcript.
162+
163+
### Audit Trail
164+
165+
Every session action is recorded in a hash-chained, immutable audit log:
166+
167+
```bash
168+
curl http://localhost:9100/v1/audit \
169+
-H "Authorization: Bearer $TOKEN"
170+
```
171+
172+
Each entry chains to the previous one via SHA-256. Entries cannot be modified or deleted. Export as CSV or NDJSON for compliance reporting.
173+
174+
### Real-Time Dashboard
175+
176+
React-based web dashboard at `http://localhost:9100/dashboard/`:
177+
178+
- Session list with live status updates via SSE
179+
- Real-time cost analytics with per-session breakdown
180+
- Agent contribution tracking
181+
- Permission approval queue
182+
- Audit log browser
183+
184+
No setup required — it's there when you start the server.
185+
186+
## Getting Started
187+
188+
Two commands. No really:
189+
190+
```bash
191+
# Run Aegis with a task
192+
npx --package=@onestepat4time/aegis ag run "Analyze this project and list the main technologies." --cwd /path/to/your/project
193+
```
194+
195+
That's it. `ag run` bootstraps the config, starts the server, creates a session, and streams output to your terminal.
196+
197+
For more advanced setups — authentication, multiple sessions, MCP integration — see the [Getting Started Guide](../getting-started.md).
198+
199+
## When to Choose Aegis
200+
201+
**Choose Aegis if:**
202+
- You need a **REST API** to integrate AI coding into CI/CD, dashboards, or custom tooling
203+
- You need **audit trails** for compliance (SOC2, GDPR, internal governance)
204+
- You need **RBAC/OIDC** for team access control
205+
- You want to **self-host** on your own infrastructure
206+
- You need **observability** (Prometheus, OpenTelemetry, Grafana)
207+
- You're building **infrastructure**, not just running interactive sessions
208+
209+
**Consider alternatives if:**
210+
- You only need to send messages from Telegram/WeChat → cc-connect
211+
- You want the simplest possible install for 28+ agent backends → OpenACP
212+
- You're a solo Mac developer who wants an AI pair programmer → Verdent AI
213+
214+
We're not trying to be everything. We're trying to be the **production-grade middleware** that makes AI coding agents safe for teams and enterprises.
215+
216+
## The Road Ahead
217+
218+
Aegis is open source (MIT), actively developed, and shipping features weekly. Current focus areas:
219+
220+
- **Multi-agent support** — adding Codex and Gemini as runner backends via ACP
221+
- **Install simplification** — reducing setup to a single command
222+
- **Telegram integration** — proper bidirectional chat (approve/reject from mobile)
223+
- **Enterprise hardening** — rate limiting, budget controls, session isolation
224+
225+
Star us on [GitHub](https://github.com/OneStepAt4time/aegis). Read the [docs](https://github.com/OneStepAt4time/aegis/tree/develop/docs). Join the [community](https://discord.com/invite/clawd).
226+
227+
**One step at a time.** ⭐
228+
229+
---
230+
231+
*This post is part of the [Aegis Blog](./). For the full competitive analysis, see the [Competitive Threat Matrix](../competitive-threat-matrix.md) and [Competitive Differentiators](../competitive-differentiators.md).*

0 commit comments

Comments
 (0)