Installation

ALC needs Python 3.12 or newer. The PyPI package is alc-runtime; it puts the alc command on your PATH.

Before you install#

ALC ships no model. It drives a coding CLI you already have — the claude binary from Claude Code, or gemini from the Gemini CLI. If you have neither, installing still works and alc init will select the Mock engine: a free, hermetic no-op that exercises the whole control plane and changes no code. That is genuinely useful for proving your setup, and it is not what you want for real work, so it is worth knowing which one you are getting before you start.

Install#

One command. It picks up your OS below; switch tabs if it guessed wrong.

The same command updates you later — it is idempotent, so running it again moves you to the latest release.

Verify:

alc --version                        # alc X.Y.Z

What the script does#

Three steps, in order:

1. Installs uv if you do not already have it. ALC ships on PyPI, and uv is what puts a Python CLI on your PATH without a virtualenv for you to manage.
2. Installs or upgrades alc-runtime[ui] — the package plus the optional web UI. Set ALC_NO_UI=1 to skip the UI extra.
3. Puts uv's tool directory on your PATH, by appending to your login shell's rc file on macOS and Linux, or to your user PATH on Windows. It checks first, so running it twice does not add the line twice.

It refuses to guess: if it cannot write your rc file, it prints the line for you to add rather than failing silently.

Installing by hand#

The script is a convenience, not a requirement. If you already have uv, or you would rather see every step:

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

uv tool install puts the binary in ~/.local/bin. If alc --version reports "command not found", that directory is not on your PATH — which is the step the script above exists to handle.

Upgrading from the old package name? Early releases shipped as alc rather than alc-runtime. If uv tool list shows both, run uv tool uninstall alc: the stale tool competes for the alc executable, and a later uv tool upgrade --all could hand the name back to an old binary. The install script above does this for you.

Pick an engine#

ALC does not ship a model. It drives one you already have installed:

alc init probes your PATH and picks one for you: claude found means default_engine: claude-code, gemini found means gemini, neither means mock. The init output tells you which it chose.

The Mock engine is not a toy you have to skip past. It exercises the whole control plane — the Policy Gate, the Assurance Loop, the Scorecard — with no model call, so you can prove your Operator Layer works before you spend anything on it.

The optional web UI#

alc ui serves a local, single-user web IDE for every registered project. It needs the ui extra:

uv tool install "alc-runtime[ui]"
alc ui                               # http://127.0.0.1:8642

See Web UI for what it can do.

Working on ALC itself#

Clone the repository and use uv sync. Every command below then needs a uv run prefix:

uv sync                              # or: uv sync --extra ui
uv run alc lint

One trap worth knowing: uv tool install --force silently reuses a cached build when the version is unchanged. If you are iterating on ALC and reinstalling as a tool, bump the version first or your changes will not land.

Editor skill (optional)#

alc setup installs a user-level skill that teaches your editor's agent to drive the alc CLI instead of editing files directly:

alc setup --engine claude-code       # or: --engine gemini

alc init --setup does this as part of scaffolding a project, so you rarely need to call it on its own. Re-run it to pick up a newer version of the skill.

Next#

First run — ten minutes from an empty project to a verified change.