backstep 0.1.2 → 0.1.4

package/README.md

@@ -8,6 +8,7 @@ Undo for everything your agents touch. Backstep sits between your agent (Claude
 - **Supabase:** `execute_sql` and `apply_migration` snapshot the tables they change, over a connection to the project's database. Backstep never connects it on its own: when Claude Code opens a project that uses Supabase and isn't connected, it asks (Connect, Not now, or Don't ask for this project). Connect uses a connection string in the project's `.env` files, the local `supabase start` database, or a Supabase sign-in (`supabase login`, `SUPABASE_ACCESS_TOKEN`, or an access token you give Backstep once), with which the project gets a temporary database login that Backstep renews as it runs out. You can also ask Claude to "connect Backstep to Supabase" any time. Deleted rows, dropped tables and migrations, including the migration's history row, all come back. Works for the claude.ai Supabase connector and a local Supabase MCP server alike.
 - **Firebase:** before a change, Backstep reads what's there through the Firebase MCP server itself, and undoes through it too, so there's nothing to set up. Firestore documents updated, deleted or added; Realtime Database writes; Remote Config publishes (rolled back to the version before); and users enabled or disabled.
 - **claude.ai connectors and servers Claude Code signs in to:** Backstep can't sit in front of these, so the Claude Code mod watches their calls instead. Calls with an undo rule are undone through Claude Code's own connection.
+- **Database commands Claude runs** (`supabase db push`, `supabase migration up`, `supabase db reset`, `psql`, `prisma migrate`, `drizzle-kit push`, seed scripts…): in a project whose Supabase database is connected, the whole database is noted before the command runs, and ctrl+z puts it back in one transaction: rows, new tables dropped, dropped or altered tables rebuilt with their constraints, indexes, foreign keys, row level security policies, triggers and grants, sequence counters, and the migration history. Copies sit in a `backstep` schema in the same database; the newest 10 per database are kept. On a very big database it keeps every table's structure and the migration history, and rows smallest-table-first up to a budget (`BACKSTEP_DB_SNAPSHOT_MB`, default 250); undo names any table whose rows it couldn't bring back. Functions, views, types and extensions aren't restored.
 - **Code Claude pushed:** ctrl+z rewinds the commits locally, then asks whether to undo them on GitHub (or any remote) too. Yes pushes one new commit that undoes Claude's, made in a temporary worktree: no force push, no rewritten history, so it works on protected branches and for teammates who already pulled. Newer commits that clash, or a rewritten branch, stop it. A branch Claude created is deleted instead, if nobody has added to it. It uses the project's own git sign-in, so there's nothing to connect.
 - **Things that can't be undone** (sending email, payments, deploys, `ALTER TABLE`…) run as normal and are marked in the journal, so you know what an undo didn't cover.
 - **Anything else, by rule:** a rules file maps a tool to its opposite (`create_issue` → close the issue, `send_message` → retract it), filled in from the call and its result. See [Undo rules](#undo-rules).
@@ -52,6 +53,8 @@ With Claude Code: `claude mcp add files -- backstep wrap --name files -- <the se
 | `--rules <file>` | undo rules (or set `BACKSTEP_RULES`) |
 | `--pg <url>` | the Postgres database the wrapped server writes to. Enables database undo. Without it, SQL writes are recorded but can't be undone. |
 
+The undo key is ⌘Z and ctrl+z on a Mac (⌘Z where the terminal passes it on, as Ghostty, Kitty and WezTerm do; Terminal.app and iTerm2 keep ⌘Z for their own menu) and ctrl+z elsewhere. The first press asks "Undo Claude's last turn?" above the prompt and a second press within 5 seconds undoes, so a stray press does nothing. Change the key whenever you like: ask Claude ("change my Backstep undo key to ctrl+u"), or run `backstep key ctrl+u`. The line above the prompt is always there, even with nothing to undo, because the key only reaches Backstep while it's on screen; otherwise ctrl+z would fall through to the terminal and suspend Claude Code.
+
 Backstep checks npm for a newer version as each Claude Code session starts and asks before updating (Update, Not now, or Skip this version; `backstep update` does it by hand, `BACKSTEP_UPDATE_CHECK=0` turns the check off).
 
 Other commands: `backstep ui`, `backstep log`, `backstep undo <action-id>`, `backstep undo --run <run-id>`, `backstep connect [supabase|firebase]` (connects what the project uses, the same as asking Claude), `backstep disconnect supabase <ref>`.

package/dist/adapters/dbsnap.js

@@ -0,0 +1,265 @@
+// Database undo for shell commands (`supabase db push`, `supabase migration up`,
+// `psql`, `prisma migrate`, seed scripts…), which change a database Backstep
+// can't see into. Before the command runs, the whole database's own tables are
+// noted:
+//  - every table's structure: columns, constraints, indexes, foreign keys,
+//    row level security and its policies, triggers, grants, sequence counters;
+//  - every table's rows, copied into Backstep's own schema in the same
+//    database, smallest tables first, until a size budget is spent. A very big
+//    database keeps its structure, its migration history and as many tables'
+//    rows as fit; undo names the tables whose rows it couldn't bring back.
+// Undo, in one transaction: drops tables made since, rebuilds tables dropped
+// or reshaped, and puts back rows wherever they changed.
+import pg from "pg";
+import { q } from "./postgres.js";
+const SNAP_SCHEMA = "backstep";
+const budget = () => Number(process.env.BACKSTEP_DB_SNAPSHOT_MB ?? 250) * 1024 * 1024;
+// Supabase's and Postgres's own schemas: managed by them, not by the project's migrations.
+const SYSTEM = [
+    "information_schema", "auth", "storage", "realtime", "_realtime", "extensions", "graphql", "graphql_public", "pgsodium",
+    "pgsodium_masks", "vault", "net", "supabase_functions", "cron", "pgbouncer", "_analytics", "_supavisor", "pgtle", "topology",
+    "tiger", "tiger_data",
+];
+const MIGRATIONS = "supabase_migrations";
+async function withClient(url, fn) {
+    const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 10_000 });
+    await client.connect();
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.end();
+    }
+}
+async function tables(c) {
+    const r = await c.query(`SELECT c.oid::int AS oid, n.nspname AS schema, c.relname AS name, pg_total_relation_size(c.oid)::bigint AS bytes
+     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE c.relkind = 'r' AND NOT c.relispartition
+       AND n.nspname NOT LIKE 'pg\\_%' AND n.nspname NOT LIKE 'backstep%' AND n.nspname <> ALL($1::text[])
+     ORDER BY n.nspname, c.relname`, [SYSTEM]);
+    return r.rows.map((x) => ({ oid: Number(x.oid), schema: x.schema, name: x.name, bytes: Number(x.bytes) }));
+}
+const full = (t) => `${q(t.schema)}.${q(t.name)}`;
+async function shapeOf(c, oid) {
+    const r = await c.query(`SELECT string_agg(attname || ' ' || format_type(atttypid, atttypmod), ', ' ORDER BY attnum) AS s
+     FROM pg_attribute WHERE attrelid = $1 AND attnum > 0 AND NOT attisdropped`, [oid]);
+    return r.rows[0].s ?? "";
+}
+async function describe(c, t) {
+    const name = full(t);
+    const cols = await c.query(`SELECT a.attname, format_type(a.atttypid, a.atttypmod) AS type, a.attnotnull, a.attidentity, a.attgenerated,
+            pg_get_expr(d.adbin, d.adrelid) AS def
+     FROM pg_attribute a LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+     WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [t.oid]);
+    const seqs = await c.query(`SELECT s.oid::regclass::text AS name, a.attname
+     FROM pg_depend dep JOIN pg_class s ON s.oid = dep.objid AND s.relkind = 'S'
+     JOIN pg_attribute a ON a.attrelid = dep.refobjid AND a.attnum = dep.refobjsubid
+     WHERE dep.refobjid = $1 AND dep.deptype IN ('a', 'i')`, [t.oid]);
+    const seqValues = [];
+    const create = [];
+    // Serial columns' sequences go with their table; make them first so the defaults resolve.
+    const serial = seqs.rows.filter((s) => !cols.rows.find((col) => col.attname === s.attname)?.attidentity);
+    for (const s of serial)
+        create.push(`CREATE SEQUENCE IF NOT EXISTS ${s.name}`);
+    const defs = cols.rows.map((col) => {
+        let d = `${q(col.attname)} ${col.type}`;
+        if (col.attgenerated === "s")
+            d += ` GENERATED ALWAYS AS (${col.def}) STORED`;
+        else if (col.attidentity)
+            d += ` GENERATED ${col.attidentity === "a" ? "ALWAYS" : "BY DEFAULT"} AS IDENTITY`;
+        else if (col.def !== null)
+            d += ` DEFAULT ${col.def}`;
+        if (col.attnotnull)
+            d += " NOT NULL";
+        return d;
+    });
+    create.push(`CREATE TABLE ${name} (${defs.join(", ")})`);
+    for (const s of serial)
+        create.push(`ALTER SEQUENCE ${s.name} OWNED BY ${name}.${q(s.attname)}`);
+    for (const s of seqs.rows) {
+        const v = await c.query(`SELECT last_value::text AS v, is_called FROM ${s.name}`);
+        seqValues.push({ name: s.name, value: v.rows[0].v, called: v.rows[0].is_called });
+    }
+    const cons = await c.query(`SELECT conname, contype, pg_get_constraintdef(oid) AS def FROM pg_constraint
+     WHERE conrelid = $1 AND contype IN ('p', 'u', 'c', 'x', 'f') ORDER BY contype = 'p' DESC, conname`, [t.oid]);
+    const fks = [];
+    for (const k of cons.rows) {
+        const sql = `ALTER TABLE ${name} ADD CONSTRAINT ${q(k.conname)} ${k.def}`;
+        if (k.contype === "f")
+            fks.push({ name: k.conname, sql });
+        else
+            create.push(sql);
+    }
+    const idx = await c.query(`SELECT pg_get_indexdef(i.indexrelid) AS def FROM pg_index i
+     WHERE i.indrelid = $1 AND NOT EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conindid = i.indexrelid)`, [t.oid]);
+    for (const i of idx.rows)
+        create.push(i.def);
+    const rls = await c.query(`SELECT relrowsecurity, relforcerowsecurity FROM pg_class WHERE oid = $1`, [t.oid]);
+    if (rls.rows[0].relrowsecurity)
+        create.push(`ALTER TABLE ${name} ENABLE ROW LEVEL SECURITY`);
+    if (rls.rows[0].relforcerowsecurity)
+        create.push(`ALTER TABLE ${name} FORCE ROW LEVEL SECURITY`);
+    const pols = await c.query(`SELECT policyname, permissive, cmd, roles::text[] AS roles, qual, with_check FROM pg_policies WHERE schemaname = $1 AND tablename = $2`, [t.schema, t.name]);
+    for (const p of pols.rows) {
+        const roles = p.roles.map((r) => (r === "public" ? "public" : q(r))).join(", ");
+        create.push(`CREATE POLICY ${q(p.policyname)} ON ${name} AS ${p.permissive} FOR ${p.cmd} TO ${roles}` +
+            (p.qual ? ` USING (${p.qual})` : "") +
+            (p.with_check ? ` WITH CHECK (${p.with_check})` : ""));
+    }
+    // Supabase's API reaches tables through grants to anon and authenticated.
+    const grants = await c.query(`SELECT CASE WHEN g.grantee = 0 THEN 'PUBLIC' ELSE quote_ident(pg_get_userbyid(g.grantee)) END AS who, g.privilege_type AS priv
+     FROM pg_class c, aclexplode(c.relacl) g WHERE c.oid = $1 AND g.grantee <> c.relowner`, [t.oid]);
+    for (const g of grants.rows)
+        create.push(`GRANT ${g.priv} ON ${name} TO ${g.who}`);
+    const trig = await c.query(`SELECT pg_get_triggerdef(oid) AS def FROM pg_trigger WHERE tgrelid = $1 AND NOT tgisinternal`, [t.oid]);
+    return { schema: t.schema, name: t.name, shape: await shapeOf(c, t.oid), create, triggers: trig.rows.map((x) => x.def), fks, seqs: seqValues };
+}
+// The same rows in any order give the same fingerprint.
+async function fingerprint(c, table) {
+    const r = await c.query(`SELECT md5(coalesce(string_agg(h, '' ORDER BY h), '')) AS s FROM (SELECT md5(t::text) AS h FROM ${table} t) x`);
+    return r.rows[0].s;
+}
+export async function snapshotDb(actionId, url) {
+    return withClient(url, async (c) => {
+        const all = await tables(c);
+        await c.query(`CREATE SCHEMA IF NOT EXISTS ${q(SNAP_SCHEMA)}`);
+        // The migration history first, then the smallest tables: the most tables for the budget.
+        const order = [...all].sort((a, b) => Number(b.schema === MIGRATIONS) - Number(a.schema === MIGRATIONS) || a.bytes - b.bytes);
+        let spent = 0;
+        const copied = new Map();
+        let k = 0;
+        for (const t of order) {
+            if (t.schema !== MIGRATIONS && spent + t.bytes > budget())
+                continue;
+            spent += t.bytes;
+            const copy = `${actionId}_db${k++}`;
+            await c.query(`CREATE TABLE ${q(SNAP_SCHEMA)}.${q(copy)} AS TABLE ${full(t)}`);
+            copied.set(t.oid, { copy, sum: await fingerprint(c, full(t)) });
+        }
+        const out = [];
+        for (const t of all)
+            out.push({ ...(await describe(c, t)), copy: copied.get(t.oid)?.copy ?? null, sum: copied.get(t.oid)?.sum ?? null });
+        return { adapter: "db", url, tables: out };
+    });
+}
+async function insertable(c, table) {
+    const r = await c.query(`SELECT string_agg(quote_ident(attname), ', ' ORDER BY attnum) AS cols FROM pg_attribute
+     WHERE attrelid = to_regclass($1) AND attnum > 0 AND NOT attisdropped AND attgenerated = ''`, [table]);
+    return r.rows[0].cols;
+}
+async function putRows(c, t) {
+    const cols = await insertable(c, full(t));
+    const r = await c.query(`INSERT INTO ${full(t)} (${cols}) OVERRIDING SYSTEM VALUE SELECT ${cols} FROM ${q(SNAP_SCHEMA)}.${q(t.copy)}`);
+    return r.rowCount ?? 0;
+}
+const label = (t) => (t.schema === "public" ? t.name : `${t.schema}.${t.name}`);
+export async function undoDb(url, u) {
+    return withClient(url, async (c) => {
+        const log = [];
+        await c.query("BEGIN");
+        try {
+            const now = new Map((await tables(c)).map((t) => [`${t.schema}.${t.name}`, t]));
+            const was = new Map(u.tables.map((t) => [`${t.schema}.${t.name}`, t]));
+            // Made since: gone again.
+            for (const [key, t] of now) {
+                if (was.has(key))
+                    continue;
+                await c.query(`DROP TABLE IF EXISTS ${full(t)} CASCADE`);
+                log.push(`removed new table ${label(t)}`);
+            }
+            // Dropped or reshaped since: rebuilt as it was, rows and all.
+            const rebuilt = [];
+            const changed = [];
+            for (const [key, t] of was) {
+                const cur = now.get(key);
+                if (cur && (await shapeOf(c, cur.oid)) === t.shape) {
+                    if (t.copy && (await fingerprint(c, full(t))) !== t.sum)
+                        changed.push(t);
+                    continue;
+                }
+                if (cur)
+                    await c.query(`DROP TABLE ${full(t)} CASCADE`);
+                for (const sql of t.create)
+                    await c.query(sql);
+                rebuilt.push(t);
+            }
+            for (const t of rebuilt) {
+                const rows = t.copy ? await putRows(c, t) : 0;
+                log.push(t.copy
+                    ? `restored table ${label(t)} (${rows} rows)`
+                    : `restored table ${label(t)}, but not its rows: it was too big to copy`);
+            }
+            // Rows changed in a table that's still there: put the old ones back. Tables
+            // whose rows point at these come along, so no foreign key is left dangling.
+            const set = new Map(changed.map((t) => [`${t.schema}.${t.name}`, t]));
+            for (let grew = true; grew;) {
+                grew = false;
+                const refs = await c.query(`SELECT DISTINCT cn.nspname || '.' || cl.relname AS child, pn.nspname || '.' || pl.relname AS parent
+           FROM pg_constraint k JOIN pg_class cl ON cl.oid = k.conrelid JOIN pg_namespace cn ON cn.oid = cl.relnamespace
+           JOIN pg_class pl ON pl.oid = k.confrelid JOIN pg_namespace pn ON pn.oid = pl.relnamespace WHERE k.contype = 'f'`);
+                for (const r of refs.rows) {
+                    if (!set.has(r.parent) || set.has(r.child) || r.child === r.parent)
+                        continue;
+                    const child = was.get(r.child);
+                    if (!child?.copy)
+                        throw new Error(`couldn't put back the rows of ${label(set.get(r.parent))}: ${r.child} points at them and was too big to copy`);
+                    set.set(r.child, child);
+                    grew = true;
+                }
+            }
+            if (set.size) {
+                const list = [...set.values()];
+                for (const t of list)
+                    await c.query(`ALTER TABLE ${full(t)} DISABLE TRIGGER USER`);
+                await c.query(`TRUNCATE ${list.map(full).join(", ")}`);
+                // Parents before the tables that point at them.
+                const left = new Set(set.keys());
+                const deps = await c.query(`SELECT cn.nspname || '.' || cl.relname AS child, pn.nspname || '.' || pl.relname AS parent
+           FROM pg_constraint k JOIN pg_class cl ON cl.oid = k.conrelid JOIN pg_namespace cn ON cn.oid = cl.relnamespace
+           JOIN pg_class pl ON pl.oid = k.confrelid JOIN pg_namespace pn ON pn.oid = pl.relnamespace WHERE k.contype = 'f'`);
+                while (left.size) {
+                    const ready = [...left].filter((k) => !deps.rows.some((d) => d.child === k && d.parent !== k && left.has(d.parent)));
+                    const batch = ready.length ? ready : [...left];
+                    for (const key of batch) {
+                        const t = set.get(key);
+                        log.push(`restored ${await putRows(c, t)} rows in ${label(t)}`);
+                        left.delete(key);
+                    }
+                }
+                for (const t of list)
+                    await c.query(`ALTER TABLE ${full(t)} ENABLE TRIGGER USER`);
+            }
+            // Triggers on rebuilt tables once their rows are in, then every foreign key a drop took with it.
+            for (const t of rebuilt)
+                for (const sql of t.triggers)
+                    await c.query(sql);
+            for (const t of u.tables) {
+                for (const fk of t.fks) {
+                    const has = await c.query(`SELECT 1 FROM pg_constraint WHERE conrelid = to_regclass($1) AND conname = $2`, [full(t), fk.name]);
+                    if (has.rowCount === 0)
+                        await c.query(fk.sql);
+                }
+            }
+            // Counters, so new rows don't collide with restored ones.
+            for (const t of [...rebuilt, ...set.values()]) {
+                for (const s of t.seqs)
+                    await c.query(`SELECT setval($1, $2::bigint, $3)`, [s.name, s.value, s.called]);
+            }
+            await c.query("COMMIT");
+        }
+        catch (err) {
+            await c.query("ROLLBACK");
+            throw err;
+        }
+        await dropCopies(c, u);
+        return log.length ? log.join("\n") : "nothing had changed in the database";
+    });
+}
+async function dropCopies(c, u) {
+    for (const t of u.tables)
+        if (t.copy)
+            await c.query(`DROP TABLE IF EXISTS ${q(SNAP_SCHEMA)}.${q(t.copy)}`);
+}
+export async function discardDb(u) {
+    await withClient(u.url, (c) => dropCopies(c, u)).catch(() => { });
+}

package/dist/check.js

@@ -7,6 +7,7 @@ import { configServers, projectUses } from "./connect.js";
 import { supabaseProjects } from "./supabase.js";
 import { watchRules } from "./watch.js";
 import { dim, pink, white, width, wrap } from "./look.js";
+import { DEFAULT_KEY, keyLabel, undoKeys } from "./keys.js";
 const WRAPPED = /(^|[/\s])(backstep|cli\.[jt]s) wrap\b/;
 const SUPABASE = /supabase/i;
 const FIREBASE = /firebase|firestore/i;
@@ -83,7 +84,7 @@ export function printCheck(c, bs = "backstep") {
     const supabase = c.items.find((i) => SUPABASE.test(i.name));
     const supabaseLeft = supabase?.level === "connect" || c.suggest.some((s) => s.title === "Connect Supabase");
     const other = [...new Set(c.items.filter((i) => i.level === "recorded").map((i) => i.name))];
-    console.log(`\n  ${white("What ctrl+z can undo")}`);
+    console.log(`\n  ${white(`What ${(undoKeys().length ? undoKeys() : [DEFAULT_KEY]).map(keyLabel).join(" or ")} can undo`)}`);
     console.log(`    ${pink("✓")} Files Claude edits and commands it runs`);
     console.log(`    ${pink("✓")} Code Claude pushes to GitHub ${dim("(automatic, nothing to connect)")}`);
     for (const n of undoable)

package/dist/cli.js

@@ -4,12 +4,14 @@ import { fileURLToPath } from "node:url";
 import { runProxy } from "./proxy.js";
 import { startUi } from "./ui/server.js";
 import { Store, snapshotDir } from "./store.js";
-import { undoAction, undoRun, undoSince } from "./undo.js";
+import { pruneDatabaseCopies, undoAction, undoRun, undoSince } from "./undo.js";
 import { snapshotPaths } from "./adapters/fs.js";
 import { notePushed, snapshotTree } from "./adapters/tree.js";
 import { revertPush } from "./push.js";
+import { snapshotDb } from "./adapters/dbsnap.js";
+import { projectDatabases } from "./connect.js";
 const PUSH = /\bgit\b[^;&|]*\bpush\b/;
-import { classifyShell } from "./shell.js";
+import { classifyShell, supabaseTarget, touchesDatabase } from "./shell.js";
 import { watchEnd, watchStart } from "./watch.js";
 import { sendActive } from "./telemetry.js";
 import { readFileSync, rmSync } from "node:fs";
@@ -20,6 +22,7 @@ import { disconnectSupabase, dismissSupabase } from "./supabase.js";
 import { connect } from "./connect.js";
 import { check, printCheck } from "./check.js";
 import { logo } from "./look.js";
+import { keyLabel, setUndoKey, undoKeys } from "./keys.js";
 import { checkUpdate, runUpdate, skipVersion } from "./update.js";
 import { askConnectionString } from "./setup.js";
 // Header values can name env vars, so tokens don't have to sit in agent config files.
@@ -58,6 +61,7 @@ const HELP = `backstep: undo for everything your agents touch
                                Supabase from the project's .env files or local database (or the
                                connection string you give), Firebase by adding its MCP server.
                                In Claude Code you can just ask: "connect Backstep to my Supabase"
+  backstep key [<key>]         show the key that undoes Claude's last turn, or change it (e.g. backstep key ctrl+u)
   backstep update               install the newest version (Claude Code offers this as a session starts)
   backstep status [--json]     what Backstep can and can't undo for each service Claude Code reaches,
                                and what to connect next
@@ -210,6 +214,26 @@ async function main() {
         }
         return;
     }
+    // The undo key: `backstep key` shows it, `backstep key ctrl+u` changes it (what Claude runs when asked).
+    if (cmd === "key") {
+        const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { json: { type: "boolean", default: false } } });
+        if (!positionals[0]) {
+            const keys = undoKeys();
+            console.log(values.json ? JSON.stringify({ key: keys[0] ?? null, keys }) : keys.length ? `Undo is ${keys.map(keyLabel).join(" or ")}.` : "No undo key is bound. Run: backstep key ctrl+z");
+            return;
+        }
+        try {
+            const r = setUndoKey(positionals.join(" "));
+            console.log(values.json ? JSON.stringify({ ok: true, ...r }) : `Undo is now ${r.keys.map(keyLabel).join(" or ")}${r.previous && !r.keys.includes(r.previous) ? ` (was ${keyLabel(r.previous)})` : ""}.`);
+        }
+        catch (err) {
+            if (!values.json)
+                throw err;
+            console.log(JSON.stringify({ ok: false, detail: err instanceof Error ? err.message : String(err) }));
+            process.exitCode = 1;
+        }
+        return;
+    }
     // Run by the Claude Code mod as a session starts: is there a newer Backstep?
     if (cmd === "update-check") {
         console.log(JSON.stringify(await checkUpdate()));
@@ -317,12 +341,35 @@ async function main() {
         });
         // Outbound commands still get a snapshot: whatever they change locally can come back.
         // A push also notes where the remote branches stood, so undo can take it back there too.
-        const undo = snapshotTree(a.id, values.cwd ?? process.cwd(), { pushes: PUSH.test(command) });
+        const cwd = values.cwd ?? process.cwd();
+        const tree = snapshotTree(a.id, cwd, { pushes: PUSH.test(command) });
+        // A migration, reset, seed or raw SQL: the connected databases it could change are noted too.
+        const dbs = [];
+        const missed = [];
+        if (touchesDatabase(command)) {
+            for (const url of await projectDatabases(cwd, supabaseTarget(command))) {
+                try {
+                    dbs.push(await snapshotDb(a.id, url));
+                }
+                catch (err) {
+                    missed.push(err instanceof Error ? err.message : String(err));
+                }
+            }
+        }
+        const undo = tree ? { ...tree, ...(dbs.length ? { dbs } : {}) } : dbs.length ? { adapter: "dbs", dbs } : null;
         if (undo)
             store.updateAction(a.id, { undo: JSON.stringify(undo) });
-        else if (plan.kind !== "outbound")
+        // With its database saved, a command that reaches it is no longer lost to undo.
+        const kind = plan.kind === "outbound" && dbs.length && plan.reason === "changes a database directly" ? "write" : plan.kind;
+        if (kind !== plan.kind)
+            store.updateAction(a.id, { kind: "reversible", reason: null });
+        if (!undo && kind !== "outbound")
             store.updateAction(a.id, { kind: "write", reason: "project too large to snapshot" });
-        console.log(JSON.stringify({ kind: plan.kind, reason: plan.reason, id: a.id, undoable: undo !== null }));
+        if (missed.length)
+            store.updateAction(a.id, { reason: `couldn't save the database first: ${missed[0]}` });
+        if (dbs.length)
+            await pruneDatabaseCopies(store).catch(() => { });
+        console.log(JSON.stringify({ kind, reason: kind === plan.kind ? plan.reason : undefined, id: a.id, undoable: undo !== null, db: dbs.length }));
         return;
     }
     // After a shell command that pushed: notes what it sent (run by the Claude Code mod).

package/dist/connect.js

@@ -12,7 +12,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { claudeConfigFile, wrapServers } from "./servers.js";
-import { connectSupabase, hasSavedToken, LOCAL, mintSupabase, projectRef, saveSupabaseToken, supabaseDismissed, supabaseProjects, supabaseToken } from "./supabase.js";
+import { connectSupabase, hasSavedToken, LOCAL, mintSupabase, projectRef, saveSupabaseToken, supabaseDb, supabaseDismissed, supabaseProjects, supabaseToken, supabaseUrl, } from "./supabase.js";
 const ENV_FILES = [".env", ".env.local", ".env.development", ".env.development.local"];
 const PG = /^postgres(ql)?:\/\//;
 const FIREBASE_SERVER = ["npx", "-y", "firebase-tools@latest", "mcp"];
@@ -105,6 +105,23 @@ function linkedRef(dir) {
     }
     return undefined;
 }
