What It Does

Aegis CLI scans your codebase, conducts a discovery conversation, and generates a complete .agentpolicy/ directory conforming to the Aegis governance specification.

You don't write policy files by hand. You talk to Aegis — it asks sharp questions about your project, your priorities, your boundaries — and compiles your answers into structured, schema-validated JSON that any agent can parse deterministically.

At the end of every session, Aegis produces a custom handoff prompt tailored to the conversation — ready to paste into your next agent session. It also configures the Aegis MCP connection automatically so runtime enforcement is in place from the first agent session.

Quick Start

# Install
npm install -g aegis-cli

# Start the discovery conversation
aegis init

# Have Aegis explain the current policy in plain language
aegis explain

# Validate policy files against the schema
aegis validate

On first run, Aegis asks you to pick a model. It supports Anthropic, OpenAI, Google Gemini, DeepSeek, and local/open-source models. API keys are stored per provider in ~/.aegis/config.json, and one provider is marked active. Note: Google Gemini allows OAuth. See Multiple Models, One Session below for the full provider list and how to swap models mid-conversation.

How aegis init Works

Run it in your project root. Aegis scans your repo — not just the file tree, but the actual contents of your config files, documentation, CI workflows, and project structure. By the time the conversation starts, Aegis already knows your stack, your architecture, your build pipeline, and your patterns.

If Aegis detects files that look sensitive — environment variables, credentials, database files — it skips them and tells you what it chose not to read. You decide whether it needs access.

From there, the conversation is focused and specific. Aegis doesn't ask what language you're using — it already knows. Instead, it asks about the things it can't infer from code alone:

• Your guiding principles and what's non-negotiable
• How much autonomy agents should have across different domains
• Which files are sacred and which are fair game
• How you want agents to coordinate when multiple roles are in play
• What should happen when an agent hits ambiguity or a gap in the rules

The conversation moves fast. When Aegis has the full picture, your .agentpolicy/ directory appears — complete, schema-validated, and ready for every agent that works here next.

Type /exit at any point to leave the session without writing changes.

Multiple Models, One Session

Aegis is provider-agnostic. The same discovery conversation runs against Anthropic, OpenAI, Google Gemini, DeepSeek, or any local/open-source model served through an OpenAI-compatible endpoint (Ollama, LM Studio, llama.cpp server, vLLM).

More importantly, you can swap models mid-session with /model without losing the conversation. The new model reads everything the prior one produced and picks up from the same state. Models hop in, look at the work in progress, and continue.

Concretely: drive the substantive discovery with one model, switch to a second model to review the playback before extraction, bring in a third for a second opinion on a contested architectural choice — all inside the same session, with the full prior context intact. The new provider becomes the default for your next aegis init unless you switch again.

Model choice becomes a per-turn decision, not a per-session commitment.

What Gets Generated

| File | Purpose | |------|---------| | constitution.json | Project identity, tech stack, principles, build commands | | governance.json | Autonomy levels, permissions, conventions, quality gates, escalation | | roles/*.json | Scoped role definitions with collaboration protocols | | state/ledger.json | Shared operational state and task tracking | | state/overrides.jsonl | Append-only log of policy overrides and construction sessions | | sessions/*.json | Complete session transcripts with closing guidance | | .mcp.json | MCP server connection config (project root) |

The session transcript captures the full discovery conversation plus the handoff prompt, deployment intent, and file list — so you can review the reasoning behind every governance decision at any time.

Return Visits

Run aegis init again in a repo that already has .agentpolicy/ and Aegis picks up where you left off. It reads the existing policy files and prior session transcripts — it knows the full history of how governance was built and why. No full rediscovery — it asks what's changed, and updates only what needs updating.

The Handoff

After generating policy files, Aegis displays three things:

1. Your Handoff Prompt — A custom prompt crafted from the conversation, ready to paste into your next agent session. For new builds, it instructs the agent to select the construction role and build in the right sequence. For return visits with changes, it describes the specific delta to apply. For existing projects getting governance, it points the agent at the right specialist role.

2. MCP — Confirms the MCP connection is configured and provides the install command.

3. For All Future Sessions — The standard prompt for every session after the initial build, ensuring agents always start by calling aegis_policy_summary and getting user confirmation before proceeding.

Runtime Enforcement

The Aegis MCP provides runtime enforcement of the governance Aegis CLI generates. The CLI automatically creates the .mcp.json connection config, so agents connect to the MCP on their first session without additional setup.

The MCP validates every write, delete, and execute operation against the loaded policy — zero token overhead, full audit trail. It also provides a construction role for initial builds, where the agent uses governance files as a blueprint but runs native tools for speed, with the session logged for auditability.

Three artifacts, one governance framework:

• aegis-spec — The governance standard
• aegis-cli — Generates the governance
• aegis-mcp — Enforces the governance

Requirements

• Node.js >= 22.3.0
• Credentials for whichever hosted provider you choose, Google browser sign-in for Gemini, or a running local OpenAI-compatible server for local/open-source models

Aegis can read provider keys from the environment or from ~/.aegis/config.json. For API-key authentication, the active provider's environment variable wins over the stored key for that provider:

| Provider | Environment variable | |----------|----------------------| | Anthropic | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY | | Google | Browser sign-in, or GOOGLE_API_KEY / GEMINI_API_KEY | | DeepSeek | DEEPSEEK_API_KEY | | Local/open-source model | AEGIS_CUSTOM_API_KEY |

For local/open-source models, Aegis prompts for the local server base URL and model ID. The API key is optional because many local servers do not require authentication.

For Google Gemini, choose "Sign in with Google" to authenticate in your browser. If a Google API-key environment variable is set, unset it before using browser sign-in, or choose the API-key path instead.

License

MIT

Built by Cleburn Walker as the reference implementation of the Aegis governance specification.