Aegis is an MCP server that provides factual observations about proposed file writes in LLM-driven coding workflows. Its core philosophy is "describe the facts, let the agent decide what to do." Aegis does not block, warn, allow, or make any judgment; every finding is a fact, such as "this regex matches here," "this signal was incremented by 1," "this file imports another file, which in turn imports it back," accompanied by enough structured context for the consuming agent (LLM) to decide on its own how to handle it.
Purpose Aegis is designed to make visible three classes of failures that LLM systems are prone to during coding: multi-turn refactoring silently accumulating regressions; the operations described by the LLM diverging from the actual tool calls; and structural rules being eroded without anyone noticing. Aegis only ensures that this data is put on the table; whether these failures are acceptable in the current context is for the agent or human to judge.
Main capabilities Aegis supports one MCP tool through two infrastructure layers. The first layer is the parsing layer: tree-sitter is called once per file and shared across all finding generators, always returning a syntax tree even if the syntax is broken. The second layer is the WorkspaceIndex: it builds a reverse index of each file's imports and public symbols, with an mtime cache, so repeated MCP calls only re-parse files that have actually changed.
Findings fall into four categories: Syntax, Signal, Security, and Workspace. Each finding carries a file, an optional range and snippet, and a structured context map. No finding carries a severity field.
Users can use aegis-allow: <rule_id> (or aegis-allow: all) on the same line or the previous line of source code to mark user_acknowledged: true; matching findings are not discarded, but instead let the agent see that acknowledgment and decide for itself whether to respect it.
Usage V2 releases only one binary: aegis-mcp (the MCP server). Point an MCP-capable client (such as Claude Code, Cursor, or your own agent) at the aegis-mcp binary via stdio. The specific configuration syntax varies by client; the server itself accepts no flags.
The only tool is validate_file. On the first call, passing workspace_root builds the workspace index (parsing each supported file once); subsequent calls reuse the cache and only re-parse files whose mtime has changed. There is no separate "scan" step.
Supported languages are dispatched at runtime by file extension. Adding a language requires a Cargo dependency, an adapter file under crates/aegis-core/src/ast/languages/, and a .scm import query, with no other changes needed.
When to use it Aegis's marginal value is highest when medium-capability models work on brownfield (existing codebase) work, because existing codebases have constraints (cyclic graphs, public APIs, removed callers) that agents might otherwise deviate from. For GPT-5-level or Sonnet-level models writing brand-new projects from scratch, they usually choose safe defaults automatically, and Aegis's findings are empty most of the time.
Limitations Aegis is a narrowly scoped tool. It is not a linter, nor a replacement for ruff, eslint, or clippy; it only triggers on patterns explicitly encoded in crates/aegis-core/src/{security.rs,signals/}, and ordinary "bad code" without these patterns is invisible to it. It is also not a SAST suite; the 10 SEC rules cover well-known anti-patterns (eval, hardcoded secrets, weak randomness, disabled TLS, CORS misconfiguration, etc.), but fall far short of Bandit's or Semgrep's coverage, and should be treated as spot checks rather than a complete audit. It is also not an auto-fixer: Aegis only describes, the agent decides; findings carry a severity_hint string but there is no enforcement, no retry, rewrite, or rollback. If you want a gate that issues a release verdict, you should install a linter, SAST, or pre-commit hook; Aegis is the layer beneath them—only facts, no judgment.
Design principles Describe facts, make no judgments: findings have no severity field, and it is up to the consuming agent to decide which findings matter and how to react. Parse once, share the syntax tree: each finding generator consumes one ParsedFile, no Parser::new() created per signal, no temporary file round-trips. Workspace bootstrapping is implicit: the first call passes workspace_root to build the index, and subsequent calls hit the mtime cache, with no separate scan tool or manual initialization step. No automatic learning, no objective optimization: Aegis does not track success/failure across calls, does not adjust rules, does not score results, and its state only carries the workspace cache. One MCP tool, narrow interface: only validate_file, no retry, hint, or explain; agent reasoning is the agent's own business.
Aegis is licensed under MIT. V2 is an MCP-only architecture; crates such as pipeline, runtime, provider, IR, and decision have been removed, and the judgment logic resides in the consuming agent.
