Skip to main content
Glama
deenesjakoruzh
wei9072

aegis

by wei9072
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Aegis

English · 繁體中文

Aegis ensures bad decisions don't stick.

A system for preventing silent regressions in LLM-driven workflows.

If you are an AI coding agent (Claude Code, Cursor, Aider, etc.) helping a user install or integrate Aegis, read AGENTS.md instead — it has imperative install commands, integration templates you can paste, and the framing rules you must respect. The rest of this README is for the human evaluating whether to adopt Aegis.

What it is

Aegis is a constraint-based behavior harness for LLM systems. (In the broad sense: a verification environment, not an agent driver.)

For the domain-independent framework definition, see docs/framework.md. aegis-agent is one implementation case: Aegis applied to agent-driven code changes.

Aegis does not write code, and does not tell the LLM how to write code. It only judges whether the code an LLM produces is allowed to stay. The LLM (or whichever code generator you wrap) keeps full agency over what to write; Aegis exercises agency only over what passes its gates.

It enforces a local closed loop: each proposed state transition is validated, and regressions are rejected.

Instead of optimizing model behavior, Aegis enforces explicit, verifiable constraints, ensuring that invalid or regressive states do not persist.

Related MCP server: agent-context-graph

Why it exists

LLM systems fail in three ways that current 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 and rejectable.

Core mechanism

Aegis controls state transitions:

Sₙ → Sₙ₊₁ is allowed only if all constraints are satisfied
and no regression is detected.

Otherwise, the system rolls back to Sₙ.

Cost-aware rollback is the only cross-iteration consistent criterion. Other checks (validation, structural constraints) act as local guards, not global direction signals.

What actually gets checked (V1.10, six layers)

Layer

Checks

Where it runs

Ring 0 — syntax

tree-sitter parse; ERROR / MISSING node → BLOCK

aegis check, MCP, pipeline

Ring 0.5 — structural signals

fan_out (unique imports), max_chain_depth (longest method chain) — numeric only

aegis check, MCP, pipeline

Cost regression

sum(signals_after) > sum(signals_before) → BLOCK / ROLLBACK

MCP (when old_content given), pipeline (every iter)

PlanValidator

path safety / scope / dangerous_path / virtual-FS simulation

aegis pipeline run only

Executor + Snapshot

atomic apply with backup-dir rollback

aegis pipeline run only

Stalemate / Thrashing detector

sequence-level; halts the loop with a named reason

aegis pipeline run only

aegis check and the MCP server expose the first three layers (single-file judgement); the multi-turn pipeline adds the last three (cross-iteration loop control).

Design principles

  • Do not write code; only judge code that is written

  • Do not tell the model what to write; only what cannot stay

  • Only reject what is verifiably bad

  • No automatic learning

  • No objective optimization

The first two are the load-bearing ones. They are why Aegis can wrap any code-generating agent (Cursor, Claude Code, Aider, your own pipeline) without becoming a competing one — Aegis exercises judge agency; the wrapped agent keeps author agency.

Guarantees

  • Regressions are detected and rolled back when constraints are defined

  • Invalid states are blocked at the validation layer

  • All decisions are recorded in a machine-readable trace

Non-goals

Aegis is not:

  • An AI agent

  • An optimizer

  • A self-improving system

These are deliberate design choices, not future work. Aegis will not evolve into any of these. See docs/post_launch_discipline.md for the explicit deferral list.

Scope

Aegis enforces correctness within a single execution loop, but does not adapt behavior across executions.

The loop is local, not global.

Quickstart

As of V1.10, Aegis is a single Rust workspace producing two binaries — aegis (CLI) and aegis-mcp (MCP stdio server). Zero Python at runtime.

Install

# Prerequisites: git + a Rust toolchain.
# If you don't have Rust:
#   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
#   source "$HOME/.cargo/env"

git clone https://github.com/wei9072/aegis && cd aegis
cargo build --release --workspace

Install system-wide so aegis / aegis-mcp end up on $PATH:

cargo install --path crates/aegis-cli
cargo install --path crates/aegis-mcp     # optional — MCP server

