backstep 0.1.3 → 0.1.5

package/README.md

@@ -53,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 ctrl+z. 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/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

@@ -22,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.
@@ -60,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
@@ -212,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()));

package/dist/keys.js

@@ -0,0 +1,85 @@
+// 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";
+export const defaultKeys = () => [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; binds ctrl+z on a first install.
 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/update.js

@@ -51,17 +51,39 @@ export function skipVersion(v) {
     mkdirSync(homeDir(), { recursive: true });
     writeFileSync(file(), JSON.stringify({ ...settings(), skipVersion: v }, null, 2) + "\n");
 }
+// What went wrong, in a line a person can act on: npm's own reason, not its
+// pointer to a log file.
+export function npmReason(out) {
+    if (/ETARGET|notarget|No matching version/i.test(out))
+        return "npm hasn't finished publishing it yet. Try again in a few minutes";
+    if (/ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|network/i.test(out))
+        return "couldn't reach npm. Check your internet connection";
+    if (/EACCES|permission denied/i.test(out))
+        return "npm wasn't allowed to install it (a permissions problem with npm's global folder)";
+    const lines = out.split("\n").map((l) => l.trim()).filter((l) => l && !/complete log of this run|^npm (error|ERR!)\s*$/i.test(l));
+    return (lines.find((l) => /^backstep:/.test(l)) ?? lines.findLast((l) => /error/i.test(l)) ?? lines.at(-1) ?? "npx failed").replace(/^(backstep:|npm (error|ERR!))\s*/i, "");
+}
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 // The new version's setup puts its own copy in place, points Claude Code's mod
-// at it and re-wraps servers, exactly as a fresh install would.
-export function runUpdate(v) {
-    const r = spawnSync("npx", ["-y", `backstep@${v}`, "setup"], {
-        encoding: "utf8",
-        timeout: 5 * 60 * 1000,
-        env: { ...process.env, NO_COLOR: "1", BACKSTEP_TELEMETRY: "0" },
-        stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (r.status === 0)
-        return { ok: true, detail: `updated to ${v}` };
-    const why = `${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").filter(Boolean).at(-1) ?? "npx failed";
-    return { ok: false, detail: why.replace(/^backstep: /, "") };
+// at it and re-wraps servers, exactly as a fresh install would. npm is asked
+// online, never from its cache, which can be older than a version just
+// published; and asked again for a while if it still hasn't heard of it.
+export function runUpdate(v, tries = 4) {
+    let out = "";
+    for (let i = 0; i < tries; i++) {
+        if (i)
+            pause(15_000);
+        const r = spawnSync("npx", ["-y", "--prefer-online", `backstep@${v}`, "setup"], {
+            encoding: "utf8",
+            timeout: 5 * 60 * 1000,
+            env: { ...process.env, NO_COLOR: "1", BACKSTEP_TELEMETRY: "0" },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (r.status === 0)
+            return { ok: true, detail: `updated to ${v}` };
+        out = `${r.stderr ?? ""}\n${r.stdout ?? ""}`;
+        if (!/ETARGET|notarget|No matching version/i.test(out))
+            break;
+    }
+    return { ok: false, detail: npmReason(out) };
 }

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Press ctrl+z to rewind everything Claude did in its last turn: file edits, shell commands, and database and tool changes.",
   "types": "./types/index.d.ts",
   "userConfig": {

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]
@@ -374,7 +403,7 @@ async function offerUpdate($: EngineInterface) {
   if (answer !== UPDATE.yes) return
   $.ui.toast(`Updating Backstep to ${u.latest}…`)
   const done = await $.process
-    .run(backstep(['update', '--version', u.latest, '--json']), { timeoutMs: 300_000 })
+    .run(backstep(['update', '--version', u.latest, '--json']), { timeoutMs: 600_000 })
     .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
   let r: { ok: boolean; detail: string } = { ok: false, detail: (done.stderr || 'it failed').trim().split('\n').at(-1) ?? 'it failed' }
   try {
@@ -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 (ctrl+z 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
@@ -549,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,12 +1,12 @@
 {
   "name": "backstep",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Undo for everything your agents touch: an MCP proxy that makes agent actions reversible.",
   "scripts": {
     "dev": "node src/cli.ts",
     "ui": "node --disable-warning=ExperimentalWarning src/cli.ts ui",
     "demo": "node --disable-warning=ExperimentalWarning examples/demo-db.ts",
-    "build": "tsc -p tsconfig.json && cp src/ui/index.html dist/ui/index.html && chmod +x dist/cli.js",
+    "build": "tsc -p tsconfig.json && cp src/ui/index.html dist/ui/index.html && chmod +x dist/cli.js && node -e \"const f='mod/.claude-plugin/plugin.json',p=JSON.parse(require('fs').readFileSync(f));p.version=require('./package.json').version;require('fs').writeFileSync(f,JSON.stringify(p,null,2)+'\\\\n')\"",
     "test": "node --disable-warning=ExperimentalWarning --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },