From sources to videos

ageation is an operator: it acts on a project that sits beside it — a paper, a book, or a single self-contained document. Your LaTeX stays yours, untouched; everything the engine creates lives in one reserved folder inside your project. Four steps to a first video.

1 · Get the engine

Clone the repository. This is the engine — the tools, the Python environment, the house style, and the docs. You never copy it into your projects; one clone drives them all.

git clone https://github.com/AgentsCreation/ageation.git
cd ageation

2 · Install the dependencies

One command installs both halves: the system packages via Homebrew (uv, FFmpeg, a LaTeX distribution) and the Python side (Manim, manim-voiceover) into a project-local environment. macOS is the tested path; rendering wants a real machine, not a cloud sandbox.

make setup        # brew bundle  +  uv sync

MacTeX is ~5 GB. The Brewfile documents a ~100 MB BasicTeX alternative if you prefer to install LaTeX packages on demand.

3 · Place your project as a sibling

Your project — a book, a paper, or a standalone lesson — sits next to the engine, and the engine operates on it. All generated files land in one reserved subfolder, ageation/, inside your project. Nothing else in your repo is written to; your sources are read-only to the pipeline and vendored (with content-hash provenance) before any edit.

your-workspace/
├── ageation/                 ← the engine (this repo)
└── your-project/             ← a sibling: book, paper, or lesson
    ├── chapters/…            ← your LaTeX — never touched
    └── ageation/             ← everything the engine creates
        ├── project.yaml      ← the spine: chapters, notation, voice
        ├── .gitignore        ← keeps media/ and .env out of git
        ├── sources/          ← vendored, editable copies of your LaTeX
        ├── content/          ← concept maps + narrated scripts
        ├── scenes/           ← generated Manim code
        └── media/            ← rendered beats + one .mp4 per topic

Bootstrap the manifest from your chapters, then review it — the chapter order, prerequisites, and notation rules are yours to shape:

mkdir -p ../your-project/ageation
uv run python tools/init_project.py ../chapters \
    --project ../your-project/ageation --scaffold-concepts

4 · Make videos

Every tool takes PROJECT=, so the engine operates on any sibling from one place. Gates run before renders: provenance, notation, review status, and a geometric lint that replays every animation looking for layout collisions.

make check       PROJECT=../your-project/ageation   # all gates
make video-draft PROJECT=../your-project/ageation   # free 480p draft
make video       PROJECT=../your-project/ageation   # 1080p60 final

The deliverable is one reviewable .mp4 per topic — per-beat clips stay on disk for cheap iteration, and draft narration uses free TTS so trying costs nothing.

Working agentically

The commands above are the explicit path. The everyday one is to just talk to the engine: open Claude Code or Codex in the engine folder and point it at a sibling.

Apply the agentic video creation workflow to sibling project ../your-project

From that one line the agent reads the docs, bootstraps the manifest, vendors your sources, and walks the pipeline — you steer in plain language and review at the gates. No command to memorize; the engine already knows its own workflow.

Underneath, the layer transforms — LaTeX to concept map, concept to narrated script, script to Manim scenes — ship as agent skills over a deterministic scaffolder. /animate-chapter walks a single topic through the whole pipeline and pauses at two review points: the concept and the script. Review them (optional), leave timestamped notes against the draft video, and the engine fixes at the right layer — narration in the script, visuals in the scene — with provenance keeping every layer honest.

Clone the engine → Why this works