# Aegis

[English](README.md) · [繁體中文](README.zh-TW.md)

> 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`](AGENTS.md) — it
> has the imperative install commands you should run.

📊 **[Experiments archive](experiments/README.md)** — 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.

```
┌─────────────────────────────────────┐
│ MCP Tool: validate_file             │
│   (path, new_content,               │
│    old_content?, workspace_root?)   │
└──────────────┬──────────────────────┘
               │ findings[]
               ▼
┌─────────────────────────────────────┐
│ Findings Generators                 │
│   Syntax · Signal · Security        │
│   Workspace                         │
└──────────────┬──────────────────────┘
               │
       ┌───────┴────────┐
       ▼                ▼
┌─────────────┐  ┌─────────────────┐
│ Layer 1     │  │ Layer 2         │
│ parse(file) │  │ WorkspaceIndex  │
│  → Tree     │  │ (mtime-cached)  │
└─────────────┘  └─────────────────┘
```

**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 —
described below. Every finding carries `file`, optional `range` and
`snippet`, and a structured `context` map. None carries severity.

---

## Finding kinds

| `kind` | What it means | Example `rule_id`s |
| :--- | :--- | :--- |
| **Syntax** | Tree-sitter found ERROR / MISSING nodes. | `ring0_violation` |
| **Signal** | A structural counter (14 of them). When `old_content` is supplied, `context` carries `value_before` / `value_after` / `delta`. | `fan_out`, `max_chain_depth`, `cyclomatic_complexity`, `nesting_depth`, `empty_handler_count`, `unfinished_marker_count`, `unreachable_stmt_count`, `mutable_default_arg_count`, `shadowed_local_count`, `suspicious_literal_count`, `unresolved_local_import_count`, `member_access_count`, `type_leakage_count`, `cross_module_chain_count`, `import_usage_count`, `test_count_lost` |
| **Security** | A specific anti-pattern matched (16 rules). `context.severity_hint` is a hint, not a verdict. | `SEC001`–`SEC016` (eval/exec, hardcoded secret, TLS-off, shell injection, SQL concat, CORS wildcard+credentials, JWT unsafe, insecure deserialization, weak crypto, weak RNG, hardcoded Bearer token, timing-unsafe credential compare, Python bare `except:`, hardcoded PEM private key, silent broad except, SSRF on user-input URL) |
| **Workspace** | Cross-file finding. Only emitted when `workspace_root` is supplied. | `cycle_introduced`, `public_symbol_removed`, `file_role` |

`aegis-allow: <rule_id>` (or `aegis-allow: all`) on the same or
previous source line marks `user_acknowledged: true` on the
matching finding instead of dropping it. The agent sees the
acknowledgement and can choose to honour it.

---

## Quickstart

V2 ships a single binary: `aegis-mcp` (the MCP server).

### Install

```bash
# Prerequisites: git + a Rust toolchain (1.74+).
git clone https://github.com/wei9072/aegis && cd aegis
cargo install --path crates/aegis-mcp
```

### Configure your MCP client

Point your MCP-aware client (Claude Code / Cursor / your own agent)
at the `aegis-mcp` binary over stdio. The exact configuration syntax
varies by client; the server itself takes no flags.

### The one tool: `validate_file`

```jsonc
{
  "name": "validate_file",
  "arguments": {
    "path": "src/auth.py",
    "new_content": "...",                  // required
    "old_content": "...",                  // optional — enables deltas
    "workspace_root": "/path/to/project"   // optional — adds Workspace findings
  }
}
```

Returns:

```json
{
  "schema_version": "v2.0",
  "findings": [
    {
      "kind": "security",
      "rule_id": "SEC009",
      "file": "src/auth.py",
      "range": { "start_line": 47, "start_col": 4, "end_line": 47, "end_col": 52 },
      "context": { "severity_hint": "block", "message": "weak hash …" },
      "user_acknowledged": false
    },
    {
      "kind": "signal",
      "rule_id": "unfinished_marker_count",
      "file": "src/auth.py",
      "context": { "value_before": 0, "value_after": 1, "delta": 1 },
      "user_acknowledged": false
    },
    {
      "kind": "workspace",
      "rule_id": "cycle_introduced",
      "file": "src/auth.py",
      "context": { "cycle": ["src/auth.py", "src/user.py", "src/auth.py"] },
      "user_acknowledged": false
    }
  ]
}
```

The first call with a `workspace_root` builds the workspace index
(parses every supported file once); subsequent calls reuse the cache
and only re-parse files whose mtime changed. No separate "scan"
step.

---

## Supported source languages

Run-time dispatch by file extension. Adding a language is a Cargo
dep + an adapter file under `crates/aegis-core/src/ast/languages/` +
a `.scm` import query — no other changes needed.

| Language | Layer 1 parse | Notes |
| :--- | :---: | :--- |
| Python | ✅ | `.py`, `.pyi` |
| TypeScript | ✅ | `.ts`, `.tsx`, `.mts`, `.cts` |
| JavaScript | ✅ | `.js`, `.mjs`, `.cjs`, `.jsx` |
| Go | ✅ | `.go` |
| Java | ✅ | `.java` |
| C# | ✅ | `.cs` |
| PHP | ✅ | `.php`, `.phtml`, `.php5`, `.php7`, `.phps` |
| Swift | ✅ | `.swift` |
| Kotlin | ✅ | `.kt`, `.kts` |
| Dart | ✅ | `.dart` |
| Rust | ✅ | `.rs` |

---

## Design principles

- **Describe facts, do not pass judgment.** Findings have no
  severity field. The consuming agent decides which findings
  matter and how to react.
- **Parse once, share the tree.** Every finding generator consumes
  a `ParsedFile`. No per-signal `Parser::new()`. No temp-file
  round-trip.
- **Workspace bootstrap is implicit.** First call with a
  `workspace_root` builds the index; subsequent calls hit the
  mtime cache. No separate scan tool, no manual init step.
- **No automatic learning, no objective optimization.** Aegis does
  not track success/failure across calls, does not adapt rules,
  does not score outcomes. State only carries the workspace cache.
- **One MCP tool, narrow surface.** `validate_file` and that's it.
  No `retry`, no `hint`, no `explain`. Agent reasoning is the
  agent's job.

---

## Status

| Layer | State |
| :--- | :--- |
| Layer 1 (parse + 11 language adapters) | ✅ |
| Layer 2 (WorkspaceIndex + mtime cache) | ✅ |
| Findings: Syntax + Signal + Security + Workspace | ✅ |
| MCP server (`aegis-mcp`) | ✅ |
| V1 binaries (`aegis`, `aegis pipeline run`, `aegis check`, `aegis attest`, `aegis scan`) | ❌ removed in V2 |

---

## License

MIT — see [`LICENSE`](LICENSE).

V2 — MCP-only architecture. Pipeline / runtime / providers / IR /
decision crates removed; judgment lives in the consuming agent.