wei9072/aegis

English · 繁體中文
> Aegis describes facts. The agent decides what to do.
A judgment-free observation layer for LLM-driven coding workflows.
> **If you are an AI coding agent** (Claude Code, Cursor, Aider, etc.)
> helping a user install Aegis, read AGENTS.md — it
> has the imperative install commands you should run.
📊 **Experiments archive** — nine rounds of
paired A/B agent comparisons (Anthropic / OpenAI / Google) drove
the rule library to its current state. Charts, run logs, and
direct lineage from finding → PR.
---
What it is (V2)
Aegis is an MCP server that emits **findings** about a proposed file
write. It does not block, warn, allow, or otherwise pass judgment.
Each finding is a fact — "this regex matched here", "this signal
went up by 1", "this file imports another file that imports it back"
— with enough structured context for the consuming agent (the LLM)
to decide what to do.
**Aegis does not write code, does not gate writes, and does not
score outcomes.** It only describes what changed.
The previous V1 architecture (Ring 0/0.5/0.7/R2 with BLOCK/WARN/PASS
verdicts, multi-turn pipeline, cost-aware regression rollback,
stalemate/thrashing detectors) is gone in V2. Judgment lives where
it belongs: in the consuming agent's reasoning step.
---
Why it exists
LLM systems still fail in three ways the surrounding tooling does
not catch:
1. Multi-turn refactors accumulate regressions silently
2. LLM-described actions diverge from actual tool calls
3. Structural rules erode without anyone noticing
Aegis exists to make these failures **visible**. Whether they're
acceptable in this context is a question for the agent or the
human; Aegis only ensures the data is on the table.
---
What Aegis is NOT
Aegis is a narrow tool. Don't install it expecting:
- **A linter or replacement for ruff / eslint / clippy.** It only
fires on the patterns explicitly encoded in
crates/aegis-core/src/{security.rs,signals/}. Plain "bad code"
without those patterns is invisible to it.
- **A SAST suite.** The 10 SEC rules cover well-known anti-patterns
(eval, hardcoded secrets, weak RNG, TLS-off, CORS misconfig,
etc.) but are nowhere near Bandit / Semgrep coverage. Treat them
as a spot check, not a full audit.
- **A safety net for capable models on greenfield work.** If the
consuming agent is GPT-5-class or Sonnet-class writing a fresh
project from scratch, it usually picks safe defaults on its own
and Aegis findings will be empty most of the time. The marginal
value is highest with **mid-tier models on brownfield work** —
where the existing codebase has constraints (cycle graphs, public
API, removed callers) the agent will otherwise drift past.
- **An auto-fixer.** Aegis describes; the agent decides. Findings
carry a severity_hint string but no enforcement. Nothing
retries, nothing rewrites, nothing reverts.
If you want a verdict-issuing gate, install a linter / SAST /
pre-commit hook. Aegis is the layer underneath that — facts only,
no judgment.
---
How it works
Two infrastructure layers feed a single MCP tool.
**Layer 1 — parse**: One tree-sitter call per file, shared across
every finding generator. No more per-signal Parser::new(). Always
returns a tree, even on broken syntax.
**Layer 2 — WorkspaceIndex**: Reverse index over per-file imports
and public symbols, mtime-cached so repeated MCP calls only re-parse
what actually changed.
**Findings**: Four kinds — Syntax, Signal, Security, Workspace —