+// The connected databases a command in this folder could change: only ones the
+// person connected, so a database is never touched without their say.
+export async function projectDatabases(dir, target) {
+    const out = [];
+    const ref = linkedRef(dir);
+    if (target !== "local" && ref && supabaseProjects().includes(ref)) {
+        const url = await supabaseUrl(ref);
+        if (url)
+            out.push(url);
+    }
+    if (target !== "hosted" && projectUses(dir).supabase) {
+        const local = supabaseDb(LOCAL);
+        if (local)
+            out.push(local);
+    }
+    return out;
+}
 // Signed in to Supabase: this folder's project connects now, the rest as Claude uses them.
 async function signedIn(dir, token, ref, isNew) {
     const project = ref ?? linkedRef(dir);

package/dist/keys.js

@@ -0,0 +1,88 @@
+// The key that undoes Claude's last turn, in Claude Code's ~/.claude/keybindings.json.
+// The mod's undo button borrows a keybinding action only the diff panel uses
+// (mod buttons can't have actions of their own yet), and whatever key is bound
+// to it, in Global and Chat, presses the button. ctrl+z by default; the person
+// can ask Claude for another, which runs `backstep key <key>`.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const UNDO_ACTION = "app:cycleDiffBase";
+export const DEFAULT_KEY = "ctrl+z";
+// A Mac gets ⌘Z too, where the terminal passes it on (Ghostty, Kitty, WezTerm,
+// Claude Code's desktop app); Terminal.app and iTerm2 keep ⌘Z for their own
+// Edit menu, so ctrl+z stays bound alongside it.
+export const defaultKeys = () => (process.platform === "darwin" ? ["cmd+z", DEFAULT_KEY] : [DEFAULT_KEY]);
+const CONTEXTS = ["Global", "Chat"];
+// Claude Code never hands these to anything else.
+const RESERVED = new Set(["ctrl+c", "ctrl+d", "ctrl+m", "ctrl+i", "ctrl+h", "ctrl+[", "ctrl+\\"]);
+const MODIFIERS = new Set(["ctrl", "control", "shift", "alt", "opt", "option", "meta", "cmd", "command", "super", "win"]);
+const file = () => join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), "keybindings.json");
+function load() {
+    if (!existsSync(file()))
+        return { $schema: "https://www.schemastore.org/claude-code-keybindings.json", $docs: "https://code.claude.com/docs/en/keybindings" };
+    return JSON.parse(readFileSync(file(), "utf8"));
+}
+// Every key bound to undo now; empty when none is.
+export function undoKeys() {
+    try {
+        const block = load().bindings?.find((b) => b.context === "Global");
+        return Object.entries(block?.bindings ?? {}).filter(([, a]) => a === UNDO_ACTION).map(([k]) => k);
+    }
+    catch {
+        return [];
+    }
+}
+export const undoKey = () => undoKeys()[0] ?? null;
+// "Ctrl + U" → "ctrl+u". Throws with a reason a person can act on.
+export function normalizeKey(raw) {
+    const key = raw.trim().toLowerCase().replace(/^⌘\s*\+?\s*/, "cmd+").replace(/\s*\+\s*/g, "+").replace(/^control\+/, "ctrl+").replace(/^(option|opt|alt)\+/, "meta+").replace(/^command\+/, "cmd+");
+    const parts = key.split("+");
+    const last = parts.at(-1) ?? "";
+    if (!last || parts.slice(0, -1).some((m) => !MODIFIERS.has(m)))
+        throw new Error(`"${raw}" isn't a key Claude Code understands. Try something like ctrl+u or meta+z`);
+    if (parts.length === 1)
+        throw new Error(`"${raw}" on its own would type a letter. Use a modifier, like ctrl+${last}`);
+    if (RESERVED.has(key))
+        throw new Error(`Claude Code keeps ${key} for itself. Pick another, like ctrl+u`);
+    return key;
+}
+// Binds undo to `keys` (one, or several) and unbinds the old ones. Refuses a key that does something else, unless it was undo's.
+export function setUndoKey(raw) {
+    const keys = (Array.isArray(raw) ? raw : raw.split(/\s*(?:,|\s(?:or|and)\s)\s*/)).filter(Boolean).map(normalizeKey);
+    const key = keys[0];
+    if (!key)
+        throw new Error("give a key, like ctrl+u");
+    let config;
+    try {
+        config = load();
+    }
+    catch {
+        throw new Error(`couldn't read ${file()}. Add "${key}": "${UNDO_ACTION}" under Global and Chat by hand`);
+    }
+    config.bindings ??= [];
+    const previous = undoKey();
+    for (const context of CONTEXTS) {
+        for (const k of keys) {
+            const taken = config.bindings.find((b) => b.context === context)?.bindings[k];
+            if (taken && taken !== UNDO_ACTION)
+                throw new Error(`${k} already does ${taken} in Claude Code. Pick another key`);
+        }
+    }
+    for (const context of CONTEXTS) {
+        let block = config.bindings.find((b) => b.context === context);
+        if (!block)
+            config.bindings.push((block = { context, bindings: {} }));
+        for (const [k, a] of Object.entries(block.bindings))
+            if (a === UNDO_ACTION)
+                delete block.bindings[k];
+        for (const k of keys)
+            block.bindings[k] = UNDO_ACTION;
+    }
+    mkdirSync(join(file(), ".."), { recursive: true });
+    writeFileSync(file(), JSON.stringify(config, null, 2) + "\n");
+    return { key, keys, previous };
+}
+// How a key reads on screen: cmd+z → ⌘Z.
+export function keyLabel(k) {
+    return k.startsWith("cmd+") ? `⌘${k.slice(4).toUpperCase()}` : k;
+}

