API reference

CLI

Installed as retake and retake-dev. With npx, use npx retake-dev.

Environment: RETAKE_URL is --url for mcp. RETAKE_CACHE_DIR moves the wrapper config and Vite cache Retake keeps for a Vite app (default $TMPDIR/retake/). PORT is given to the dev command Retake starts. RETAKE_CODE_TIMELINES is for Next's proxy.ts / middleware.ts, where there are no flags: 1 separate code, 0 shared, unset the dock asks.

Code timelines

Each timeline can keep its own code (how it works). Turn it on or off with the dock's prompt, a lane's right-click menu, or:

Left unset, the dock asks once, the first time the code changes with two timelines; the answer is kept in .retake/settings.json.

retake code works with or without a dev server running (through its HTTP API when one is, else on .retake/ directly). Run it in the project, or pass --root.

Vite plugin

retake(options) returns the plugins for vite dev; it does nothing in vite build.

import { defineConfig } from "vite"
import { retake } from "retake-dev"

export default defineConfig({
  plugins: [
    retake({
      codeTimelines: "ask", // each timeline keeps its own code (true rewrites files when you switch)
      banner: true,        // the "Retake  timeline docked at …" line
    }),
  ],
})

Types ship with the package (RetakeOptions from retake-dev). The plugin turns on Vite's CSS source maps in dev unless you set them, so notes can point at CSS lines.

Server building blocks

For serving the dock from your own server (Retake's site does this on Vercel). All four come from retake-dev:

Session HTTP API

Every Retake server (the plugin and the front server) answers these under /__retake/. Timelines, recordings and notes are kept in .retake/.

The token

Every request that changes something needs the header x-retake-token. Reads don't. The token is random for each server start (or the plugin's token option). It's in .retake/server.json ({ url, base, token, pid }, readable only by you) and in the dock page as window.__RETAKE_TOKEN.

TOKEN=$(node -p 'require("./.retake/server.json").token')

curl -X PATCH http://localhost:3014/__retake/notes/nmg3k2x1a9f \
  -H "x-retake-token: $TOKEN" \
  -H "content-type: application/json" \
  -d '{"status":"resolved","reply":"Eased it out, 60ms delay."}'

window.__retake

Inside the dock's frame your app can read Retake's clock and timeline. In any other page or frame it's { inert: true }, and without Retake it's undefined. Types: add retake-dev/client to compilerOptions.types, or reference it.

/// <reference types="retake-dev/client" />

const rt = window.__retake
if (rt && !rt.inert) {
  // Running in Retake's frame.
  const off = rt.onPlayState(({ playing, now }) => {
    console.log(playing ? "playing" : "paused", "at", now, "ms")
  })
  const { markers, clips } = rt.timeline()
}

timeline()

• markers: your actions only, { t, end?, kind, label, selector? } with kind one of click, submit, route, focus or type. A type marker is one burst of typing (gaps under 800ms).
• clips: animations, { id, start, end, kind, label, selector, component?, property?, path, iterations?, pseudoElement? } with kind transition, css-animation or waapi; end is null while running.
• activity: samples at 10 Hz, { t, v }, where v (0 to 1) is how much of the viewport changed.

Room for the dock

Your app fills the window and the dock sits over its bottom edge. In the dock's frame, window.__retakeDockHeight is how many px it covers (0 when it's folded away), and a retake:dock event on window (detail: { height }) says when that changes.

const room = (h: number) => document.body.style.setProperty("padding-bottom", `${h}px`)
room(window.__retakeDockHeight ?? 0)
window.addEventListener("retake:dock", (e) => room(e.detail.height))