Getting Started

Install

npm — global (recommended)

npm install -g @collivity/aglang

npx — no install needed

npx @collivity/aglang add .

GitHub URL

npm install github:collivity/aglang

Requirements:

• Node.js ≥ 18 — nodejs.org
• A git repository

The solver ships via the z3-solver npm package (WebAssembly) — no system install needed.

---

Quick setup — one command

aglc add /path/to/your/project --name MyApp

That's it. This single command:

1. Scans your project (C#, Python, TypeScript, Go, Rust, Swift, JVM — all supported)
2. Generates architecture.ag — a starter spec with discovered components and routes
3. Compiles it to architecture.o
4. Installs a git pre-commit hook — every commit is now checked
5. Emits skill.json so AI agents understand your architectural rules

---

Add your first rule

Open the generated architecture.ag and add an invariant block:

invariant NoDirectDBAccess {
  deny flow PublicAPI -> Database
}

Then recompile:

aglc compile architecture.ag

From now on, any commit that creates a direct path from PublicAPI to Database is blocked with a precise error message and proof details.

---

How it works

Your codebase                   Your .ag spec
     │                               │
     ▼                               ▼
[Git Diff Extractor]    +    [Architecture Compiler]
     │                               │
     └──────────── Z3 Solver ────────┘
                        │
               UNSAT → commit passes ✓
               SAT   → commit rejected with proof ✗

1. You write an architecture.ag file describing components and invariants
2. aglc compile translates it to SMT-LIB and emits architecture.o
3. A pre-commit hook runs Z3 against every staged diff — violations are blocked before they land

---

Designed for AI Agents

AI coding agents (Copilot, Claude, Cursor, etc.) can operate autonomously for long stretches. aglang acts as guardrails — mathematical constraints the agent cannot violate even if it hallucinates an architecture change.

• aglc add generates a starter spec, installs the hook, and emits skill.json in one command
• Agents read AGENTS.md (generated by aglc emit-context) to understand boundaries before they start
• Every commit attempt is checked — human or agent alike

See the AI Agents guide for the full integration workflow.