package/dist/setup.js

@@ -1,9 +1,9 @@
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { cpSync, readFileSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homeDir } from "./store.js";
+import { defaultKeys, keyLabel, setUndoKey, undoKey, undoKeys } from "./keys.js";
 import { createInterface } from "node:readline/promises";
 import { autoWrap, wrapServers } from "./servers.js";
 import { check, printCheck } from "./check.js";
@@ -11,9 +11,6 @@ import { dim, logo, pink, white, width, wrap } from "./look.js";
 import { sendInstall, telemetryOn } from "./telemetry.js";
 // Both src/ and dist/ sit one level below the package root, next to mod/.
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
-const UNDO_KEY = "ctrl+z";
-// The mod's undo button borrows this action; see mod/hooks/register.tsx.
-const UNDO_ACTION = "app:cycleDiffBase";
 function run(cmd, args) {
     const r = spawnSync(cmd, args, { encoding: "utf8" });
     return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim(), missing: r.error !== undefined };
@@ -32,34 +29,17 @@ function keepCopy() {
     cpSync(dirname(ROOT), modules, { recursive: true });
     return { root: join(modules, "backstep"), onPath: false };
 }
+// Keeps a key the person picked; on a first install binds ⌘Z and ctrl+z on a Mac, ctrl+z elsewhere.
 function bindUndoKey() {
-    const dir = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
-    const file = join(dir, "keybindings.json");
-    let config = {
-        $schema: "https://www.schemastore.org/claude-code-keybindings.json",
-        $docs: "https://code.claude.com/docs/en/keybindings",
-    };
-    if (existsSync(file)) {
-        try {
-            config = JSON.parse(readFileSync(file, "utf8"));
-        }
-        catch {
-            return `couldn't read ${file}, so ${UNDO_KEY} isn't bound. Add "${UNDO_KEY}": "${UNDO_ACTION}" under Global and Chat.`;
-        }
+    if (undoKey())
+        return "";
+    try {
+        setUndoKey(defaultKeys());
+        return "";
     }
-    config.bindings ??= [];
-    for (const context of ["Global", "Chat"]) {
-        let block = config.bindings.find((b) => b.context === context);
-        if (!block)
-            config.bindings.push((block = { context, bindings: {} }));
-        const taken = block.bindings[UNDO_KEY];
-        if (taken && taken !== UNDO_ACTION)
-            return `${UNDO_KEY} is already bound to ${taken} in ${file}; left it alone.`;
-        block.bindings[UNDO_KEY] = UNDO_ACTION;
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
     }
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
-    return "";
 }
 const WHERE = `In Supabase, open your project, press Connect at the top, and copy the URI under
 "Direct connection" (or "Session pooler" if your network has no IPv6). Put your
@@ -107,7 +87,9 @@ export async function setup() {
     autoWrap(true);
     wrapServers(cli);
     // What's covered and what isn't, said once here and kept up to date by `backstep status`.
-    console.log(`\n  ${pink("✓")} ${white("Backstep is ready.")} Restart Claude Code, then press ${white(UNDO_KEY)} after any turn to undo it.`);
+    const key = (undoKeys().length ? undoKeys() : defaultKeys()).map(keyLabel).join(" or ");
+    console.log(`\n  ${pink("✓")} ${white("Backstep is ready.")} Restart Claude Code, then press ${white(key)} after any turn to undo it.`);
+    console.log(dim(`    Want a different key? Just ask Claude: "change my Backstep undo key to ctrl+u"`));
     printCheck(check(process.cwd()), bs);
     if (telemetryOn()) {
         console.log(dim("  Sends an anonymous install count. Turn it off with BACKSTEP_TELEMETRY=0.\n"));

package/dist/shell.js

@@ -110,3 +110,18 @@ export function classifyShell(command) {
         return { kind: "read" };
     return { kind: "write" };
 }
+// Commands that change a database through its own tools rather than Claude's:
+// migrations, resets, seeds and raw SQL.
+const DATABASE = /(^|[\s;&|(])(npx\s+|pnpm\s+(dlx\s+)?|bunx\s+|yarn\s+)?(supabase\s+(db|migration|seed)\b|psql\b|pg_restore\b|prisma\s+(migrate|db)\b|drizzle-kit\s+(push|migrate)\b|knex\s+(migrate|seed)|sequelize(-cli)?\s+db:|typeorm\s+(migration|schema)|node-pg-migrate\b|dbmate\b|goose\b|sqlx\s+(migrate|database)\b|alembic\b|(rails|rake)\s+db:|python3?\s+manage\.py\s+(migrate|flush|loaddata)\b)/;
+export function touchesDatabase(command) {
+    return DATABASE.test(command);
+}
+// Which of a project's databases a Supabase command aims at: `db push` and
+// --linked mean the hosted project, the rest default to the local one.
+export function supabaseTarget(command) {
+    if (!/\bsupabase\s+(db|migration|seed)\b/.test(command))
+        return "both";
+    if (/--local\b/.test(command))
+        return "local";
+    return /--linked\b|--db-url\b|\bdb\s+push\b/.test(command) ? "hosted" : "local";
+}

package/dist/store.js

@@ -114,6 +114,12 @@ export class Store {
         const r = this.db.prepare("UPDATE actions SET status = ? WHERE id = ? AND status = ?").run(to, id, from);
         return r.changes === 1;
     }
+    // Actions still holding a copy of a database, newest first.
+    databaseCopies() {
+        return this.db
+            .prepare(`SELECT * FROM actions WHERE undo LIKE '%"adapter":"db"%' AND status IN ('ok', 'error') ORDER BY created_at DESC`)
+            .all();
+    }
     getAction(id) {
         return this.db.prepare("SELECT * FROM actions WHERE id = ?").get(id);
     }

package/dist/undo.js

@@ -3,18 +3,45 @@ import { rmSync } from "node:fs";
 import { undoPaths } from "./adapters/fs.js";
 import { undoSql } from "./adapters/postgres.js";
 import { undoTree } from "./adapters/tree.js";
+import { discardDb, undoDb } from "./adapters/dbsnap.js";
 import { snapshotDir } from "./store.js";
 import { dbKey, freshUrl } from "./supabase.js";
 const INVERSE_TIMEOUT_MS = 20_000;
+// Database copies sit in the person's own database, so only the newest few per
+// database are kept; older commands keep their file undo but not their database undo.
+const KEEP_DB_COPIES = 10;
+export async function pruneDatabaseCopies(store) {
+    const seen = new Map();
+    for (const a of store.databaseCopies()) {
+        const u = JSON.parse(a.undo);
+        const keep = [];
+        for (const d of u.dbs ?? []) {
+            const k = dbKey(d.url);
+            const n = (seen.get(k) ?? 0) + 1;
+            seen.set(k, n);
+            if (n <= KEEP_DB_COPIES)
+                keep.push(d);
+            else
+                await discardDb({ ...d, url: await freshUrl(d.url) });
+        }
+        if (keep.length === (u.dbs ?? []).length)
+            continue;
+        const next = u.adapter === "dbs" ? (keep.length ? { ...u, dbs: keep } : null) : { ...u, dbs: keep.length ? keep : undefined };
+        store.updateAction(a.id, { undo: next ? JSON.stringify(next) : null, ...(next ? {} : { kind: "write", reason: "its database copy was cleared to save space" }) });
+    }
+}
 function resources(store, a) {
     const u = a.undo ? JSON.parse(a.undo) : null;
     if (!u)
         return new Set();
     if (u.adapter === "fs")
         return new Set(u.entries.map((e) => `fs:${e.path}`));
-    // A project snapshot rewinds every file under its folder.
+    // A project snapshot rewinds every file under its folder, and any whole database saved with it.
+    const whole = (dbs = []) => dbs.map((d) => `pgdb:${dbKey(d.url)}`);
     if (u.adapter === "tree")
-        return new Set([`fs:${u.root}`]);
+        return new Set([`fs:${u.root}`, ...whole(u.dbs)]);
+    if (u.adapter === "dbs")
+        return new Set(whole(u.dbs));
     // An opposite tool call doesn't rewind shared state, so it never conflicts.
     if (u.adapter === "inverse" || u.adapter === "engine")
         return new Set();
@@ -22,7 +49,7 @@ function resources(store, a) {
     const url = u.url ?? store.getRun(a.run_id)?.pg_url;
     const db = url ? dbKey(url) : a.run_id;
     const pgKey = (t) => `pg:${db}:${t.schema}.${t.name}`;
-    return new Set([...u.snapshots, ...u.trashed, ...u.created].map(pgKey));
+    return new Set([...u.snapshots, ...u.trashed, ...u.created].map(pgKey).concat(url ? [`pgdb:${dbKey(url)}`] : []));
 }
 // Same resource, or a file inside a folder that's rewound whole.
 function overlaps(a, b) {
@@ -102,8 +129,14 @@ async function undoOne(store, a, opts = {}) {
         if (u.adapter === "fs") {
             detail = undoPaths(u);
         }
-        else if (u.adapter === "tree") {
-            detail = undoTree(u, a.id);
+        else if (u.adapter === "tree" || u.adapter === "dbs") {
+            // The databases first: their undo is one transaction each, so a failure leaves everything as it was.
+            const lines = [];
+            for (const d of u.dbs ?? [])
+                lines.push(await undoDb(await freshUrl(d.url), d));
+            if (u.adapter === "tree")
+                lines.unshift(undoTree(u, a.id));
+            detail = lines.filter((l) => !/^nothing had changed/.test(l)).join("\n") || lines[0];
         }
         else {
             const url = u.url ?? store.getRun(a.run_id)?.pg_url;

package/mod/hooks/register.test.tsx

@@ -65,6 +65,7 @@ test('pressing undo rewinds the turn and tells Claude on the next prompt', { opt
   await $.tool.call({ tool: 'Edit', file_path: '/repo/src/a.ts', old_string: 'a', new_string: 'b' })
 
   const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
+  await ui.press({ key: 'undo' })
   const pressed = ui.press({ key: 'undo' })
   await clock.settle()
   expect((await ui.find({ type: 'Text', text: /Rewinding/ }))?.text).toBeTruthy()
@@ -77,7 +78,7 @@ test('pressing undo rewinds the turn and tells Claude on the next prompt', { opt
 
   // The band folds away, and with the turn undone nothing is left to offer.
   await clock.advance(5000)
-  expect(await ui.find({ type: 'Button', key: 'undo' })).toBeFalsy()
+  expect(await ui.find({ type: 'Text', text: /nothing to undo yet/ })).toBeTruthy()
   await ui.unmount()
 
   await $.prompt.submit({ text: 'try again', wait: false, origin: { kind: 'composer' } })
@@ -104,6 +105,7 @@ test('a change that cannot be undone stops the rewind and says so', { options: {
   await $.tool.call({ tool: 'mcp__db__query', sql: 'update t set x = 1' } as never)
 
   const ui = await $.ui.mount({ ...BAND, surface: 'desktop' })
+  await ui.press({ key: 'undo' })
   const pressed = ui.press({ key: 'undo' })
   await clock.advance(1000)
   await pressed
@@ -117,14 +119,21 @@ test('a change that cannot be undone stops the rewind and says so', { options: {
   expect(prompts).toHaveLength(1)
 })
 
-test('with nothing to undo the band leaves the space to the engine', async ($, on) => {
+test('with nothing to undo the band still holds the key, so ctrl+z never suspends Claude Code', async ($, on) => {
   engine(on, { exitCode: 0, stdout: '[]' })
+  const toasts: string[] = []
+  on('ui.toast', (_, e) => {
+    toasts.push(e.text)
+    return { value: undefined }
+  })
 
   await $.prompt.submit({ text: 'hi', wait: false, origin: { kind: 'composer' } })
   await $.tool.call({ tool: 'Bash', command: 'ls' })
 
   const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
-  expect((await ui.find({ type: 'Text' }))?.text).toBe('engine')
+  expect((await ui.find({ type: 'Text', text: /nothing to undo yet/ }))).toBeTruthy()
+  await ui.press({ key: 'undo' })
+  expect(toasts[0]).toContain('Nothing to undo yet')
   await ui.unmount()
 })
 
@@ -181,9 +190,10 @@ test('servers added since setup are wrapped as a session starts', { options: { c
 
   await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
   await new Promise((r) => setTimeout(r, 10))
-  expect(tools).toEqual(['connect'])
+  expect(tools).toEqual(['connect', 'undo_key'])
   expect(logs[0]).toContain('Backstep connected')
   expect(runs).toEqual([
+    ['node', '--disable-warning=ExperimentalWarning', CLI, 'key', '--json'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'wrap-servers', '--project', '/repo', '--json'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'connect', '--dir', '/repo', '--json', '--auto'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'ping'],
@@ -248,6 +258,7 @@ test('a connector call with an undo rule is undone through Claude Code', { optio
 
   const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
   expect((await ui.find({ type: 'Text', text: /Last turn/ }))?.text).toContain('1 tool action')
+  await ui.press({ key: 'undo' })
   const pressed = ui.press({ key: 'undo' })
   await clock.advance(1000)
   await pressed
@@ -265,6 +276,7 @@ test('when the opposite call fails, the rewind says so', { options: { cli: CLI }
   await $.prompt.submit({ text: 'make a page', wait: false, origin: { kind: 'composer' } })
   await $.tool.call({ tool: 'mcp__claude_ai_Notion__create-page', title: 'Plan' } as never)
   const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
+  await ui.press({ key: 'undo' })
   const pressed = ui.press({ key: 'undo' })
   await clock.advance(1000)
   await pressed
@@ -424,6 +436,7 @@ test('after undoing a turn that pushed, Backstep asks and pushes the undo', { op
   expect(runs.at(-1)?.argv.slice(3)).toEqual(['shell-end', 'p1'])
 
   const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
+  await ui.press({ key: 'undo' })
   const pressed = ui.press({ key: 'undo' })
   await clock.advance(1000)
   await pressed
@@ -484,3 +497,70 @@ test('Skip this version stops asking about it, and Not now changes nothing', { o
   expect(runs.some((r) => r.slice(3).join(' ') === 'update --skip 0.2.0')).toBe(true)
   expect(runs.some((r) => r.includes('--version'))).toBe(false)
 })
+
+test('asking Claude to change the undo key rebinds it and relabels the band', { options: { cli: CLI } }, async ($, on) => {
+  const runs: string[][] = []
+  on('process.run', (_, e) => {
+    runs.push([...e.argv])
+    const stdout = e.argv.includes('key') ? JSON.stringify({ ok: true, key: 'ctrl+u', previous: 'ctrl+z' }) : '[]'
+    return { value: { exitCode: 0, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } }
+  })
+  on('ui.toast', () => ({ value: undefined }))
+  on('ui.render', ($, e) => {
+    const { Text } = $.ui.resolve(e)
+    return <Text>engine</Text>
+  })
+  const r = await $.tool.call({ tool: 'mcp__backstep__undo_key', key: 'Ctrl + U' } as never)
+  expect(runs[0].slice(3)).toEqual(['key', 'Ctrl + U', '--json'])
+  expect(r.result).toBe('Undo is now ctrl+u (it was ctrl+z). It works right away.')
+  const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
+  expect((await ui.find({ type: 'Button', key: 'undo' }))?.text).toBe('ctrl+u to undo')
+  await ui.unmount()
+})
+
+test('one press only asks; it lets go after a few seconds, or on cancel, and undoes nothing', { options: { cli: CLI } }, async ($, on) => {
+  const clock = mock.clock(on, { now: 5000 })
+  const { runs } = engine(on, { exitCode: 0, stdout: '[]' })
+
+  await $.prompt.submit({ text: 'fix it', wait: false, origin: { kind: 'composer' } })
+  await $.tool.call({ tool: 'Edit', file_path: '/repo/src/a.ts', old_string: 'a', new_string: 'b' })
+  const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
+
+  await ui.press({ key: 'undo' })
+  expect((await ui.find({ type: 'Text', text: /Undo Claude's last turn\?/ }))).toBeTruthy()
+  expect((await ui.find({ type: 'Button', key: 'undo' }))?.text).toBe('ctrl+z again to undo')
+  await clock.advance(6000)
+  expect((await ui.find({ type: 'Text', text: /Last turn/ }))).toBeTruthy()
+
+  await ui.press({ key: 'undo' })
+  await ui.press({ key: 'cancel' })
+  expect((await ui.find({ type: 'Text', text: /Last turn/ }))).toBeTruthy()
+  // A press after the question let go asks again rather than undoing.
+  await ui.press({ key: 'undo' })
+  expect(runs.some((r) => r.includes('undo'))).toBe(false)
+  await ui.unmount()
+})
+
+test('on a Mac the band names both keys', { options: { cli: CLI } }, async ($, on) => {
+  on('process.run', (_, e) => {
+    const stdout = e.argv.includes('key') ? JSON.stringify({ key: 'cmd+z', keys: ['cmd+z', 'ctrl+z'] }) : '[]'
+    return { value: { exitCode: 0, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } }
+  })
+  const logs: string[] = []
+  on('ui.log', (_, e) => {
+    logs.push(e.text)
+    return { value: undefined }
+  })
+  on('ui.toast', () => ({ value: undefined }))
+  on('tool.register', (_, e) => ({ value: { tool: `mcp__backstep__${e.name}` } }))
+  on('session.start', (_, e) => ({ cwd: e.cwd }))
+  on('ui.render', ($, e) => {
+    const { Text } = $.ui.resolve(e)
+    return <Text>engine</Text>
+  })
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  expect(logs[0]).toContain('press ⌘Z / ctrl+z to undo')
+  const ui = await $.ui.mount({ ...BAND, surface: 'terminal' })
+  expect((await ui.find({ type: 'Button', key: 'undo' }))?.text).toBe('⌘Z / ctrl+z to undo')
+  await ui.unmount()
+})

package/mod/hooks/register.tsx

@@ -12,6 +12,9 @@ import type { Rewind, RewindItem, Turn } from '../types'
 const turns = atom({ plugin: 'backstep', key: 'turns' } as const, [] as Turn[])
 const rewind = atom({ plugin: 'backstep', key: 'rewind' } as const, null as Rewind | null)
 const note = atom({ plugin: 'backstep', key: 'note' } as const, null as string | null)
+const armed = atom({ plugin: 'backstep', key: 'armed' } as const, null as number | null)
+// How long the "press again to undo" question waits before it lets go.
+const CONFIRM_MS = 5000
 
 // The engine has no keybinding actions of its own for plugins yet, so the undo
 // button borrows one that only the diff panel handles; ~/.claude/keybindings.json
@@ -80,6 +83,28 @@ async function offerPushUndo($: EngineInterface, outcomes: Outcome[]) {
   }
 }
 
+// The first press asks, right there above the prompt; a second press within a
+// few seconds undoes. A dialog would take the band off screen, and with it the
+// key, which would then suspend Claude Code in a terminal.
+async function pressUndo($: EngineInterface) {
+  if (await read($, rewind)) return
+  const target = (await read($, turns)).findLast(hasWork)
+  if (!target) {
+    $.ui.toast('Nothing to undo yet: Claude hasn\'t changed anything Backstep can take back.')
+    return
+  }
+  const at = await read($, armed)
+  const now = await $.clock.now()
+  if (at !== null && now - at < CONFIRM_MS) {
+    await update($, armed, () => null)
+    return undoLastTurn($)
+  }
+  await update($, armed, () => now)
+  $.clock.after(CONFIRM_MS, () => {
+    void update($, armed, (a) => (a === now ? null : a))
+  })
+}
+
 async function undoLastTurn($: EngineInterface) {
   if (await read($, rewind)) return
   const target = (await read($, turns)).findLast(hasWork)
@@ -162,7 +187,7 @@ async function undoLastTurn($: EngineInterface) {
   if (done) {
     const list = items.filter((i) => i.ok).map((i) => `- ${i.label}`).join('\n')
     await update($, note, () =>
-      `[Backstep] The user pressed undo (ctrl+z) on your previous turn. These changes were reverted:\n${list}\n` +
+      `[Backstep] The user pressed undo (${keysLabel()}) on your previous turn. These changes were reverted:\n${list}\n` +
         (lost ? `${plural(lost, 'action')} from that turn couldn't be undone (they reached outside this machine with no way back, or the project was too big to snapshot).\n` : '') +
         `Treat them as not having happened, re-read files before editing them, and don't redo them unless asked.`,
     )