Cross-platform release artifacts (Linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64) ship via GitHub Releases — see V2.0 in docs/v1_rust_port_plan.md.

Static analysis (no LLM, no API key)

aegis check runs Ring 0 (syntax) + Ring 0.5 (structural signals — fan-out, max chain depth) on any supported source file:

aegis languages                       # list supported languages
aegis check path/to/file.py           # human-readable signals
aegis check path/to/file.py --json    # machine-readable

The intent: drop this into a pre-commit hook or CI gate so bad diffs never make it past the boundary you care about. See docs/integrations/ for paste-ready examples.

LLM-backed multi-turn pipeline

aegis pipeline run drives the Planner → Validator → Executor loop against your workspace. Provider config comes from environment variables — supports any OpenAI-compatible endpoint (OpenAI, OpenRouter, Groq):

export AEGIS_PROVIDER=openai          # or: openrouter | groq
export AEGIS_MODEL=gpt-4o-mini        # any model the provider exposes
export OPENAI_API_KEY=sk-...          # or AEGIS_API_KEY (provider-agnostic)

aegis pipeline run \
  --task "rename the foo helper to bar everywhere" \
  --root . \
  --max-iters 3

Every iteration prints a one-line summary (iter 0 [abc12345] plan=continuing patches=2 applied=true rolled_back=false); add --json for a machine-readable summary at the end. The loop stops when the planner declares done, signals stalemate, signals thrashing, or hits --max-iters. Cost-aware regression rollback fires automatically if structural signals get worse mid-loop.

MCP server (Cursor / Claude Code / your own agent)

aegis-mcp     # stdio JSON-RPC, MCP protocol 2025-06-18

Configure your MCP client per docs/integrations/mcp_design.md; the agent then calls validate_change(path, new_content, old_content?) mid-loop and gets a {decision, reasons, signals_after, …} verdict back. Pure observation — never coaches the agent (see Design principles).

aegis chat — interactive coding agent (V3)

Built on the same primitives, aegis chat is a substrate-mode agent: pick any of three providers via env vars, drop into a REPL with line editing + slash commands + markdown rendering. Three modes auto-detected:

aegis chat "explain this concept"        # one-shot
echo "task" | aegis chat                 # pipe → one-shot
aegis chat                               # tty → interactive REPL

Provider env vars (first match wins):

# OpenAI-compat (covers OpenRouter / Groq / Ollama / vLLM / etc.)
export AEGIS_OPENAI_BASE_URL=https://openrouter.ai/api/v1
export AEGIS_OPENAI_API_KEY=sk-or-v1-...
export AEGIS_OPENAI_MODEL=meta-llama/llama-3.3-70b-instruct

# Anthropic
export AEGIS_ANTHROPIC_API_KEY=sk-ant-...
export AEGIS_ANTHROPIC_MODEL=claude-haiku-4-5

# Gemini
export AEGIS_GEMINI_API_KEY=AIza...
export AEGIS_GEMINI_MODEL=gemini-2.5-flash

Common flags:

aegis chat --tools --workspace .                # add Read/Glob/Grep tools
aegis chat --tools --mcp aegis-mcp              # mount aegis-mcp as a tool
aegis chat --verify                             # auto-detect test runner
aegis chat --cost-budget 5.0                    # terminate on cumulative regression
aegis chat --permission-mode read-only          # safest sandbox

The four V3 differentiation points (PreToolUse aegis-predict, cross-turn cost tracking, verifier-driven done, stalemate detection) are wired in; full usage walkthrough in docs/v3_dogfood.md, design rationale in docs/v3_agent_design.md.

Integrations

You're already using Cursor / Claude Code / Aider / Copilot / your own agent. Aegis is meant to be a side-channel enforcement layer that doesn't ask you to switch tools.

Boundary

Path

Status

Commit

Git pre-commit hook

✓ ready (5-line bash)

PR / merge

GitHub Action / CI gate

✓ ready (10-line YAML)

Agent decision

MCP server

✅ validate_change ready (cargo install --path crates/aegis-mcp && aegis-mcp)

Pick whichever boundary fits your workflow; you can stack them. Index + per-path detail: docs/integrations/.

