Step 01 · Start here · Start here · What Alembic is and how the pieces fit ENPT
Alembic Complete Visual Course

What Alembic is and how the pieces fit

A monorepo engine that turns goals into verified, teachable, publishable runs.

Read the plain version, or open the technical layer on any section.
1

The big idea

Alembic is a TypeScript monorepo designed to run an autonomous software-engineering loop. You give it a goal (a GOAL.md or a prompt), it plans, executes, verifies, and publishes a visual-teach course of what was done.

The engine is built in layers:

  • Contracts define the shared language: model adapters, tiers, results, signals.
  • Adapters talk to LLMs without ever throwing.
  • Swarm / VM / Mission execute tasks and plans.
  • Council / Coda deliberate and gate every run.
  • Harness / CLI / Web / TUI expose the engine to humans.

Think of it like… a research lab where every experiment is logged, peer-reviewed, and turned into a textbook chapter automatically.

Under the hood

Every package in the repo has a single responsibility and depends only on packages below it. @alembic/contracts is the leaf; @alembic/adapters implements the narrow waist; @alembic/etl handles cheap deterministic work; @alembic/swarm orchestrates tasks; @alembic/mission compiles missions; @alembic/vm runs alembic.plan.ts; @alembic/forge materializes scopes; @alembic/coda closes gates; @alembic/harness ties it together; and apps/cli is the human interface.

2

In one picture

Alembic Engine CLI / Web / TUI Harness Forge / Planf3 Swarm / VM Council / Coda Mission Adapters Contracts ETL / Ingestion LLM Providers
Alembic architecture: UI at the top, orchestration in the middle, adapters/contracts/ETL at the bottom, providers underneath.
3

In the code

# see the whole command surface
alembic help

# run the doctor to verify your environment
alembic doctor

# generate a plan from a prompt
alembic plan "Build a tiny HTTP service"

# execute a Forge scope
alembic forge "Build a tiny HTTP service"

Implementation notes

The CLI is implemented in apps/cli. It parses arguments with Node's util.parseArgs and validates them with Zod schemas from @alembic/contracts. Each command is a pure-ish function over validated args and injected writer/logger, so the CLI is testable without spawning subprocesses.

4

Try it

Run alembic doctor and read the summary. Then run alembic help and note which commands you already understand.

Reflect: Which layer would you debug first if a run failed silently — adapters, swarm, or coda?
5

Quick check

Which package is the dependency-free leaf that every other package imports?