@@ -250,6 +275,10 @@ type ShellPlan = { kind: 'read' | 'write' | 'outbound'; reason?: string; id?: st
 
 // Set from the plugin's options each time the module registers.
 let cli = 'backstep'
+// The keys bound to undo, read as a session starts and when the person changes them.
+let undoKeys = ['ctrl+z']
+const keyLabel = (k: string) => (k.startsWith('cmd+') ? `⌘${k.slice(4).toUpperCase()}` : k)
+const keysLabel = () => undoKeys.map(keyLabel).join(' / ')
 
 function backstep(args: string[]): string[] {
   return cli === 'backstep' ? ['backstep', ...args] : ['node', '--disable-warning=ExperimentalWarning', cli, ...args]
@@ -385,6 +414,39 @@ async function offerUpdate($: EngineInterface) {
   $.ui.toast(r.ok ? `Backstep ${r.detail}. Restart Claude Code to use it.` : `Backstep couldn't update: ${r.detail}. Try: npx backstep@latest setup`)
 }
 
+const KEY = 'mcp__backstep__undo_key'
+
+const KEY_TOOL = {
+  name: 'undo_key',
+  description:
+    "Change the key that undoes Claude's last turn with Backstep (⌘Z and ctrl+z on a Mac, ctrl+z elsewhere, unless the user changed it). " +
+    'Use it when the user asks to change, rebind or pick a different Backstep or undo shortcut. ' +
+    'Keys are written like ctrl+u, cmd+z (⌘ on a Mac; most Mac terminals keep ⌘ keys for themselves, so pair it with a ctrl key), meta+z (Option) or ctrl+shift+z. ' +
+    'Several keys can share undo: separate them with commas. It takes effect right away, no restart.',
+  inputSchema: {
+    type: 'object',
+    properties: { key: { type: 'string', description: 'the new key, like ctrl+u, or several separated by commas, like "cmd+z, ctrl+z"' } },
+    required: ['key'],
+  },
+}
+
+async function changeKey($: EngineInterface, key: string): Promise<string> {
+  const ran = await $.process
+    .run(backstep(['key', key, '--json']))
+    .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
+  let r: { ok?: boolean; key?: string; keys?: string[]; previous?: string | null; detail?: string } = {}
+  try {
+    r = JSON.parse(ran.stdout || '{}') as typeof r
+  } catch {
+    r = { ok: false, detail: ran.stderr.trim() || 'it failed' }
+  }
+  if (!r.ok || !r.key) return `Couldn't change the undo key: ${r.detail ?? 'it failed'}`
+  undoKeys = r.keys?.length ? r.keys : [r.key]
+  $.ui.toast(`Backstep: undo is now ${keysLabel()}.`)
+  const was = r.previous && !undoKeys.includes(r.previous) ? ` (it was ${keyLabel(r.previous)})` : ''
+  return `Undo is now ${keysLabel()}${was}. It works right away.`
+}
+
 const CONNECT = 'mcp__backstep__connect'
 
 const CONNECT_TOOL = {
@@ -435,9 +497,17 @@ export const register: Register = (on, options) => {
 
   on('session.start', async ($, e, next) => {
     await $.tool.register(CONNECT_TOOL)
+    await $.tool.register(KEY_TOOL)
     const r = await next(e)
+    const bound = await $.process.run(backstep(['key', '--json'])).catch(() => null)
+    try {
+      const keys = (JSON.parse(bound?.stdout || '{}') as { keys?: string[] }).keys
+      if (keys?.length) undoKeys = keys
+    } catch {
+      // keep the default
+    }
     // Said first thing, so nobody has to wonder whether it's running.
-    $.ui.log("✓ Backstep connected · press ctrl+z to undo Claude's last turn")
+    $.ui.log(`✓ Backstep connected · press ${keysLabel()} to undo Claude's last turn`)
     // In the background: a session never waits on either.
     void wrapNewServers($, e.cwd)
     // One question at a time: Supabase first, then any update.
@@ -458,11 +528,13 @@ export const register: Register = (on, options) => {
     return next({ ...e, context: [...(e.context ?? []), pending] })
   })
 
+  on('tool.call', { tool: KEY }, async ($, e) => ({ result: await changeKey($, String((e as { key?: unknown }).key ?? '')) }))
+
   on('tool.call', { tool: CONNECT }, async ($, e) => ({ result: await connectServices($, e as { service?: string; connection_string?: string; project_ref?: string }) }))
 
   on('tool.call', async ($, e, next) => {
     const tool = String(e.tool)
-    if (tool === CONNECT) return next(e)
+    if (tool === CONNECT || tool === KEY) return next(e)
     if (EDIT_TOOLS.has(tool)) {
       const input = e as { file_path?: string; notebook_path?: string }
       const path = input.file_path ?? input.notebook_path
@@ -485,7 +557,8 @@ export const register: Register = (on, options) => {
       const sid = await $.session.id()
       // Never blocks the command: if Backstep can't be reached it just won't be undoable.
       const ran = await $.process
-        .run(backstep(['shell', '--session', sid, '--cwd', cwd, '--', command]), { timeoutMs: 60_000 })
+        // A database command copies the database first, which takes longer on a big one.
+        .run(backstep(['shell', '--session', sid, '--cwd', cwd, '--', command]), { timeoutMs: 180_000 })
         .catch(() => null)
       let plan: ShellPlan | null = null
       try {
@@ -548,16 +621,32 @@ export const register: Register = (on, options) => {
       )
     }
 
-    // Idle: a quiet line naming what one press would take back. The button
-    // has to be on screen for the chord to reach it.
     const target = (await read($, turns)).findLast(hasWork)
-    if (!target) return next(e)
+    if (target && (await read($, armed)) !== null) {
+      return (
+        <Box>
+          <Text color="warning" bold>↺ Undo Claude's last turn? </Text>
+          <Text dimColor>{summary(target)}  </Text>
+          <Button key="undo" action={UNDO_ACTION} plain onPress={() => void pressUndo($)}>
+            {`${keysLabel()} again to undo`}
+          </Button>
+          <Text dimColor>  ·  </Text>
+          <Button key="cancel" plain dimColor onPress={() => void update($, armed, () => null)}>
+            cancel
+          </Button>
+        </Box>
+      )
+    }
+
+    // Idle: a quiet line naming what one press would take back. It's always
+    // there, because the button has to be on screen for the key to reach it;
+    // without it, ctrl+z falls through to the terminal and suspends Claude Code.
     return (
       <Box>
         <Text color="success">↺ </Text>
-        <Text dimColor>Last turn: {summary(target)}  </Text>
-        <Button key="undo" action={UNDO_ACTION} plain dimColor onPress={() => void undoLastTurn($)}>
-          ctrl+z to undo
+        <Text dimColor>{target ? `Last turn: ${summary(target)}  ` : 'Backstep is on · nothing to undo yet  '}</Text>
+        <Button key="undo" action={UNDO_ACTION} plain dimColor onPress={() => void pressUndo($)}>
+          {`${keysLabel()} to undo`}
         </Button>
       </Box>
     )

package/mod/types/index.d.ts

@@ -25,6 +25,7 @@ export type Rewind = {
 
 declare module 'claude-code' {
   interface PluginState {
-    backstep: { turns: Turn[]; rewind: Rewind | null; note: string | null }
+    // armed: when the undo key was first pressed; a second press within a few seconds undoes.
+    backstep: { turns: Turn[]; rewind: Rewind | null; note: string | null; armed: number | null }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
   "scripts": {
     "dev": "node src/cli.ts",