ALC — Agentic Layer Compiler & Runtime

Declare how your agents should work once. Run it on any coding engine — with the guardrails built in.

English | Português

ALC is a control plane for agentic coding. It keeps the good practices — verification, focus, isolation, review — outside the model, in plain deterministic code. The coding engine (Claude Code, Gemini, …) becomes a thin, swappable executor.

The point: best practices stop being discipline you have to remember, and become defaults you can't skip.

✨ Highlights

• 🛡️ Guarantees outside the model — the Assurance Loop runs your checks and repairs until they pass. Nothing is reported done until it actually is.
• 🔌 Engine-agnostic — Claude Code or Gemini. Switch with a flag; the control plane doesn't change.
• 🎯 One agent, one purpose — every task is a focused Single Mandate. No context pollution.
• 🧩 Composable — Blueprints → Flows → a Conductor that turns a goal into the right Flows.
• 🌙 Unattended — drop tasks in a queue; cron's alc tick drains them, isolated, while you're away.
• 🧠 Specialists — agents that keep a Knowledge File and get better at an area over time.
• 🔒 Isolated — --isolate runs the work in a throwaway git-worktree branch, so your working tree stays clean.

🚀 Quick Start

New to ALC? The first-run guide walks you from install to a verified change, with the rough edges flagged.

If you set up with uv sync, prefix the commands below with uv run (e.g. uv run alc lint).

Install — one command, and the same one updates you later.

macOS and Linux:

curl -fsSL https://alc-runtime.vercel.app/install.sh | sh

Windows (PowerShell):

irm https://alc-runtime.vercel.app/install.ps1 | iex

It installs uv if you do not have it, installs alc-runtime[ui], and puts the command on your PATH — the step people otherwise hit. Read it first if you would rather: install.sh · install.ps1.

uv tool install alc-runtime          # installs the `alc` command
uv tool install "alc-runtime[ui]"    # …with the web UI (dashboard, live runs)

The PyPI package is alc-runtime; it puts the alc command on your PATH.

Hacking on ALC itself? uv sync in a clone and prefix commands with uv run.

Set up a project — three steps from zero to a validated Operator Layer:

cd your-project
alc init --setup     # 1. scaffold .alc/ (detects your stack) + install the editor skill
alc onboard          # 2. adopt the checks your project ALREADY declares (Makefile targets,
                     #    package.json scripts) — proposes first, you approve
alc lint             # 3. validate the Operator Layer

Run

# Safe by default: the scaffolded manifest uses the free Mock engine (no model calls).
alc run chore "remove the unused export endpoint"

# Use a real engine when you're ready:
alc run chore "tidy the imports"        --engine claude-code
alc run chore "tidy the imports"        --engine claude-code --tier standard
alc flow ship "add a changelog entry"   --engine claude-code --isolate
alc conduct "the README is stale, refresh the docs" --engine claude-code --parallel
alc primer new my-context               # scaffold a Primer at .alc/primers/my-context.md
alc tick --concurrency 4                # drain the queue 4 tasks at a time

🧭 Commands

By intent — the fast path when you already know what you want:

🖥 Web UI

alc ui serves a local, single-user web IDE — an IntelliJ-like control room for every registered project: dashboard, queue, live runs (Assurance Loop timeline), loops and config, all updated in real time over WebSocket (no refresh, ever).

uv tool install "alc-runtime[ui]"   # or: uv sync --extra ui
alc ui                              # http://127.0.0.1:8642 — frontend served by default
alc ui --lan                        # binds every interface, prints the address for other devices

The frontend lives in ui/ (React + Vite + TypeScript). Development workflow:

cd ui && npm install
npm run dev        # Vite dev server proxying /api and /ws to 127.0.0.1:8642
npm run build:alc  # publish the production build into src/alc/ui/static/ (gitignored; shipped in the wheel)

--lan prints a Network: line with the address to type on any other device on your network (another laptop, a desktop, a tablet, a phone) — pair it with --token T on any network you do not control. --ui-dist PATH serves an alternative build; --no-ui serves only the API/WebSocket.

🧱 How it fits together

ALC lives in a ring around your codebase — the Operator Layer (.alc/), kept separate from your app code:

• Blueprint — a template for a class of work (chore, bug, feature…), carrying its own checks and report.
• Flow — Blueprints composed into a pipeline; each stage is its own mandate, threading context forward.
• Conductor — turns a high-level goal into the right Flows, then runs or queues them.
• Specialist — an agent with a Knowledge File for one area, improving as it works.
• Assurance Loop — Act → Verify → Repair. Your checks are the law.
• Scorecard — tracks Span / Passes / Streak / Touch, heading toward hands-off delivery.

🪜 Where you are on the ladder

ALC grows with you: Attended (you run it) → Detached (it runs unattended off the queue) → Conducted (a Conductor drives the Flows for you). You don't start at the top — you climb.

📚 Documentation

alc-runtime.vercel.app — the full documentation site: getting started, concepts, guides, and the CLI reference.

• Concepts & vocabulary — the words ALC uses, and the two-plane model
• Architecture — the control-plane / execution-plane diagram
• Engine contract — what it takes to plug in an engine
• MVP & roadmap

🧪 Status

Experimental, but real: every feature is covered by a hermetic test suite and validated live against Claude Code and Gemini. Python 3.12 + uv, no heavy dependencies.

📄 License

MIT © gifflet