Status

Layer

State

Notes

Execution Engine

✅

Pipeline + Executor + cost-aware regression rollback. Native Rust loop in aegis-runtime::native_pipeline.

Static analysis

✅

Ring 0 (syntax) + Ring 0.5 (fan_out, max_chain_depth) shared by aegis check + aegis pipeline run + aegis-mcp validate_change.

Decision Trace

✅

DecisionTrace + 10-value DecisionPattern + 5-value TaskVerdict; Python-era cross-model evidence in docs/v1_validation.md. Rust re-validation is gated on LLM API budget (V1.8).

MCP server

✅

aegis-mcp — hand-rolled JSON-RPC 2.0 over stdio; one tool: validate_change per docs/integrations/mcp_design.md.

Cross-model sweep harness

🟡

aegis pipeline run works scenario-by-scenario; batch sweep (aegis sweep) is V1.8 backlog — gated on API budget.

Feedback Layer

❌

Out of scope by design — see Non-goals and Critical Principle. Structurally enforced by crates/aegis-decision/tests/contract.rs.

Supported source languages (Ring 0 + Ring 0.5 signals)

Tier 2 multi-language support landed in V1.4–V1.7 of the Rust port (see docs/v1_rust_port_plan.md). With V1.10's Python deletion, every language listed below now gets both enforcement (Ring 0 + Ring 0.5 via aegis check) and the refactor half (aegis pipeline run against an OpenAI-compatible LLM provider). Run aegis languages for the live registry.

Language

Ring 0 syntax

Ring 0.5 fan-out

Ring 0.5 chain-depth

Extensions

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

🟡 = the default chain-depth walker under-counts on this language's AST shape; per-language overrides are the planned fix path (LanguageAdapter::max_chain_depth).

Adding a language is one Cargo dep + one adapter file under crates/aegis-core/src/ast/languages/ + one .scm query — checklist in docs/multi_language_plan.md#per-language-work-checklist.

Philosophy

If Aegis starts learning automatically, it has violated its own design.

License

MIT — see LICENSE.

V1.10 — Rust workspace, zero Python at runtime. Cross-platform release artifacts (Homebrew, npm, GitHub Releases) are templated under packaging/; activation is the V2.0 milestone in docs/v1_rust_port_plan.md.

Available Tools

3 tools
attest_pathA

Post-write attestation. Reads on-disk content of path and runs absolute checks (Ring 0 syntax + Ring 0.7 security + optional Ring R2 cycle). Use from PostToolUse hooks / CI / after any write that bypasses the pre-write gate. Writes the verdict to <workspace_root>/.aegis/attestations.jsonl for audit when workspace_root is provided.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path of the file to attest.
workspace_rootNoOptional. Enables Ring R2 cycle detection and JSONL audit log.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses side effect: writes verdict to attestations.jsonl when workspace_root provided. Mentions reading on-disk content and running checks. Lacks details on error handling, permissions, or performance, but given no annotations, the description adequately discloses key behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first defines action, second gives usage and side effect. No fluff, front-loaded with purpose. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description covers purpose, usage, and a key behavioral trait (writing audit log). Does not specify return value format but provides enough context for the agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. Description adds value for workspace_root (explaining it enables Ring R2 detection and audit log) beyond schema. For path, description repeats absolute nature but is clear. Overall adds significant meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool performs post-write attestation, reading file content and running specific checks (Ring 0 syntax, Ring 0.7 security, optional Ring R2 cycle). Distinguishes from siblings by mentioning 'post-write' and 'pre-write gate', contrasting with validate_change tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: from PostToolUse hooks, CI, or after any write bypassing the pre-write gate. Does not explicitly list alternatives but implies distinction from pre-write validation. Provides context for optional workspace_root enabling Ring R2 detection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_changeA

Fast single-file gate. Run Aegis Ring 0 (syntax) + Ring 0.5 (structural signals + cost regression) + Ring 0.7 (security anti-patterns) on a proposed file write. Returns the decision without applying the change. Pure observation — never coaches the agent. Use this when the change is contained to one file or when speed matters more than cross-file safety.

