gaido

A lab notebook for creative-coding agents. Type a brief; a coder agent
builds it — a website, a Pixi scene, a canvas experiment — a renderer films
the result, a critic reviews it. Every attempt is a node on a graph you can
fork.

Local-first: your filesystem, your git, your keys.

gaido.ai · Quickstart · How it's built

One client brief — "a slow glass blob, iridescent like oil on water" —
pushed through three takes in one branch. The critic called take one pastel
and take two a cool tunnel; take three got its amber sweep. Then the actual
index.html from the third node's git worktree, opened. The video in the
card and the file on disk are the same thing.

The loop

One instruction in, one rendered variation out. The coder works in its own
git worktree; the renderer drives headless Chromium on a fixed clock, so a
scene renders the same way twice. When the run finishes, a critique slot
opens under it.

Fork, don't undo

A node is a slot; runs are attempts to fill it. Fork from any point — a fork
is a git branch, so siblings are cheap and nothing is overwritten. Above: one
bakery brief pushed through three passes in a single branch (the critic kept
rejecting the hero loaf), a dark A/B sibling, and a second client on the same
canvas. Failed branches stay too. They're part of the experiment.

A critic in the loop

A critic agent — or you; reviewing every render yourself is a first-class
mode — judges each run against its brief: a rating, concrete weaknesses,
proposed rules. When feedback should outlive one branch, promote it: the rule
lands in LESSONS.md, plain markdown at the project root, and every fresh
session starts from it. The fork above read "smooth vector shapes are not a
substitute for hand-drawn assets" before it redrew the loaf.

Switch coders mid-graph

Coders are adapters — Claude Code, Codex, OpenCode, and Cursor ship in the
box. Run several inside one exploration, switch under any critique, and the new
coder continues from the same committed code — resuming the session where the
adapter allows it, resetting cleanly where it doesn't.

Quickstart

mkdir drift-studies && cd drift-studies
npx gaido init
npx playwright install chromium   # one-time: the renderer's browser
npx gaido

Opens the graph at 127.0.0.1:4288, pointed at the current directory. The
init template runs end-to-end on stub adapters; wire real ones in
gaido.config.ts:

import {
  defineConfig,
  claudeCodeCoder,
  codexCoder,
  opencodeCoder,
  cursorCoder,
  geminiCritic,
  playwrightRenderer,
} from 'gaido';

export default defineConfig({
  coders: {
    'cc-sonnet': claudeCodeCoder({ model: 'sonnet' }),
    'cc-opus': claudeCodeCoder({ model: 'opus' }),
    codex: codexCoder({ effort: 'medium' }),
    // OpenCode reaches any provider it's configured for; this hosted one is free, no key.
    opencode: opencodeCoder({ model: 'opencode/deepseek-v4-flash-free' }),
    // Cursor CLI; effort is part of the model id (`cursor-agent models` lists them).
    cursor: cursorCoder({ model: 'auto' }),
  },
  critic: geminiCritic(), // or humanCritic() — your eye, no API
  renderer: playwrightRenderer(),
  render: { width: 1024, height: 1024, fps: 30, duration: 5 },
});

Requires Node 20+ and ffmpeg. The bundled coder adapters shell out to the
claude / codex / opencode / cursor-agent CLIs — your existing
subscriptions and logins, no extra keys.

How it's built

• The graph is the workflow. No workflow engine — SQLite, a state
  machine, and an events table. Nodes alternate coder → critique, with
  config nodes marking mid-graph switches.
• Versioning is git. Each coder node owns a worktree and a branch backed
  by one bare repo. Fork = git worktree add off the parent's tip. Retry
  stacks a commit. Diffs and reverts come free.
• Renders are reproducible. Headless Chromium with a faked clock steps
  through frames; ffmpeg encodes. Same code, same video. Websites get a
  scroll-through capture — the camera pans the page, slower when the page
  is tall, so the critic sees every section.
• Adapters are the only pluggable surface. Coder, critic, renderer —
  three interfaces in @vadimlobanov/gaido-core. Everything else is deliberately
  hardcoded.
• Skeletons seed roots. Named starting points (skeletons/<name>/) per
  root node, so sibling roots can A/B different starting contexts. Init ships
  three — default (Pixi), css, and website, whose config overlay swaps
  in the scroll renderer and a web-designer critic for that lineage only.
• References feed the coder. Attach images or other runs to any node;
  they're materialized into the worktree, excluded from the art's diff.

Status

Early and moving. Local-first, single-user by design. Built in the open —
the graph model is settling, the adapter interfaces are nearly stable.

MIT © Vadim Lobanov