@generativereality/cctabs 0.3.2 → 0.4.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cctabs",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux. Claude can orchestrate its own sibling sessions.",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "author": {
     "name": "generativereality",
     "url": "https://cctabs.com"

package/dist/index.js

@@ -4,14 +4,14 @@ import { cli, define } from "gunshi";
 import { createConnection } from "net";
 import { execFileSync, spawn, spawnSync } from "child_process";
 import { randomUUID } from "crypto";
-import { homedir, platform, tmpdir } from "os";
+import { homedir, hostname, platform, tmpdir } from "os";
 import { basename, dirname, extname, join, resolve } from "path";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
 import { consola } from "consola";
 import * as p from "@clack/prompts";
 //#region package.json
 var name = "@generativereality/cctabs";
-var version = "0.3.2";
+var version = "0.4.1";
 var description = "Claude Code tab manager. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -651,6 +651,8 @@ var TabbyAdapter = class {
 			"claude.ai/code",
 			"⏵⏵ bypass",
 			"⏵⏵ auto",
+			"new task?",
+			"Checking for updates",
 			"Thinking",
 			"Hatching",
 			"Composing",
@@ -694,6 +696,27 @@ var TabbyAdapter = class {
 	async renameTab(tabId, name) {
 		await this.http("PUT", `/api/tabs/${tabId}/title`, { title: name });
 	}
+	/**
+	* Fast path: the plugin's POST /api/tabs/new accepts {cwd, title, command,
+	* args} and returns the new tab's uuid synchronously. This collapses the
+	* whole newTab → waitForNewBlock → renameTab → wait-for-shell-prompt →
+	* sendInput sequence into a single round-trip, and (because the uuid is
+	* returned, not discovered by diffing) lets the caller open many tabs at once.
+	*/
+	async openTabDirect(opts) {
+		this.ensureHealthy();
+		const uuid = (await this.http("POST", "/api/tabs/new", {
+			cwd: opts.cwd,
+			title: opts.title,
+			command: opts.command,
+			args: opts.args
+		}))?.uuid;
+		if (!uuid) throw new Error("Tabby plugin did not return a tab uuid");
+		return {
+			blockId: uuid,
+			tabId: uuid
+		};
+	}
 	async sendInput(blockId, text) {
 		return this.http("POST", `/api/tabs/${blockId}/send`, { data: text });
 	}
@@ -1259,66 +1282,114 @@ async function waitForScrollbackMatch(adapter, blockId, pattern, label, timeoutM
 	}
 	throw new Error(`Timed out waiting for ${label}`);
 }
+/**
+* Wait for Claude's input prompt, then send the initial task and reliably
+* submit it.
+*
+* Reliability matters because a naive "send text, then send \r" loses the
+* Enter for multi-line prompts: the terminal treats the burst as a bracketed
+* paste and swallows a \r that arrives inside the paste window, leaving the
+* text sitting unsent in the input box. We fix that two ways:
+*   1. Wrap the prompt in explicit bracketed-paste markers so the (possibly
+*      multi-line) text is ingested as one paste and the following Enter lands
+*      *outside* it — an unambiguous submit, not a newline.
+*   2. Verify the turn actually started (a spinner / "esc to interrupt" hint
+*      appears only while Claude is processing, never at the idle prompt), and
+*      re-send Enter a few times if not, since a large paste can still be
+*      mid-ingest when the first Enter arrives.
+*/
+async function sendInitialPrompt(adapter, blockId, initialPromptFile) {
+	try {
+		await waitForScrollbackMatch(adapter, blockId, "❯", "Claude prompt", 3e4);
+	} catch {
+		adapter.closeSocket();
+		throw new Error("Claude prompt (❯) never appeared — not sending initial prompt. Check that claude started successfully.");
+	}
+	const prompt = readFileSync(initialPromptFile, "utf-8").trimEnd();
+	await adapter.sendInput(blockId, `\x1b[200~${prompt}\x1b[201~`);
+	for (let attempt = 0; attempt < 4; attempt++) {
+		await new Promise((r) => setTimeout(r, attempt === 0 ? 300 : 500));
+		await adapter.sendInput(blockId, "\r");
+		await new Promise((r) => setTimeout(r, 500));
+		const tail = adapter.scrollback(blockId, 40);
+		const compact = tail.replace(/\s+/g, "");
+		if (/[✻✽✶✳✢]/.test(tail) || /esctointerrupt/i.test(compact)) return;
+	}
+	consola.warn("Could not confirm the initial prompt was submitted — it may be sitting in the input box. Press Enter in the tab to send it.");
+}
 async function openSession(opts) {
 	const { tabName, claudeCmd, workspaceQuery, initialPromptFile, envVars, modelOverride } = opts;
+	const tailDelayMs = opts.tailDelayMs ?? 2e3;
 	const dir = resolve(opts.dir.replace(/^~/, homedir()));
-	if (!existsSync(dir)) {
-		consola.error(`Directory does not exist: ${dir}`);
-		process.exit(1);
-	}
+	if (!existsSync(dir)) throw new Error(`Directory does not exist: ${dir}`);
 	const config = loadConfig();
 	const adapter = requireAdapter();
+	const timing = !!process.env.CCTABS_TIMING;
+	let tPhase = Date.now();
+	const mark = (label) => {
+		if (!timing) return;
+		const now = Date.now();
+		consola.log(`    ⏱ ${tabName} ${label}: ${now - tPhase}ms`);
+		tPhase = now;
+	};
+	if (adapter.openTabDirect) {
+		const extraFlags = config.claude.flags.join(" ");
+		const namePart = claudeCmd.includes("--resume") ? "" : ` --name ${JSON.stringify(tabName)}`;
+		const modelPart = modelOverride ? ` --model ${JSON.stringify(modelOverride)}` : "";
+		const envPrefix = envVars ? shellQuoteEnv$1(envVars) : "";
+		const claudeCore = `claude${extraFlags ? " " + extraFlags : ""} ${claudeCmd.replace(/^claude\s*/, "")}${namePart}${modelPart}`.replace(/\s+/g, " ").trim();
+		const shell = process.env.SHELL ?? "/bin/zsh";
+		const launch = `${envPrefix}exec ${claudeCore}`;
+		const { blockId, tabId } = await adapter.openTabDirect({
+			cwd: dir,
+			title: tabName,
+			command: shell,
+			args: [
+				"-l",
+				"-c",
+				launch
+			]
+		});
+		mark("openTabDirect");
+		if (initialPromptFile) await sendInitialPrompt(adapter, blockId, initialPromptFile);
+		adapter.closeSocket();
+		return tabId;
+	}
 	let focusWindowId;
 	if (workspaceQuery) {
 		const { workspaces } = await adapter.getAllData();
 		const matches = adapter.resolveWorkspace(workspaces, workspaceQuery);
-		if (!matches.length) {
-			consola.error(`No workspace matching '${workspaceQuery}'`);
-			process.exit(1);
-		}
+		if (!matches.length) throw new Error(`No workspace matching '${workspaceQuery}'`);
 		const { data, windowId } = matches[0];
-		if (!windowId) {
-			consola.error(`Workspace '${data.name}' has no open window`);
-			process.exit(1);
-		}
+		if (!windowId) throw new Error(`Workspace '${data.name}' has no open window`);
 		focusWindowId = windowId;
 		consola.info(`Workspace: ${data.name}`);
 	}
 	const beforeIds = new Set(adapter.blocksList().filter((b) => b.view === "term").map((b) => b.blockid));
+	mark("beforeIds");
 	await adapter.newTab(focusWindowId);
+	mark("newTab");
 	const result = await adapter.waitForNewBlock(beforeIds);
-	if (!result) {
-		consola.error("Timed out waiting for new terminal block");
-		process.exit(1);
-	}
+	if (!result) throw new Error("Timed out waiting for new terminal block");
+	mark("waitForNewBlock");
 	const { blockId, tabId } = result;
 	await adapter.renameTab(tabId, tabName);
+	mark("renameTab");
 	try {
 		await waitForScrollbackMatch(adapter, blockId, /[$%>]\s*$/, "shell prompt", 1e4, 250);
 	} catch {
-		consola.error("Shell prompt never appeared in new tab — aborting. Check your shell profile (e.g. nvm default alias).");
-		process.exit(1);
+		throw new Error("Shell prompt never appeared in new tab — aborting. Check your shell profile (e.g. nvm default alias).");
 	}
+	mark("shellPrompt");
 	const extraFlags = config.claude.flags.join(" ");
 	const namePart = claudeCmd.includes("--resume") ? "" : ` --name ${JSON.stringify(tabName)}`;
 	const modelPart = modelOverride ? ` --model ${JSON.stringify(modelOverride)}` : "";
 	const envPrefix = envVars ? shellQuoteEnv$1(envVars) : "";
 	const cmd = `cd ${JSON.stringify(dir)} && ${envPrefix}claude${extraFlags ? " " + extraFlags : ""} ${claudeCmd.replace(/^claude\s*/, "")}${namePart}${modelPart}\r`;
 	await adapter.sendInput(blockId, cmd);
-	if (initialPromptFile) {
-		try {
-			await waitForScrollbackMatch(adapter, blockId, "❯", "Claude prompt", 3e4);
-		} catch {
-			consola.error("Claude prompt (❯) never appeared — not sending initial prompt. Check that claude started successfully.");
-			adapter.closeSocket();
-			process.exit(1);
-		}
-		const prompt = readFileSync(initialPromptFile, "utf-8").trimEnd();
-		await adapter.sendInput(blockId, prompt);
-		await new Promise((r) => setTimeout(r, 100));
-		await adapter.sendInput(blockId, "\r");
-	}
-	await new Promise((r) => setTimeout(r, 2e3));
+	if (initialPromptFile) await sendInitialPrompt(adapter, blockId, initialPromptFile);
+	if (tailDelayMs > 0) await new Promise((r) => setTimeout(r, tailDelayMs));
+	mark("tail");
 	adapter.closeSocket();
 	return tabId;
 }
@@ -2339,24 +2410,29 @@ async function runManifestMode(manifestPath, createMissing, dryRun) {
 		}
 	}
 	adapter.closeSocket();
