backstep 0.1.16 → 0.1.17

package/README.md

@@ -25,10 +25,16 @@ Undo for everything your agents touch. Backstep sits between your agent (Claude
 npx backstep setup
 ```
 
-This installs Backstep, adds its Claude Code mod, binds **ctrl+u** to undo everything Claude did in its last turn, and puts the MCP servers you've already added to Claude Code behind Backstep, so their changes can be undone too. If you use Supabase, it asks for your database's connection string (Enter skips; you can ask Claude to connect it later). Restart Claude Code afterwards. Needs Node 22.13+ and Claude Code.
+This installs Backstep, adds its Claude Code mod, binds **ctrl+u** to undo everything Claude did in its last turn, and puts the MCP servers you've already added to Claude Code behind Backstep, so their changes can be undone too. Databases (Supabase, Postgres, Firebase) aren't touched at setup: the first time Claude goes to change one, Backstep asks whether to connect it. Restart Claude Code afterwards. Needs Node 22.13+ and Claude Code.
 
 Servers in a repo's shared `.mcp.json` that you've approved get a wrapped copy for that project only; the repo's file is never edited. Remote servers that Claude Code signs in to stay as they are, and the mod watches their calls instead. Servers you add later are wrapped the next time Claude Code starts. `backstep unwrap` puts every server back the way it was and stops new ones being wrapped.
 
+## Uninstall
+
+In Claude Code, type **/uninstall-backstep**, or just ask Claude to uninstall Backstep. From a terminal: `backstep uninstall` (or `npx backstep uninstall`).
+
+It asks first, then takes away everything Backstep set up: your MCP servers go back to their own commands, the database copies Backstep saved are dropped (and its `backstep` schema, only if that leaves it empty), the undo key comes out of Claude Code's keybindings, the plugin is removed, and `~/.backstep` (history, snapshots, saved connections) is deleted. Nothing you undid or kept changes. Restart Claude Code to finish.
+
 ## Try it
 
 ```sh
@@ -112,7 +118,7 @@ Everything is journaled to `~/.backstep/journal.db` (SQLite, mode 0600; override
 
 ## Telemetry
 
-`backstep setup` sends one anonymous `install` event, and Claude Code with the Backstep mod sends one `active` event a day. Each carries a random id made on your machine (`~/.backstep/install-id`), the Backstep version, your OS and CPU type, and the Node major version. Nothing else: no paths, commands, server names, IP-based location, or anything from the journal. The code is `src/telemetry.ts`.
+`backstep setup` sends one anonymous `install` event, Claude Code with the Backstep mod sends one `active` event a day, and `backstep uninstall` sends one `uninstall` event. Each carries a random id made on your machine (`~/.backstep/install-id`), the Backstep version, your OS and CPU type, and the Node major version. Nothing else: no paths, commands, server names, IP-based location, or anything from the journal. The code is `src/telemetry.ts`.
 
 Turn it off with `BACKSTEP_TELEMETRY=0`, or the standard `DO_NOT_TRACK=1`.
 

package/dist/adapters/dbsnap.js

@@ -263,3 +263,11 @@ async function dropCopies(c, u) {
 export async function discardDb(u) {
     await withClient(u.url, (c) => dropCopies(c, u)).catch(() => { });
 }
+// On uninstall, after every copy is dropped: removes Backstep's schema, but only
+// if it's empty (no CASCADE), so a schema of the project's own by that name is never touched.
+export async function dropSnapSchema(url) {
+    return withClient(url, async (c) => {
+        await c.query(`DROP SCHEMA IF EXISTS ${q(SNAP_SCHEMA)}`);
+        return true;
+    }).catch(() => false);
+}

package/dist/cli.js

@@ -88,6 +88,8 @@ const HELP = `backstep: undo for everything your agents touch
   backstep setup               install the Claude Code mod, bind ctrl+u to undo Claude's last turn,
                                and put your MCP servers behind Backstep
   backstep unwrap              take your MCP servers back out from behind Backstep
+  backstep uninstall [--yes]   remove Backstep and everything it set up (in Claude Code: /uninstall-backstep,
+                               or ask Claude to uninstall Backstep)
   backstep connect [supabase|firebase] [<access-token>|<connection-string>] [--project <ref>] [--dir <folder>] [--json]
                                connect what the project uses, so Claude's changes to it can be undone:
                                Supabase from the project's .env files or local database (or the
@@ -166,6 +168,36 @@ async function main() {
         await sendActive();
         return;
     }
+    if (cmd === "uninstall") {
+        const { values } = parseArgs({ args: rest, options: { yes: { type: "boolean", default: false }, json: { type: "boolean", default: false } } });
+        if (!values.yes) {
+            if (!process.stdin.isTTY)
+                throw new Error("run it with --yes to confirm: backstep uninstall --yes");
+            const { createInterface } = await import("node:readline/promises");
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = (await rl.question("This removes Backstep from this computer: your MCP servers go back to how they were, the undo key\n" +
+                "and the Claude Code plugin are removed, and Backstep's history and saved copies are deleted\n" +
+                "(nothing you undid or kept is changed). Remove Backstep? [y/N] ")).trim();
+            rl.close();
+            if (!/^y(es)?$/i.test(answer)) {
+                console.log("Kept Backstep.");
+                return;
+            }
+        }
+        const { uninstall } = await import("./uninstall.js");
+        const removed = await uninstall();
+        if (values.json) {
+            console.log(JSON.stringify(removed));
+        }
+        else {
+            for (const r of removed)
+                console.log(`  ${r.ok ? "✓" : "!"} ${r.step}: ${r.detail}`);
+            console.log(`\nBackstep is removed.${removed.every((r) => r.ok) ? "" : " The lines marked ! need a look."} Restart Claude Code to finish.`);
+        }
+        if (removed.some((r) => !r.ok))
+            process.exitCode = 1;
+        return;
+    }
     if (cmd === "unwrap") {
         autoWrap(false);
         const changes = unwrapServers();

package/dist/connect.js

@@ -354,26 +354,16 @@ async function supabase(dir, given, ref, interactive = false, auto = false) {
             `Or the database's connection string (${WHERE})${errors.length ? `. Tried the one in the project's settings: ${errors[0]}` : ""}`,
     };
 }
-// firebase-tools keeps its sign-in here once someone runs `firebase login`.
-function firebaseSignedIn() {
-    try {
-        const c = JSON.parse(read(join(homedir(), ".config", "configstore", "firebase-tools.json")));
-        return Boolean(c.tokens?.refresh_token);
-    }
-    catch {
-        return false;
-    }
-}
-// `auto`: on its own as a session starts, so a server is only added when it would work.
+// `auto`: as a session starts. Nothing is added then: like Supabase, Firebase is
+// only set up once Claude goes to change it and the person says Connect.
 function firebase(dir, cli, auto = false) {
     if (servers(dir).some((s) => /firebase|firestore/i.test(s))) {
         return { service: "firebase", state: "covered", detail: "Claude reaches Firebase through its MCP server, so its changes can be undone" };
     }
     if (!projectUses(dir).firebase)
         return { service: "firebase", state: "unused", detail: "this project doesn't use Firebase" };
-    if (auto && !firebaseSignedIn()) {
-        return { service: "firebase", state: "needs", detail: "sign in to Firebase once (run: npx firebase-tools login), and Backstep connects it by itself" };
-    }
+    if (auto)
+        return { service: "firebase", state: "unused", detail: "set up the first time Claude goes to change Firebase" };
     // For this project only, like `claude mcp add` without -s.
     const r = spawnSync("claude", ["mcp", "add", "firebase", "--", ...FIREBASE_SERVER], { cwd: dir, encoding: "utf8" });
     if (r.status !== 0) {

package/dist/keys.js

@@ -84,6 +84,24 @@ export function setUndoKey(raw) {
     writeFileSync(file(), JSON.stringify(config, null, 2) + "\n");
     return { key, keys, previous };
 }
+// On uninstall: takes every key bound to Backstep's undo back out. Returns the keys removed.
+export function removeUndoKeys() {
+    if (!existsSync(file()))
+        return [];
+    const config = load();
+    const removed = new Set();
+    for (const block of config.bindings ?? []) {
+        for (const [k, a] of Object.entries(block.bindings)) {
+            if (a === UNDO_ACTION) {
+                delete block.bindings[k];
+                removed.add(k);
+            }
+        }
+    }
+    if (removed.size)
+        writeFileSync(file(), JSON.stringify(config, null, 2) + "\n");
+    return [...removed];
+}
 // 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

@@ -78,6 +78,7 @@ export async function setup() {
     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+q"`));
+    console.log(dim(`    To remove Backstep, type /uninstall-backstep in Claude Code, or ask Claude to uninstall it.`));
     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/telemetry.js

@@ -63,6 +63,7 @@ async function send(event) {
     }
 }
 export const sendInstall = () => send("install");
+export const sendUninstall = () => send("uninstall");
 // At most once a day, as Claude Code starts with Backstep's mod.
 export async function sendActive() {
     if (!telemetryOn())

package/dist/uninstall.js

@@ -0,0 +1,105 @@
+// Takes Backstep off this computer: everything setup and use put in place, in
+// the order that never leaves something pointing at a Backstep that's gone.
+//   1. MCP servers wrapped behind Backstep get their own commands back
+//   2. the database copies Backstep made are dropped, and its schema if empty
+//   3. the undo key comes out of Claude Code's keybindings
+//   4. the Claude Code plugin and its source are removed
+//   5. ~/.backstep (history, snapshots, saved connections) is deleted
+//   6. the global npm package, when setup installed one
+import { spawnSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import { homeDir, Store } from "./store.js";
+import { unwrapServers } from "./servers.js";
+import { removeUndoKeys } from "./keys.js";
+import { discardDb, dropSnapSchema } from "./adapters/dbsnap.js";
+import { dbKey, freshUrl } from "./supabase.js";
+import { sendUninstall } from "./telemetry.js";
+const run = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return { ok: r.status === 0, missing: Boolean(r.error), out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+};
+const plural = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
+async function dropDatabaseCopies() {
+    if (!existsSync(homeDir()))
+        return null;
+    const store = new Store();
+    const urls = new Map();
+    let dropped = 0;
+    for (const a of store.databaseCopies()) {
+        const u = JSON.parse(a.undo);
+        for (const d of u.dbs ?? []) {
+            const url = await freshUrl(d.url).catch(() => d.url);
+            await discardDb({ ...d, url });
+            urls.set(dbKey(d.url), url);
+            dropped++;
+        }
+    }
+    if (urls.size === 0)
+        return null;
+    let schemas = 0;
+    for (const url of urls.values())
+        if (await dropSnapSchema(url))
+            schemas++;
+    return {
+        step: "database copies",
+        ok: schemas === urls.size,
+        detail: `dropped ${plural(dropped, "saved copy")} from ${plural(urls.size, "database")}` +
+            (schemas < urls.size ? `; couldn't reach ${urls.size - schemas} of them, so a "backstep" schema may be left there to drop by hand` : ""),
+    };
+}
+export async function uninstall() {
+    const out = [];
+    // Counted before anything is deleted (the install id lives in ~/.backstep).
+    await sendUninstall();
+    const servers = unwrapServers();
+    const restored = servers.filter((c) => c.done).length;
+    const kept = servers.filter((c) => !c.done && !/nothing to put back/.test(c.note));
+    if (servers.length) {
+        out.push({
+            step: "MCP servers",
+            ok: kept.length === 0,
+            detail: `gave ${plural(restored, "server")} back ${restored === 1 ? "its" : "their"} own command` +
+                (kept.length ? `; left ${kept.map((c) => `${c.name} (${c.note})`).join(", ")}` : ""),
+        });
+    }
+    try {
+        const db = await dropDatabaseCopies();
+        if (db)
+            out.push(db);
+    }
+    catch (err) {
+        out.push({ step: "database copies", ok: false, detail: err instanceof Error ? err.message : String(err) });
+    }
+    try {
+        const keys = removeUndoKeys();
+        if (keys.length)
+            out.push({ step: "undo key", ok: true, detail: `unbound ${keys.join(", ")}` });
+    }
+    catch (err) {
+        out.push({ step: "undo key", ok: false, detail: `couldn't edit Claude Code's keybindings: ${err instanceof Error ? err.message : String(err)}` });
+    }
+    const plugin = run("claude", ["plugin", "uninstall", "backstep@backstep"]);
+    const market = run("claude", ["plugin", "marketplace", "remove", "backstep"]);
+    if (plugin.missing) {
+        out.push({ step: "Claude Code plugin", ok: false, detail: "Claude Code isn't on the PATH: remove the plugin with /plugin inside Claude Code" });
+    }
+    else {
+        const gone = plugin.ok || /not (installed|found)/i.test(plugin.out);
+        out.push({ step: "Claude Code plugin", ok: gone, detail: gone ? `removed${market.ok ? ", with its source" : ""}` : plugin.out.split("\n").at(-1) ?? "failed" });
+    }
+    if (existsSync(homeDir())) {
+        try {
+            rmSync(homeDir(), { recursive: true, force: true });
+            out.push({ step: "Backstep's folder", ok: true, detail: `deleted ${homeDir()} (history, snapshots, saved connections)` });
+        }
+        catch (err) {
+            out.push({ step: "Backstep's folder", ok: false, detail: `couldn't delete ${homeDir()}: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    // Last: this may be the copy that's running.
+    if (run("npm", ["ls", "-g", "backstep", "--depth=0"]).ok) {
+        const npm = run("npm", ["uninstall", "-g", "backstep"]);
+        out.push({ step: "backstep command", ok: npm.ok, detail: npm.ok ? "removed the global npm package" : "run: npm uninstall -g backstep" });
+    }
+    return out;
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "backstep",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "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

@@ -235,14 +235,13 @@ 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', 'undo_key'])
+  expect(tools).toEqual(['connect', 'undo_key', 'uninstall'])
   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'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'status', '--quick', '--json', '--dir', '/repo'],
+    ['node', '--disable-warning=ExperimentalWarning', CLI, 'ping'],
     ['node', '--disable-warning=ExperimentalWarning', CLI, 'update-check'],
   ])
   expect(toasts.find((t) => t.includes('linear is now behind Backstep'))).toBeTruthy()
@@ -386,6 +385,8 @@ test('asking Claude to connect runs backstep connect, with the connection string
   expect(toasts).toHaveLength(1)
 })
 
+const settle = () => new Promise((r) => setTimeout(r, 20))
+
 // A project that uses Supabase, not connected: Backstep asks, and only the answer connects it.
 function supabaseProject(on: On, answer: string, connectResult: object) {
   const runs: string[][] = []
@@ -393,7 +394,11 @@ function supabaseProject(on: On, answer: string, connectResult: object) {
   const asked: string[] = []
   on('process.run', (_, e) => {
     runs.push([...e.argv])
-    const stdout = e.argv.includes('--auto')
+    const stdout = e.argv.includes('db-check')
+      ? JSON.stringify({ ask: '/repo', service: 'supabase' })
+      : e.argv.includes('shell')
+        ? JSON.stringify({ kind: 'write', undoable: true })
+        : e.argv.includes('--auto')
       ? JSON.stringify([{ service: 'supabase', state: 'ask', detail: "this project uses Supabase, but Backstep isn't connected to it" }])
       : e.argv.includes('status')
         ? JSON.stringify({ items: [], suggest: [] })
@@ -413,15 +418,32 @@ function supabaseProject(on: On, answer: string, connectResult: object) {
     return { result: { questions, answers: { [questions[0].question]: answer } } }
   })
   on('session.start', (_, e) => ({ cwd: e.cwd }))
+  on('session.cwd', () => ({ value: '/repo' }))
+  on('session.id', () => ({ value: 's1' }))
+  on('tool.call', () => ({ result: {} }))
   return { runs, toasts, asked }
 }
 
-const settle = () => new Promise((r) => setTimeout(r, 20))
+// Claude is about to change the database: the moment Backstep asks.
+async function changeDatabase($: Parameters<Parameters<typeof test>[2]>[0], on: On) {
+  on('ui.log', () => ({ value: undefined }))
+  mock.clock(on, { now: 5000 })
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  await settle()
+  await $.tool.call({ tool: 'Bash', command: 'supabase db push' })
+  await settle()
+}
 
-test('a Supabase project that is not connected is asked about, and Connect connects it', { options: { cli: CLI } }, async ($, on) => {
-  const { runs, toasts, asked } = supabaseProject(on, 'Connect', { service: 'supabase', state: 'connected', detail: 'connected project abc' })
+test('opening a session never asks about a database, even with Supabase projects below the folder', { options: { cli: CLI } }, async ($, on) => {
+  const { asked } = supabaseProject(on, 'Connect', {})
   await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
   await settle()
+  expect(asked).toHaveLength(0)
+})
+
+test('a Supabase project that is not connected is asked about when Claude goes to change it, and Connect connects it', { options: { cli: CLI } }, async ($, on) => {
+  const { runs, toasts, asked } = supabaseProject(on, 'Connect', { service: 'supabase', state: 'connected', detail: 'connected project abc' })
+  await changeDatabase($, on)
   expect(asked).toHaveLength(1)
   expect(runs.some((r) => r.slice(3).join(' ') === 'connect supabase --dir /repo --json')).toBe(true)
   expect(toasts.find((t) => t.includes('connected project abc'))).toBeTruthy()
@@ -429,15 +451,13 @@ test('a Supabase project that is not connected is asked about, and Connect conne
 
 test('Not now connects nothing', { options: { cli: CLI } }, async ($, on) => {
   const { runs } = supabaseProject(on, 'Not now', {})
-  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
-  await settle()
+  await changeDatabase($, on)
   expect(runs.filter((r) => r.includes('connect') && !r.includes('--auto'))).toHaveLength(0)
 })
 
 test("Don't ask for this project remembers it", { options: { cli: CLI } }, async ($, on) => {
   const { runs } = supabaseProject(on, "Don't ask for this project", {})
-  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
-  await settle()
+  await changeDatabase($, on)
   expect(runs.some((r) => r.slice(3).join(' ') === 'connect supabase --dir /repo --dismiss')).toBe(true)
 })
 
@@ -524,9 +544,22 @@ function updates(on: On, answer: string) {
     return { result: { questions, answers: { [questions[0].question]: answer } } }
   })
   on('session.start', (_, e) => ({ cwd: e.cwd }))
+  on('session.cwd', () => ({ value: '/repo' }))
+  on('session.id', () => ({ value: 's1' }))
+  on('tool.call', () => ({ result: {} }))
   return { runs, toasts, asked }
 }
 
+// Claude is about to change the database: the moment Backstep asks.
+async function changeDatabase($: Parameters<Parameters<typeof test>[2]>[0], on: On) {
+  on('ui.log', () => ({ value: undefined }))
+  mock.clock(on, { now: 5000 })
+  await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
+  await settle()
+  await $.tool.call({ tool: 'Bash', command: 'supabase db push' })
+  await settle()
+}
+
 test('a newer version is offered as a session starts, and Update installs it', { options: { cli: CLI } }, async ($, on) => {
   const { runs, toasts, asked } = updates(on, 'Update')
   await $.session.start({ cwd: '/repo', surface: 'terminal', hasPerson: true } as never)
@@ -826,3 +859,39 @@ test('a GitHub repository Claude created is offered for deletion after undo, and
   expect(logs.find((l) => l.includes('Backstep undid'))).not.toContain('changes GitHub')
   await ui.unmount()
 })
+
+// Uninstalling: asked first, and only the answer removes anything.
+function uninstallSetup(on: On, answer: string) {
+  const runs: string[][] = []
+  const asked: string[] = []
+  on('session.cwd', () => ({ value: '/repo' }))
+  on('session.id', () => ({ value: 's1' }))
+  on('ui.toast', () => ({ value: undefined }))
+  on('process.run', (_, e) => {
+    runs.push([...e.argv])
+    const stdout = e.argv.includes('uninstall') ? JSON.stringify([{ step: 'Claude Code plugin', ok: true, detail: 'removed' }]) : ''
+    return { value: { exitCode: 0, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } }
+  })
+  on('tool.call', { tool: 'AskUserQuestion' }, (_, e) => {
+    const questions = (e as unknown as { questions: { question: string }[] }).questions
+    asked.push(questions[0].question)
+    return { result: { questions, answers: { [questions[0].question]: answer } } }
+  })
+  return { runs, asked }
+}
+
+test('/uninstall-backstep asks, then removes Backstep', { options: { cli: CLI } }, async ($, on) => {
+  const { runs, asked } = uninstallSetup(on, 'Remove Backstep')
+  const r = await $.command.run({ command: 'uninstall-backstep' } as never)
+  expect(asked).toHaveLength(1)
+  expect(runs.at(-1)?.slice(3)).toEqual(['uninstall', '--yes', '--json'])
+  expect(JSON.stringify(r)).toContain('Backstep is removed')
+})
+
+test('asking Claude to uninstall asks too, and Keep it removes nothing', { options: { cli: CLI } }, async ($, on) => {
+  const { runs, asked } = uninstallSetup(on, 'Keep it')
+  const r = await $.tool.call({ tool: 'mcp__backstep__uninstall' } as never)
+  expect(asked).toHaveLength(1)
+  expect(runs.filter((a) => a.includes('uninstall'))).toHaveLength(0)
+  expect(r.result).toBe('Kept Backstep: nothing was removed.')
+})

package/mod/hooks/register.tsx

@@ -489,17 +489,9 @@ async function wrapNewServers($: EngineInterface, cwd: string) {
 // says what Claude reaches that Backstep could undo once connected, so nobody
 // presses undo expecting it to come back.
 async function checkCoverage($: EngineInterface, cwd: string) {
-  // Supabase is only ever noticed here, never connected: that's the person's
-  // call. Firebase is added once someone is signed in to it.
-  const found = await $.process.run(backstep(['connect', '--dir', cwd, '--json', '--auto']), { timeoutMs: 120_000 }).catch(() => null)
-  try {
-    for (const c of JSON.parse(found?.stdout || '[]') as Connected[]) {
-      if (c.state === 'ask') await askDatabase($, c.dir ?? cwd, c.service)
-      if (c.state === 'added') $.ui.toast('Backstep added Firebase for this project, so Claude can reach it and its changes can be undone. Restart Claude Code to use it.')
-    }
-  } catch {
-    // Backstep couldn't be reached: nothing to say.
-  }
+  // Nothing is asked or set up here: a database (Supabase, Postgres, Firebase)
+  // is only asked about once Claude is about to change it (see the Bash hook),
+  // not just because a project in or below this folder happens to use one.
   const ran = await $.process.run(backstep(['status', '--quick', '--json', '--dir', cwd])).catch(() => null)
   let items: { name: string; level: string; detail: string }[] = []
   try {
@@ -525,9 +517,9 @@ const asked = new Set<string>()
 // How each database is named in the question, and what the answer connects.
 const DB_NAME: Record<string, string> = { supabase: 'Supabase', postgres: 'a Postgres database', firebase: 'Firebase' }
 
-// Asked when Claude Code opens a project that uses a database (Supabase, other
-// Postgres, Firebase), or Claude is about to change one, and Backstep isn't
-// connected to it; the answer is the only thing that connects it.
+// Asked when Claude is about to change a database (Supabase, other Postgres,
+// Firebase) that Backstep isn't connected to; never just because a project uses
+// one. The answer is the only thing that connects it.
 async function askDatabase($: EngineInterface, cwd: string, service = 'supabase') {
   const key = `${service}:${cwd}`
   if (asked.has(key)) return
@@ -676,12 +668,56 @@ async function connectServices($: EngineInterface, input: { service?: string; co
   return out.map((s) => `${s.service === 'supabase' ? 'Supabase' : 'Firebase'} (${s.state}): ${s.detail}`).join('\n')
 }
 
+const UNINSTALL = 'mcp__backstep__uninstall'
+
+const UNINSTALL_TOOL = {
+  name: 'uninstall',
+  description:
+    'Remove Backstep (the undo for this session) from this computer: puts MCP servers back as they were, drops its saved database copies, ' +
+    "removes the undo key and the Claude Code plugin, and deletes Backstep's history. Use it only when the user asks to uninstall, remove or delete Backstep. " +
+    'The user is asked to confirm first; nothing else is needed.',
+  inputSchema: { type: 'object', properties: {} },
+}
+
+const UNINSTALL_ASK = { yes: 'Remove Backstep', no: 'Keep it' }
+
+// Asked first, every time: the answer is the only thing that removes it.
+async function uninstallBackstep($: EngineInterface): Promise<string> {
+  const answer = await $.ui
+    .ask(
+      "Remove Backstep from this computer? Your MCP servers go back to how they were, and the undo key, the plugin and Backstep's history are removed. " +
+        "Nothing you've undone or kept changes, but Claude's turns can't be undone after this.",
+      {
+        header: 'Backstep',
+        options: [UNINSTALL_ASK.yes, UNINSTALL_ASK.no],
+      },
+    )
+    .catch(() => null)
+  if (answer !== UNINSTALL_ASK.yes) return 'Kept Backstep: nothing was removed.'
+  const ran = await $.process
+    .run(backstep(['uninstall', '--yes', '--json']), { timeoutMs: 180_000 })
+    .catch((err: unknown) => ({ exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }))
+  let removed: { step: string; ok: boolean; detail: string }[] = []
+  try {
+    removed = JSON.parse(ran.stdout || '[]') as typeof removed
+  } catch {
+    removed = []
+  }
+  if (removed.length === 0) return `Backstep couldn't uninstall itself: ${(ran.stderr || ran.stdout).trim().split('\n').at(-1) || 'it failed'}. Run: backstep uninstall`
+  const lines = removed.map((r) => `${r.ok ? '✓' : '!'} ${r.step}: ${r.detail}`).join('\n')
+  $.ui.toast('Backstep is removed. Restart Claude Code to finish.')
+  return `Backstep is removed. Restart Claude Code to finish.\n${lines}`
+}
+
 export const register: Register = (on, options) => {
   cli = String(options.cli ?? 'backstep')
 
   on('session.start', async ($, e, next) => {
     await $.tool.register(CONNECT_TOOL)
     await $.tool.register(KEY_TOOL)
+    await $.tool.register(UNINSTALL_TOOL)
+    // A command that can't be added never holds up the session: asking Claude still uninstalls.
+    await $.command.register({ name: 'uninstall-backstep', description: 'Remove Backstep and everything it set up from this computer' }).catch(() => null)
     const r = await next(e)
     const boundOut = await $.process.run(backstep(['key', '--json'])).catch(() => null)
     try {
@@ -719,9 +755,13 @@ export const register: Register = (on, options) => {
 
   on('tool.call', { tool: CONNECT }, async ($, e) => ({ result: await connectServices($, e as { service?: string; connection_string?: string; project_ref?: string }) }))
 
+  on('tool.call', { tool: UNINSTALL }, async ($) => ({ result: await uninstallBackstep($) }))
+
+  on('command.run', { command: 'uninstall-backstep' }, async ($) => ({ text: await uninstallBackstep($) }))
+
   on('tool.call', async ($, e, next) => {
     const tool = String(e.tool)
-    if (tool === CONNECT || tool === KEY) return next(e)
+    if (tool === CONNECT || tool === KEY || tool === UNINSTALL) 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

package/package.json

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