Install

Requirements

• Node 18 or newer.
• A Vite 5+ app served from an index.html (React, Vue, Svelte, plain JS), or any dev server that serves HTML: Next.js, React Router, Remix, Nuxt, SvelteKit, Astro.
• Chrome, Edge or another Chromium browser. That's what it's tested on (browsers).

Install with your agent

Paste this into Claude Code, Cursor or any coding agent:

Add Retake to this project so its timeline shows on the normal dev URL: install retake-dev as a dev dependency with the project's package manager. Put the Next file next to the app/ folder (the root, or src/ for src/app). Next.js 16: add proxy.ts with export { default } from "retake-dev/next". Next.js 15: add middleware.ts with import retake from "retake-dev/next", export default retake, export const config = { runtime: "nodejs" }. If a proxy or middleware already exists, wrap its default export in withRetake from "retake-dev/next". Vite: add retake() from "retake-dev" to the Vite plugins. Anything else: add a "dev:retake": "retake ." script to package.json. Add .retake/ to .gitignore, and don't change anything else. Docs: https://retake-omega.vercel.app/docs/install

Or install the skill once and run /retake in your agent:

npx skills add LightningDesigner/retake

The skill does the same, and also connects the MCP server: it adds retake to the project's .mcp.json (or .cursor/mcp.json), so your notes reach your agent without another step. Your agent asks once to turn it on. It installs a second skill, retake-notes, on how to work through notes.

Try it without installing

npx retake-dev .

Open the URL it prints (http://localhost:3014 by default). On a Vite app it runs your own vite.config through a wrapper kept in your temp folder; on a framework it runs your dev script and sits in front of it. Retake keeps its session in a .retake/ folder in the app, which git-ignores itself.

Install in the project

npm i -D retake-dev

Then run it from node_modules:

npx retake .

Or add a script, so npm run retake starts it:

{
  "scripts": {
    "dev": "vite",
    "retake": "retake ."
  }
}

Vite plugin

To keep your usual npm run dev, add the plugin to vite.config instead. npx retake-dev init prints these lines.

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

export default defineConfig({
  plugins: [retake(), /* ...your plugins */],
})

retake() only runs in vite dev; vite build output has no Retake code in it. With no index.html in the Vite root (React Router, SvelteKit, Astro and other Vite-based frameworks render their own pages), the plugin docks into the pages your framework renders, on your usual dev server port. Options are on the API page.

Next.js

Install retake-dev in the project (above), add one file, and keep running next dev: the timeline shows on your usual dev URL, with no second port. npx retake-dev init prints these lines.

• Where the file goes: next to your app/ folder. That's the project root, or src/ if your app lives in src/app (src/proxy.ts / src/middleware.ts).
• Which file: Next 16 and Next 15 need different ones. Check next in your package.json.

export { default } from "retake-dev/next"

import retake from "retake-dev/next"
export default retake
export const config = { runtime: "nodejs" }

Open the page in a browser to see the timeline. It's added only for real page loads, so curl shows the plain page, and the first request or two right after next dev starts may arrive before Retake has loaded (“Retake timeline docked” prints when it has).

It only runs in next dev; in next build and next start every request goes straight on, and the build has no dock or runtime in it. Notes and npx -y retake-dev mcp work as with the CLI. For separate code per timeline without CLI flags, set RETAKE_CODE_TIMELINES=1 (more).

Install it from the registry (or a tarball). A file: or linked install is a symlink, which Turbopack doesn't follow out of the project, and retake-dev/next isn't found.

Already have a proxy or middleware? Wrap yours:

import { withRetake } from "retake-dev/next"

export default withRetake(async (req) => {
  // ...your middleware, as before
})

Next reads config from your file as written, so it can't come from Retake. With a matcher of your own, add Retake's two entries to it. Your function then also sees page loads it didn't match before.

export const config = {
  matcher: [
    "/__retake/:path*",
    { source: "/((?!_next/static|_next/image).*)", has: [{ type: "header", key: "sec-fetch-mode", value: "navigate" }] },
    // ...your entries
  ],
}

Without installing anything, npx retake-dev . runs next dev behind Retake's own port (3014) instead. Behind that front server a rebuilt moment gets the page's HTML as it was recorded; with proxy.ts the page is rendered again.

Frameworks

A Vite single-page app gets Retake from the plugin. Anything that renders its own HTML gets it from Retake's front server: Retake listens on its port, serves the dock there, and passes everything else through to your dev server, adding a small script to the framed page as it streams. Assets, data fetches, server actions, API routes and the HMR socket go through untouched.

retake . picks the front server for a project that depends on Next, Nuxt, React Router (framework mode), Remix, SvelteKit, Astro, TanStack Start, SolidStart, Vike, Waku or Analog, and runs its dev script with the package manager its lockfile names.

Tested means: the app hydrates in the dock with no warning, and recording, scrubbing back, the rebuilt moment, Play, hot updates and reloads all work, started either way. The untested ones go through the same front server.

Arguments for your dev server

Anything after -- goes to the dev server. Without a project before it, it's the command to run:

npx retake-dev . -- --host        # retake runs your dev script with --host
npx retake-dev -- next dev --turbo  # retake runs this command

Next.js 16

Next 16 sends React debug data for each request over its HMR socket. Retake keeps it with the recording and hands it back on replay, so nothing needs changing. For a Next version with a debug channel Retake doesn't know yet, it prints a warning that says to set experimental: { reactDebugChannel: false }.

A server that's already running

npx retake-dev http://localhost:3000

Retake serves the dock on its own port and proxies to that server. Ctrl-C stops Retake; your server keeps running.

Ports

• Retake serves on 3014; --port 4000 picks another.
• For a dev command it starts, Retake sets PORT to a free port (or keeps yours if it's free), and otherwise follows the first http://localhost:… the command prints, so tools that ignore PORT work too.
• Ctrl-C stops the dev server with it.
• The front server only answers requests for localhost, *.localhost and IP addresses. For OAuth sign-in, see the FAQ.

Uninstall

npm uninstall retake-dev    # or pnpm remove / yarn remove / bun remove
rm -rf .retake              # the session, recordings, notes and code snapshots
claude mcp remove retake    # if you added the MCP server

Remove retake() from vite.config or Retake's proxy.ts / middleware.ts if you added it, the retake entry from .mcp.json if the skill added one, and the server from any other MCP client's settings. With separate code on, stop Retake first so the newest code is back on disk.