-	for (const entry of toSpawn) try {
-		const claudeCmd = entry.session_id ? `claude --resume ${entry.session_id} --name ${JSON.stringify(entry.name)}` : "claude";
-		const newTabId = await openSession({
-			tabName: entry.name,
-			dir: entry.dir,
-			claudeCmd
-		});
-		const sid = entry.session_id ? entry.session_id.slice(0, 8) + "…" : "fresh";
-		results.push({
-			name: entry.name,
-			result: `✔ spawned [${newTabId.slice(0, 8)}] (${sid})`
-		});
-	} catch (err) {
-		results.push({
-			name: entry.name,
-			result: `✘ spawn failed: ${err.message}`
-		});
-	}
+	const spawnOne = async (entry) => {
+		try {
+			const claudeCmd = entry.session_id ? `claude --resume ${entry.session_id} --name ${JSON.stringify(entry.name)}` : "claude";
+			const newTabId = await openSession({
+				tabName: entry.name,
+				dir: entry.dir,
+				claudeCmd,
+				tailDelayMs: 500
+			});
+			const sid = entry.session_id ? entry.session_id.slice(0, 8) + "…" : "fresh";
+			results.push({
+				name: entry.name,
+				result: `✔ spawned [${newTabId.slice(0, 8)}] (${sid})`
+			});
+		} catch (err) {
+			results.push({
+				name: entry.name,
+				result: `✘ spawn failed: ${err.message}`
+			});
+		}
+	};
+	if (typeof adapter.openTabDirect === "function") await Promise.all(toSpawn.map(spawnOne));
+	else for (const entry of toSpawn) await spawnOne(entry);
 	console.log("\nRestore summary:");
 	for (const r of results) console.log(`  ${r.name}: ${r.result}`);
 }