ParametersJSON Schema
NameRequiredDescriptionDefault
new_contentYesFull file contents the agent intends to write.
old_contentNoOptional. If provided, enables cost-aware regression detection by comparing structural signal totals before vs after.
pathYesPath the agent intends to write (used as filename for syntax/structural analysis only — no side effects to disk).

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses it is a pure observation, no side effects, runs syntax, structural, cost, and security checks, returns decision without coaching. Lacks detail on output format but otherwise transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise (few sentences), front-loaded with purpose, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, parameters, and behavioral traits well. Minor gap: no output structure description, but given no output schema, it is mostly complete for a single-file validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters are described in the schema at 100% coverage; the description adds limited additional context (e.g., old_content enables cost regression), but baseline is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool validates a proposed file write using three rings, returns a decision without applying changes, and distinguishes itself from the sibling 'validate_change_with_workspace' by being single-file and speed-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'when the change is contained to one file or when speed matters more than cross-file safety', implicitly guiding against the workspace variant.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_change_with_workspaceA

Workspace-aware gate (Ring 0 + 0.5 + 0.7 + R2). Adds cross-file checks on top of validate_change: detects when a change introduces a module import cycle, or deletes a public symbol that other files in the workspace still reference. Slower than validate_change because it walks the workspace tree; prefer this when the change touches a public API or shared module.

ParametersJSON Schema
NameRequiredDescriptionDefault
new_contentYesFull file contents the agent intends to write.
old_contentNoOptional baseline for cost-aware regression.
pathYesAbsolute or workspace-relative path the agent intends to write.
workspace_rootYesAbsolute path to the project root. Used to build a one-shot workspace index for cycle detection and public-symbol reference tracking.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the tool performs cross-file checks (cycle detection, public symbol deletion) and is slower. However, it does not describe error behavior, side effects, or return values, leaving gaps in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the key purpose, and every sentence adds value. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 4 parameters, no output schema, and performs complex cross-file checks. The description fails to explain what the tool returns (e.g., success/failure, list of issues) and does not cover side effects or state changes. Incomplete for the complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional parameter-level meaning beyond what is in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is a workspace-aware gate that adds cross-file checks on top of validate_change, specifically detecting module import cycles and deletion of public symbols. It distinguishes itself from the sibling validate_change by noting it is slower and preferred for public API or shared module changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to prefer this tool when the change touches a public API or shared module, and notes it is slower than validate_change, implying it is not for quick local checks. It does not explicitly state when not to use, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.3
    • Addedattest_path
    • Addedvalidate_change_with_workspace
  2. 1 tool updatev1.0.0
    • First observedvalidate_change
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct stage and scope: post-write attestation, pre-write single-file validation, and pre-write workspace-aware validation. No overlap in purpose.

Naming Consistency5/5

All tool names follow a clear verb_noun pattern: 'attest_path', 'validate_change', 'validate_change_with_workspace'. The naming is consistent and descriptive.

Tool Count5/5

Three tools cover the essential validation and attestation workflow without redundancy. The count is well-scoped for the server's purpose.

Completeness4/5

The tool set covers pre-write and post-write validation, but lacks a tool for batch workspace-wide analysis without a specific change. Minor gap for complete coverage.

Maintenance

ActivityInactive
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers

  • Waymark by waymarks

    Waymarkofficial

    waymarks
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server that intercepts and controls AI agent actions in your codebase by enforcing policies on file operations and commands, with logging, approval workflows, and rollback capabilities.
    MIT

  • agent-locks

    luohoa97
    A
    license
    A
    quality
    F
    maintenance
    A filesystem-based MCP server for AI coding agents to coordinate work across git worktrees by claiming files, checking for conflicts, and logging progress without affecting the repository's git history.
    5
    MIT

  • godkiller-mcp

    taurus42119-stack
    A
    license
    A
    quality
    B
    maintenance
    An MCP server that enforces hard quality gates on AI coding agents, including forced web search, planning, and empirical test execution, to prevent common failure modes and ensure production-grade code.
    13
    30 PyPI
    27
    MIT

Appeared in Searches