@@ -2391,6 +2467,7 @@ async function runLegacyMode(rawDir, dryRun) {
 	const extraFlags = loadConfig().claude.flags.join(" ");
 	const results = [];
 	const toRecreate = [];
+	const resolved = [];
 	for (const tab of toResume) {
 		let sessionId = null;
 		let sessionDir = null;
@@ -2437,8 +2514,21 @@ async function runLegacyMode(rawDir, dryRun) {
 			});
 			continue;
 		}
-		if (tab.status === "unknown") {
-			if (await adapter.confirmScrollbackEmpty(tab.blockId)) {
+		resolved.push({
+			tab,
+			sessionId,
+			sessionDir
+		});
+	}
+	if (!dryRun) {
+		const unknownTabs = resolved.filter((r) => r.tab.status === "unknown");
+		const emptyById = /* @__PURE__ */ new Map();
+		await Promise.all(unknownTabs.map(async (r) => {
+			emptyById.set(r.tab.tabId, await adapter.confirmScrollbackEmpty(r.tab.blockId));
+		}));
+		for (const r of resolved) {
+			const { tab, sessionId, sessionDir } = r;
+			if (tab.status === "unknown" && emptyById.get(tab.tabId)) {
 				const blockIds = (tabsById.get(tab.tabId) ?? []).map((b) => b.blockid);
 				toRecreate.push({
 					name: tab.name,
@@ -2453,15 +2543,15 @@ async function runLegacyMode(rawDir, dryRun) {
 				});
 				continue;
 			}
+			consola.log(`  ${tab.name} → resuming session ${sessionId.slice(0, 8)}… in ${sessionDir} (send)`);
+			const cmd = `cd ${JSON.stringify(sessionDir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${sessionId} --name ${JSON.stringify(tab.name)}\r`;
+			await adapter.sendInput(tab.blockId, cmd);
+			await new Promise((r) => setTimeout(r, 500));
+			results.push({
+				name: tab.name,
+				result: "sent"
+			});
 		}
-		consola.log(`  ${tab.name} → resuming session ${sessionId.slice(0, 8)}… in ${sessionDir} (send)`);
-		const cmd = `cd ${JSON.stringify(sessionDir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${sessionId} --name ${JSON.stringify(tab.name)}\r`;
-		await adapter.sendInput(tab.blockId, cmd);
-		await new Promise((r) => setTimeout(r, 500));
-		results.push({
-			name: tab.name,
-			result: "sent"
-		});
 	}
 	if (!dryRun) {
 		const sent = results.filter((r) => r.result === "sent");
@@ -2481,18 +2571,23 @@ async function runLegacyMode(rawDir, dryRun) {
 		for (const t of toRecreate) for (const bid of t.blockIds) adapter.deleteBlock(bid);
 		adapter.closeSocket();
 		consola.info(`Recreating ${toRecreate.length} dead tab(s)…`);
-		for (const t of toRecreate) try {
-			const newTabId = await openSession({
-				tabName: t.name,
-				dir: t.sessionDir,
-				claudeCmd: `claude --resume ${t.sessionId} --name ${JSON.stringify(t.name)}`
-			});
-			const r = results.find((x) => x.name === t.name);
-			r.result = `✔ recreated [${newTabId.slice(0, 8)}]`;
-		} catch (err) {
-			const r = results.find((x) => x.name === t.name);
-			r.result = `✘ recreate failed: ${err.message}`;
-		}
+		const recreateOne = async (t) => {
+			try {
+				const newTabId = await openSession({
+					tabName: t.name,
+					dir: t.sessionDir,
+					claudeCmd: `claude --resume ${t.sessionId} --name ${JSON.stringify(t.name)}`,
+					tailDelayMs: 500
+				});
+				const r = results.find((x) => x.name === t.name);
+				r.result = `✔ recreated [${newTabId.slice(0, 8)}]`;
+			} catch (err) {
+				const r = results.find((x) => x.name === t.name);
+				r.result = `✘ recreate failed: ${err.message}`;
+			}
+		};
+		if (typeof adapter.openTabDirect === "function") await Promise.all(toRecreate.map(recreateOne));
+		else for (const t of toRecreate) await recreateOne(t);
 	} else adapter.closeSocket();
 	console.log("\nRestore summary:");
 	for (const r of results) console.log(`  ${r.name}: ${r.result}`);
@@ -2879,6 +2974,389 @@ echo "[$(date)] done"
 	}
 });
 //#endregion
+//#region src/commands/export-cmd.ts
+/** Replace anything that isn't safe in a filesystem dir name. */
+function safeDirName(name) {
+	return name.replace(/[^A-Za-z0-9._-]+/g, "_").slice(0, 80) || "tab";
+}
+function timestampSlug() {
+	const d = /* @__PURE__ */ new Date();
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+const exportCommand = define({
+	name: "export",
+	description: "Export tabs + their Claude sessions to a tarball you can move to another machine (then `cctabs import`).",
+	args: {
+		all: {
+			type: "boolean",
+			short: "a",
+			description: "Export every tab in the workspace (use --workspace to pick one; default is the current workspace)."
+		},
+		workspace: {
+			type: "string",
+			short: "w",
+			description: "Workspace to export from when using --all (defaults to current)."
+		},
+		out: {
+			type: "string",
+			short: "o",
+			description: "Output path for the tarball. Default: ./cctabs-export-<name>-<timestamp>.tar.gz"
+		}
+	},
+	async run(ctx) {
+		const tabQuery = ctx.positionals[1];
+		const exportAll = ctx.values.all ?? false;
+		const workspaceQuery = ctx.values.workspace;
+		const outPath = ctx.values.out;
+		if (!tabQuery && !exportAll) {
+			consola.error("Provide a tab name, or pass --all to export every tab in the workspace.");
+			process.exit(1);
+		}
+		if (tabQuery && exportAll) {
+			consola.error("Pass either a tab name OR --all, not both.");
+			process.exit(1);
+		}
+		const adapter = requireAdapter();
+		const { tabsById, tabNames, workspaces } = await adapter.getAllData();
+		const currentWs = adapter.currentWorkspaceId();
+		let wsData;
+		if (workspaceQuery) {
+			const matches = adapter.resolveWorkspace(workspaces, workspaceQuery);
+			if (matches.length === 0) {
+				consola.error(`Workspace not found: ${workspaceQuery}`);
+				process.exit(1);
+			}
+			if (matches.length > 1) {
+				consola.error(`Workspace query is ambiguous: ${workspaceQuery}`);
+				process.exit(1);
+			}
+			wsData = matches[0].data;
+		} else wsData = workspaces.find((w) => w.workspacedata.oid === currentWs)?.workspacedata;
+		if (!wsData) {
+			consola.error("Could not determine workspace.");
+			process.exit(1);
+		}
+		const wsName = wsData.name;
+		const wsTabIds = wsData.tabids.filter((t) => tabsById.has(t));
+		let targetTabIds;
+		if (exportAll) targetTabIds = wsTabIds;
+		else {
+			const matched = adapter.resolveTab(tabQuery, tabsById, tabNames).filter((tid) => wsTabIds.includes(tid));
+			if (matched.length === 0) {
+				consola.error(`No tab in workspace "${wsName}" matches: ${tabQuery}`);
+				process.exit(1);
+			}
+			if (matched.length > 1) {
+				consola.error(`Tab query is ambiguous: ${tabQuery} (matches ${matched.length} tabs)`);
+				process.exit(1);
+			}
+			targetTabIds = matched;
+		}
+		const stageRoot = mkdtempSync(join(tmpdir(), "cctabs-export-"));
+		const tabsRoot = join(stageRoot, "tabs");
+		mkdirSync(tabsRoot, { recursive: true });
+		const exported = [];
+		const skipped = [];
+		for (const tabId of targetTabIds) {
+			const tabName = tabNames.get(tabId) ?? tabId.slice(0, 8);
+			const termBlock = (tabsById.get(tabId) ?? []).find((b) => b.view === "term");
+			if (!termBlock) {
+				skipped.push({
+					name: tabName,
+					reason: "no terminal block"
+				});
+				continue;
+			}
+			const cwd = termBlock.meta?.["cmd:cwd"];
+			if (!cwd) {
+				skipped.push({
+					name: tabName,
+					reason: "no cwd recorded"
+				});
+				continue;
+			}
+			let sessionId;
+			let effectiveCwd = cwd;
+			try {
+				const matches = findSessionsByName(cwd, tabName);
+				if (matches.length) sessionId = matches[0].id;
+			} catch {}
+			if (!sessionId) {
+				const worktreesDir = join(cwd, ".claude", "worktrees");
+				if (existsSync(worktreesDir)) try {
+					const candidates = [];
+					for (const entry of readdirSync(worktreesDir)) {
+						const wtPath = join(worktreesDir, entry);
+						if (!statSync(wtPath).isDirectory()) continue;
+						try {
+							const matches = findSessionsByName(wtPath, tabName);
+							if (matches.length) candidates.push({
+								id: matches[0].id,
+								mtime: matches[0].mtime,
+								path: wtPath
+							});
+						} catch {}
+					}
+					if (candidates.length) {
+						candidates.sort((a, b) => b.mtime - a.mtime);
+						sessionId = candidates[0].id;
+						effectiveCwd = candidates[0].path;
+					}
+				} catch {}
+			}
+			if (!sessionId) {
+				skipped.push({
+					name: tabName,
+					reason: "no Claude session found for this tab name + cwd"
+				});
+				continue;
+			}
+			const slug = pathToProjectSlug(effectiveCwd);
+			const jsonlPath = join(homedir(), ".claude", "projects", slug, `${sessionId}.jsonl`);
+			if (!existsSync(jsonlPath)) {
+				skipped.push({
+					name: tabName,
+					reason: `session file missing: ${jsonlPath}`
+				});
+				continue;
+			}
+			const tabDir = join(tabsRoot, safeDirName(tabName));
+			mkdirSync(tabDir, { recursive: true });
+			copyFileSync(jsonlPath, join(tabDir, "session.jsonl"));
+			const manifest = {
+				name: tabName,
+				cwd: effectiveCwd,
+				sessionId,
+				claudeProjectSlug: slug,
+				workspace: wsName
+			};
+			writeFileSync(join(tabDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+			exported.push({ ...manifest });
+		}
+		if (exported.length === 0) {
+			rmSync(stageRoot, {
+				recursive: true,
+				force: true
+			});
+			consola.error("Nothing to export. Skipped tabs:");
+			for (const s of skipped) consola.log(`  ${s.name}: ${s.reason}`);
+			process.exit(1);
+		}
+		const meta = {
+			cctabsExportVersion: 1,
+			cctabsVersion: version,
+			exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			sourceMachine: hostname(),
+			tabs: exported
+		};
+		writeFileSync(join(stageRoot, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+		const defaultName = exportAll ? `cctabs-export-${safeDirName(wsName)}-${timestampSlug()}.tar.gz` : `cctabs-export-${safeDirName(exported[0].name)}-${timestampSlug()}.tar.gz`;
+		const resolvedOut = outPath ?? join(process.cwd(), defaultName);
+		try {
+			execFileSync("tar", [
+				"-czf",
+				resolvedOut,
+				"-C",
+				stageRoot,
+				"."
+			], { stdio: "inherit" });
+		} catch (err) {
+			rmSync(stageRoot, {
+				recursive: true,
+				force: true
+			});
+			consola.error(`tar failed: ${err.message}`);
+			process.exit(1);
+		}
+		rmSync(stageRoot, {
+			recursive: true,
+			force: true
+		});
+		consola.success(`Exported ${exported.length} tab${exported.length === 1 ? "" : "s"} → ${resolvedOut}`);
+		for (const t of exported) consola.log(`  ✓ ${t.name}  (${t.sessionId.slice(0, 8)}…)  ${t.cwd}`);
+		if (skipped.length) {
+			consola.warn(`Skipped ${skipped.length}:`);
+			for (const s of skipped) consola.log(`  - ${s.name}: ${s.reason}`);
+		}
+		consola.log("");
+		consola.log(`Import on another machine with:  cctabs import ${defaultName}`);
+	}
+});
+//#endregion
+//#region src/commands/import-cmd.ts
+function expandHome(p) {
+	return p.startsWith("~") ? join(homedir(), p.slice(1)) : p;
+}
+const importCommand = define({
+	name: "import",
+	description: "Import tabs + sessions from a cctabs-export tarball (produced by `cctabs export`) and open each one as a new tab.",
+	args: {
+		cwd: {
+			type: "string",
+			short: "C",
+			description: "Target working directory. With a single-tab archive, replaces the original cwd. Ignored for multi-tab archives."
+		},
+		workspace: {
+			type: "string",
+			short: "w",
+			description: "Workspace to open the new tab(s) in (defaults to current)."
+		},
+		force: {
+			type: "boolean",
+			short: "f",
+			description: "Overwrite an existing session jsonl in ~/.claude/projects/ if the same session id already exists locally."
+		},
+		"dry-run": {
+			type: "boolean",
+			short: "n",
+			description: "Report what would happen without copying files or spawning tabs."
+		}
+	},
+	async run(ctx) {
+		const archive = ctx.positionals[1];
+		const cwdOverride = ctx.values.cwd;
+		const workspaceQuery = ctx.values.workspace;
+		const force = ctx.values.force ?? false;
+		const dryRun = ctx.values["dry-run"] ?? false;
+		if (!archive) {
+			consola.error("Archive path is required.");
+			process.exit(1);
+		}
+		const archivePath = resolve(expandHome(archive));
+		if (!existsSync(archivePath)) {
+			consola.error(`Archive not found: ${archivePath}`);
+			process.exit(1);
+		}
+		const stageRoot = mkdtempSync(join(tmpdir(), "cctabs-import-"));
+		try {
+			execFileSync("tar", [
+				"-xzf",
+				archivePath,
+				"-C",
+				stageRoot
+			], { stdio: "inherit" });
+		} catch (err) {
+			rmSync(stageRoot, {
+				recursive: true,
+				force: true
+			});
+			consola.error(`tar failed to extract ${archivePath}: ${err.message}`);
+			process.exit(1);
+		}
+		const metaPath = join(stageRoot, "meta.json");
+		if (!existsSync(metaPath)) {
+			rmSync(stageRoot, {
+				recursive: true,
+				force: true
+			});
+			consola.error("Archive does not contain meta.json — not a cctabs export.");
+			process.exit(1);
+		}
+		let meta;
+		try {
+			meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+		} catch (err) {
+			rmSync(stageRoot, {
+				recursive: true,
+				force: true
+			});
+			consola.error(`meta.json is malformed: ${err.message}`);
+			process.exit(1);
+		}
+		if (meta.cctabsExportVersion !== 1) {
+			rmSync(stageRoot, {
+				recursive: true,
+				force: true
+			});
+			consola.error(`Unsupported cctabsExportVersion: ${meta.cctabsExportVersion} (this build understands version 1).`);
+			process.exit(1);
+		}
+		if (cwdOverride && meta.tabs.length > 1) consola.warn(`--cwd was provided but archive contains ${meta.tabs.length} tabs; --cwd is ignored for multi-tab imports.`);
+		consola.info(`Importing ${meta.tabs.length} tab${meta.tabs.length === 1 ? "" : "s"} from ${archivePath}`);
+		if (meta.sourceMachine) consola.log(`  Source: ${meta.sourceMachine}${meta.cctabsVersion ? ` (cctabs ${meta.cctabsVersion})` : ""}`);
+		if (meta.exportedAt) consola.log(`  Exported: ${meta.exportedAt}`);
+		consola.log("");
+		const tabsDir = join(stageRoot, "tabs");
+		const stagedDirs = existsSync(tabsDir) ? readdirSync(tabsDir).filter((n) => statSync(join(tabsDir, n)).isDirectory()) : [];
+		const results = [];
+		for (const entry of meta.tabs) {
+			let stagedDir;
+			for (const d of stagedDirs) {
+				const m = join(tabsDir, d, "manifest.json");
+				if (!existsSync(m)) continue;
+				try {
+					if (JSON.parse(readFileSync(m, "utf-8")).sessionId === entry.sessionId) {
+						stagedDir = join(tabsDir, d);
+						break;
+					}
+				} catch {}
+			}
+			if (!stagedDir) {
+				results.push({
+					name: entry.name,
+					status: `staged tab dir not found for sessionId ${entry.sessionId.slice(0, 8)}…`
+				});
+				continue;
+			}
+			const targetCwd = resolve(expandHome(meta.tabs.length === 1 && cwdOverride ? cwdOverride : entry.cwd));
+			if (!existsSync(targetCwd)) {
+				results.push({
+					name: entry.name,
+					status: `cwd missing on this machine: ${targetCwd} (clone the repo, then re-run)`
+				});
+				continue;
+			}
+			const targetSlug = pathToProjectSlug(targetCwd);
+			const targetProjectDir = join(homedir(), ".claude", "projects", targetSlug);
+			const targetJsonl = join(targetProjectDir, `${entry.sessionId}.jsonl`);
+			const srcJsonl = join(stagedDir, "session.jsonl");
+			if (existsSync(targetJsonl) && !force) {
+				results.push({
+					name: entry.name,
+					status: `already present at ${targetJsonl} (pass --force to overwrite)`
+				});
+				continue;
+			}
+			if (dryRun) {
+				results.push({
+					name: entry.name,
+					status: `dry-run: would copy → ${targetJsonl} and open tab in ${targetCwd}`
+				});
+				continue;
+			}
+			mkdirSync(targetProjectDir, { recursive: true });
+			copyFileSync(srcJsonl, targetJsonl);
+			const config = loadConfig();
+			const claudeCmd = `claude${config.claude.flags.length ? " " + config.claude.flags.join(" ") : ""} --resume ${entry.sessionId} --name ${JSON.stringify(entry.name)}`;
+			try {
+				await openSession({
+					tabName: entry.name,
+					dir: targetCwd,
+					claudeCmd,
+					workspaceQuery
+				});
+				results.push({
+					name: entry.name,
+					status: `imported → ${targetJsonl}, tab opened`
+				});
+			} catch (err) {
+				results.push({
+					name: entry.name,
+					status: `jsonl copied but failed to open tab: ${err.message}`
+				});
+			}
+		}
+		rmSync(stageRoot, {
+			recursive: true,
+			force: true
+		});
+		consola.log("");
+		consola.log("Results:");
+		for (const r of results) consola.log(`  ${r.name.padEnd(24)} ${r.status}`);
+	}
+});
+//#endregion
 //#region src/commands/index.ts
 const defaultCommand = define({
 	name: "cctabs",
@@ -2903,7 +3381,9 @@ const subCommands = new Map([
 	["restore", restoreCommand],
 	["backends", backendsCommand],
 	["doctor", doctorCommand],
-	["install-tabby-plugin", installTabbyPluginCommand]
+	["install-tabby-plugin", installTabbyPluginCommand],
+	["export", exportCommand],
+	["import", importCommand]
 ]);
 async function run() {
 	await cli(process.argv.slice(2), defaultCommand, {
@@ -2916,7 +3396,12 @@ async function run() {
 }
 //#endregion
 //#region src/index.ts
-updateNotifier({ pkg: package_default }).notify();
+const notifier = updateNotifier({ pkg: package_default });
+notifier.notify();
+if (notifier.update && notifier.update.latest !== notifier.update.current) {
+	const { current, latest } = notifier.update;
+	process.stdout.write(`[cctabs] OUTDATED ${current} < ${latest} — run: npm install -g ${name}@latest\n`);
+}
 run().catch((err) => {
 	console.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/cctabs",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {

package/skills/cctabs/SKILL.md

@@ -44,6 +44,14 @@ npm install -g @generativereality/cctabs
 
 Do not modify PATH or npm configuration beyond this.
 
+### Check the installed version isn't stale
+
+On your first cctabs invocation in a session, look at the version banner cctabs prints (`(@generativereality/cctabs vX.Y.Z)`) and at any `[cctabs] OUTDATED ...` warning line in the output. If you see the warning — or if the banner version is older than the version in this skill's `plugin.json` — tell the user:
+
+> *"Your installed cctabs is `vX.Y.Z`; the current release is `vA.B.C`. Want me to upgrade with `npm install -g @generativereality/cctabs@latest` before continuing?"*
+
+Don't silently work around an outdated CLI: detection heuristics, command flags, and bug fixes diverge between versions, so misbehavior on the user's machine is often "binary on PATH lags behind the plugin docs you're reading." The Claude Code marketplace plugin update path only refreshes this skill — the npm-installed CLI binary is a separate channel and must be upgraded explicitly.
+
 ### Tabby users: a one-time plugin install is needed
 
 Wave Terminal works out of the box. **Tabby additionally needs a small companion plugin** that exposes a localhost HTTP API the cctabs CLI talks to.
@@ -66,7 +74,7 @@ On approval, run `cctabs install-tabby-plugin --yes`. Tabby quits ~2s after the
 
 If the user wants to keep their other Tabby tabs intact, run `cctabs install-tabby-plugin --no-restart` instead and tell them to quit + reopen Tabby themselves.
 
-`cctabs doctor` is also available for a deliberate environment check (terminal, Wave Accessibility, plugin reachability, Wave DB) — useful if something feels off, but **not required as a preflight** since every command fails loudly on its own.
+`cctabs doctor` is also available for a deliberate environment check. It adapts to whichever terminal you're running in — terminal detection runs either way; on Wave it additionally inspects Accessibility permission and scans the Wave DB for orphan tabids; on Tabby it probes the cctabs plugin's localhost health endpoint. Useful if something feels off, but **not required as a preflight** since every command fails loudly on its own.
 
 #### Auto-install + auto-restart (recommended)
 
@@ -143,6 +151,9 @@ cctabs close <name-or-id>                # close a tab
 cctabs rename <name-or-id> <new-name>    # rename a tab
 cctabs scrollback <tab-or-block> [n]    # read terminal output (default: 50 lines)
 cctabs send <tab-or-block> [text]        # send input — arg, --file, or stdin pipe
+cctabs export <name> [--out path]        # bundle a tab + its claude session into a tarball
+cctabs export --all [-w workspace]       # bundle every tab in a workspace
+cctabs import <tarball> [--dry-run] [-f] # restore tabs + sessions from a tarball
 cctabs backends                          # list available backend presets
 cctabs config                            # show config and path
 ```
@@ -260,7 +271,7 @@ cctabs resume api ~/Dev/myapp
 
 ## Workflow: Restoring tabs after a reboot
 
-After a Wave/computer restart, every tab loses its Claude session and shows up with `terminal` or `unknown` status. `cctabs restore` walks every such tab, looks up its session by name across **all** Claude project directories, and re-attaches in place.
+After a terminal restart or computer reboot, every tab loses its Claude session and shows up with `terminal` or `unknown` status (true for both Wave and Tabby). `cctabs restore` walks every such tab, looks up its session by name across **all** Claude project directories, and re-attaches in place.
 
 ```bash
 cctabs restore                    # search all projects (default)
@@ -270,6 +281,31 @@ cctabs restore ~/Dev/myapp        # restrict the search to one project dir
 
 If a session was started in a different `cwd` than the tab's current directory (common after `cd`-ing inside the tab), the global search still finds it via the recorded session metadata — no need to guess the right dir.
 
+## Workflow: Moving sessions across machines
+
+Use `export` + `import` to migrate a tab (or a whole workspace) — and its underlying Claude conversation — from one machine to another, e.g. when switching laptops or sharing a debug session with a teammate.
+
+```bash
+# On source machine
+cctabs export auth                                  # → ./cctabs-export-auth-<ts>.tar.gz
+cctabs export auth --out ~/Downloads/auth.tar.gz
+cctabs export --all                                 # every tab in the current workspace
+cctabs export --all --workspace tabby
+
+# On destination machine
+cctabs import ~/Downloads/auth.tar.gz --dry-run     # preview without copying or opening tabs
+cctabs import ~/Downloads/auth.tar.gz               # copy session jsonl(s) + open tab(s)
+cctabs import ~/Downloads/auth.tar.gz --cwd ~/Dev/myapp   # single-tab archives only — remap the cwd
+cctabs import ~/Downloads/auth.tar.gz --force       # overwrite a session id that already exists locally
+```
+
+Gotchas:
+
+- **Target cwd must exist on the destination machine.** Each manifested tab carries the original `cwd` (e.g. `/Users/alice/Dev/myapp`). If that path doesn't exist locally, that entry is skipped with a "clone the repo, then re-run" hint. Either clone/recreate the directory first, or use `--cwd` to remap (single-tab archives only).
+- **No multi-tab cwd remap.** If the source laptop had repos under a different layout (e.g. `~/Dev/Projects/foo` vs `~/Dev/foo`), `--cwd` is ignored. The workaround is to extract the tarball, edit `meta.json`, and re-tar — or split into per-tab archives and import each with `--cwd`.
+- **Session IDs are preserved.** The exported session jsonl lands at `~/.claude/projects/<slug>/<sessionId>.jsonl` on the destination. Pass `--force` to overwrite a colliding session id (e.g. when re-importing an updated export).
+- **Always preview multi-tab imports with `--dry-run` first.** It reports which entries would import, which would be skipped (missing cwd), and where each session jsonl would land — useful before spawning many tabs.
+
 ## Workflow: Forking a Session
 
 Use `fork` when you want to explore an alternative approach without disrupting the original.