@generativereality/cctabs 0.2.0 → 0.3.0

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.2.0",
+  "version": "0.3.0",
   "author": {
     "name": "generativereality",
     "url": "https://cctabs.com"

package/dist/index.js

@@ -2,15 +2,16 @@
 import updateNotifier from "update-notifier";
 import { cli, define } from "gunshi";
 import { createConnection } from "net";
-import { execFileSync, spawnSync } from "child_process";
+import { execFileSync, spawn, spawnSync } from "child_process";
 import { randomUUID } from "crypto";
-import { homedir, tmpdir } from "os";
+import { homedir, platform, tmpdir } from "os";
 import { basename, dirname, extname, join, resolve } from "path";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { consola } from "consola";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import * as p from "@clack/prompts";
 //#region package.json
 var name = "@generativereality/cctabs";
-var version = "0.2.0";
+var version = "0.3.0";
 var description = "Claude Code tab manager. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -31,6 +32,8 @@ var package_default = {
 		"check": "npm run typecheck && npm run build",
 		"release": "bumpp && npm publish",
 		"sync-plugin": "bash scripts/sync-plugin.sh",
+		"build:tabby-plugin": "cd tabby-plugin && npm install && npm run build",
+		"publish:tabby-plugin": "cd tabby-plugin && npm publish --access public",
 		"prepack": "bash scripts/sync-plugin.sh --check && npm run build"
 	},
 	keywords: [
@@ -70,9 +73,10 @@ var package_default = {
 //#endregion
 //#region src/core/terminal.ts
 function detectTerminal() {
-	if (process.env.WAVETERM_JWT) return "wave";
 	const prog = process.env.TERM_PROGRAM ?? "";
 	const term = process.env.TERM ?? "";
+	if (prog === "Tabby") return "tabby";
+	if (process.env.WAVETERM_JWT) return "wave";
 	if (prog === "iTerm.app") return "iterm2";
 	if (prog === "ghostty" || process.env.GHOSTTY_RESOURCES_DIR) return "ghostty";
 	if (prog === "WarpTerminal") return "warp";
@@ -85,6 +89,7 @@ function detectTerminal() {
 }
 const TERMINAL_NAMES = {
 	wave: "Wave Terminal",
+	tabby: "Tabby",
 	iterm2: "iTerm2",
 	ghostty: "Ghostty",
 	warp: "Warp",
@@ -123,7 +128,89 @@ function adapterFileName(terminal) {
 	return `${terminal}.ts`;
 }
 //#endregion
+//#region src/core/wave-db.ts
+const WAVE_DB_PATH = process.env.CCTABS_WAVE_DB_PATH ?? join(homedir(), "Library", "Application Support", "waveterm", "db", "waveterm.db");
+const WSH_ORPHAN_TABID_PATTERN = /couldn't list blocks for workspace [0-9a-f-]+: not found/i;
+function sqliteRun(query, mode = "list") {
+	return execFileSync("sqlite3", [
+		"-readonly",
+		"-bail",
+		`-${mode}`,
+		WAVE_DB_PATH,
+		query
+	], { encoding: "utf-8" }).trim();
+}
+/** Inspect every workspace; report any tabids that point at non-existent rows in db_tab. */
+function findOrphanTabIds() {
+	if (!existsSync(WAVE_DB_PATH)) return [];
+	const rawWs = sqliteRun("SELECT oid AS oid, json_extract(data, '$.name') AS name, json_extract(data, '$.tabids') AS tabids FROM db_workspace;", "json");
+	const tabRows = sqliteRun("SELECT oid FROM db_tab;", "list");
+	const liveTabs = new Set(tabRows.split("\n").map((s) => s.trim()).filter(Boolean));
+	const wsRows = rawWs ? JSON.parse(rawWs) : [];
+	const reports = [];
+	for (const row of wsRows) {
+		if (!row.tabids) continue;
+		let tabids;
+		try {
+			tabids = JSON.parse(row.tabids);
+		} catch {
+			continue;
+		}
+		if (!Array.isArray(tabids)) continue;
+		const present = [];
+		const orphans = [];
+		for (const t of tabids) {
+			if (typeof t !== "string") continue;
+			if (liveTabs.has(t)) present.push(t);
+			else orphans.push(t);
+		}
+		if (orphans.length) reports.push({
+			workspaceId: row.oid,
+			workspaceName: row.name || row.oid.slice(0, 8),
+			presentTabIds: present,
+			orphanTabIds: orphans
+		});
+	}
+	return reports;
+}
+/** Copy the live DB to a timestamped backup next to it. Returns the backup path. */
+function backupWaveDb() {
+	const dest = `${WAVE_DB_PATH}.cctabs-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
+	copyFileSync(WAVE_DB_PATH, dest);
+	return dest;
+}
+/** Surgically strip orphan tabids from a workspace's tabids array.
+*
+* SQLite's json_remove evaluates each path against the *previous* result, so
+* we delete by descending index — that way each removal doesn't shift later
+* indices out from under us.
+*/
+function removeOrphanTabIds(report) {
+	if (!report.orphanTabIds.length) return;
+	const r = spawnSync("sqlite3", [WAVE_DB_PATH, `UPDATE db_workspace SET data = json_set(data, '$.tabids', json('${JSON.stringify(report.presentTabIds).replace(/'/g, "''")}')) WHERE oid = '${report.workspaceId}';`], { encoding: "utf-8" });
+	if (r.status !== 0) throw new Error(`sqlite3 update failed (status ${r.status}): ${r.stderr?.trim() || "unknown error"}`);
+}
+//#endregion
 //#region src/core/wave.ts
+var WaveOrphanTabidError = class extends Error {
+	reports;
+	wshStderr;
+	constructor(reports, wshStderr) {
+		const lines = [
+			"Wave Terminal's block listing aborted: a workspace's tabids list references a tab that no longer exists in db_tab.",
+			"wsh stderr: " + wshStderr.trim(),
+			"",
+			"Affected workspaces:",
+			...reports.map((r) => `  • "${r.workspaceName}" [${r.workspaceId.slice(0, 8)}] — ${r.orphanTabIds.length} orphan tabid(s): ${r.orphanTabIds.map((t) => t.slice(0, 8)).join(", ")}`),
+			"",
+			"Run `cctabs doctor` to back up the Wave DB and apply the fix."
+		];
+		super(lines.join("\n"));
+		this.name = "WaveOrphanTabidError";
+		this.reports = reports;
+		this.wshStderr = wshStderr;
+	}
+};
 const SOCK_PATH = join(homedir(), "Library", "Application Support", "waveterm", "wave.sock");
 var WaveSocket = class {
 	socket;
@@ -198,6 +285,7 @@ var WaveSocket = class {
 var WaveAdapter = class {
 	socket = null;
 	jwt;
+	lastBlocksListStderr = "";
 	constructor() {
 		this.jwt = process.env.WAVETERM_JWT ?? "";
 	}
@@ -211,13 +299,27 @@ var WaveAdapter = class {
 			"15000"
 		];
 		if (wsId) args.push("--workspace", wsId);
+		const r = spawnSync("wsh", args, { encoding: "utf-8" });
+		this.lastBlocksListStderr = r.stderr ?? "";
+		if (r.status !== 0 || !r.stdout?.trim()) return [];
 		try {
-			const out = execFileSync("wsh", args, { encoding: "utf-8" });
-			return JSON.parse(out);
+			return JSON.parse(r.stdout);
 		} catch {
 			return [];
 		}
 	}
+	/** If the most recent blocksList() looked like it hit Wave's orphan-tabid
+	* abort, run a sqlite3 self-check to confirm. Returns reports when orphans
+	* are found, otherwise null. */
+	diagnoseOrphanTabids() {
+		const stderr = this.lastBlocksListStderr;
+		if (!stderr || !WSH_ORPHAN_TABID_PATTERN.test(stderr)) return null;
+		const reports = findOrphanTabIds();
+		return reports.length ? reports : null;
+	}
+	getLastBlocksListStderr() {
+		return this.lastBlocksListStderr;
+	}
 	scrollback(blockId, lastN = 50) {
 		return spawnSync("wsh", [
 			"termscrollback",
@@ -233,7 +335,7 @@ var WaveAdapter = class {
 	async confirmScrollbackEmpty(blockId, attempts = 3, intervalMs = 500) {
 		for (let i = 0; i < attempts; i++) {
 			if (this.scrollback(blockId, 10).trim()) return false;
-			if (i < attempts - 1) await sleep(intervalMs);
+			if (i < attempts - 1) await sleep$1(intervalMs);
 		}
 		return true;
 	}
@@ -263,7 +365,7 @@ var WaveAdapter = class {
 	async newTab(focusWindowId) {
 		if (focusWindowId) {
 			await this.focusWindow(focusWindowId);
-			await sleep(300);
+			await sleep$1(300);
 		}
 		const r = spawnSync("osascript", ["-e", [
 			"tell application \"Wave\" to activate",
@@ -279,7 +381,7 @@ var WaveAdapter = class {
 	async waitForNewBlock(beforeIds, timeoutMs = 15e3) {
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() < deadline) {
-			await sleep(250);
+			await sleep$1(250);
 			for (const b of this.blocksList()) if (b.view === "term" && !beforeIds.has(b.blockid)) return {
 				blockId: b.blockid,
 				tabId: b.tabid
@@ -321,6 +423,13 @@ var WaveAdapter = class {
 	}
 	async getAllData() {
 		const blocks = this.blocksList();
+		if (!blocks.length) {
+			const orphans = this.diagnoseOrphanTabids();
+			if (orphans) {
+				this.closeSocket();
+				throw new WaveOrphanTabidError(orphans, this.lastBlocksListStderr);
+			}
+		}
 		const tabsById = /* @__PURE__ */ new Map();
 		for (const b of blocks) {
 			const arr = tabsById.get(b.tabid) ?? [];
@@ -379,6 +488,15 @@ var WaveAdapter = class {
 	resolveBlock(query, blocks) {
 		return blocks.filter((b) => b.blockid.startsWith(query));
 	}
+	currentTabId() {
+		return process.env.WAVETERM_TABID ?? "";
+	}
+	currentBlockId() {
+		return process.env.WAVETERM_BLOCKID ?? "";
+	}
+	currentWorkspaceId() {
+		return process.env.WAVETERM_WORKSPACEID ?? "";
+	}
 	resolveWorkspace(workspaces, query) {
 		const q = query.toLowerCase();
 		const exact = workspaces.filter(({ workspacedata: wd }) => (wd.name ?? "").toLowerCase() === q);
@@ -391,16 +509,315 @@ var WaveAdapter = class {
 		}));
 	}
 };
-function requireWaveAdapter() {
-	if (!process.env.WAVETERM_JWT) {
-		printUnsupportedTerminalError(detectTerminal());
-		process.exit(1);
-	}
-	return new WaveAdapter();
+function sleep$1(ms) {
+	return new Promise((r) => setTimeout(r, ms));
 }
+//#endregion
+//#region src/core/tabby.ts
+/**
+* Thrown when the cctabs Tabby plugin's HTTP API is unreachable.
+*
+* Failing loud here matters: if we silently returned empty data the
+* caller would conclude "no tabs" and act on it. The CLI's outer error
+* handler renders this with the install hint.
+*/
+var TabbyPluginUnreachableError = class extends Error {
+	constructor(host, port, underlying) {
+		const lines = [
+			`cctabs Tabby plugin not reachable at http://${host}:${port}.`,
+			underlying ? `  reason: ${underlying}` : "",
+			"",
+			"Install + restart Tabby in one shot from inside a Tabby tab:",
+			"  cctabs install-tabby-plugin",
+			"",
+			"Or do it by hand:",
+			`  npm install --legacy-peer-deps --prefix "$HOME/Library/Application Support/tabby/plugins" tabby-cctabs`,
+			"  # then quit Tabby (Cmd+Q) and reopen it.",
+			"",
+			"Verify with: cctabs doctor"
+		].filter(Boolean);
+		super(lines.join("\n"));
+		this.host = host;
+		this.port = port;
+		this.underlying = underlying;
+		this.name = "TabbyPluginUnreachableError";
+	}
+};
+/**
+* cctabs adapter for Tabby Terminal. Talks to the tabby-cctabs
+* plugin's HTTP API (default 127.0.0.1:3300).
+*
+* Tab identity: cctabs (running inside a Tabby tab) walks its own
+* process.pid → ppid chain via `ps`, POSTs the PID list to
+* /api/tabs/identify, and caches the resulting plugin UUID.
+*
+* In Tabby's data model there are no Wave-style "workspaces" or "blocks";
+* we project a single synthetic workspace and a 1:1 tab↔block mapping so
+* the rest of cctabs sees the same shape it does on Wave.
+*/
+var TabbyAdapter = class {
+	host;
+	port;
+	cachedSelfUuid = null;
+	healthChecked = false;
+	constructor() {
+		this.host = process.env.CCTABS_TABBY_HOST ?? "127.0.0.1";
+		this.port = Number(process.env.CCTABS_TABBY_PORT ?? "3300");
+	}
+	/**
+	* One-shot health check. Throws TabbyPluginUnreachableError on the
+	* first call if /api/health is unreachable. Subsequent calls are no-ops
+	* — once we've confirmed the plugin is up, we trust it for this process.
+	*/
+	ensureHealthy() {
+		if (this.healthChecked) return;
+		const r = spawnSync("curl", [
+			"-fsS",
+			"--max-time",
+			"3",
+			this.url("/api/health")
+		], { encoding: "utf-8" });
+		if (r.status !== 0 || !r.stdout) {
+			const reason = (r.stderr || "").trim() || `curl exit ${r.status}`;
+			throw new TabbyPluginUnreachableError(this.host, this.port, reason);
+		}
+		this.healthChecked = true;
+	}
+	url(path) {
+		return `http://${this.host}:${this.port}${path}`;
+	}
+	async http(method, path, body) {
+		const res = await fetch(this.url(path), {
+			method,
+			headers: body ? { "content-type": "application/json" } : void 0,
+			body: body ? JSON.stringify(body) : void 0
+		});
+		if (res.status === 404) return null;
+		if (!res.ok) throw new Error(`Tabby plugin ${method} ${path} failed: ${res.status}`);
+		return res.json();
+	}
+	closeSocket() {}
+	blocksList() {
+		this.ensureHealthy();
+		const out = spawnSync("curl", [
+			"-fsS",
+			"--max-time",
+			"5",
+			this.url("/api/tabs")
+		], { encoding: "utf-8" });
+		if (out.status !== 0 || !out.stdout) return [];
+		let parsed;
+		try {
+			parsed = JSON.parse(out.stdout);
+		} catch {
+			return [];
+		}
+		return parsed.tabs.filter((t) => t.type === "terminal").map((t) => ({
+			blockid: t.uuid,
+			tabid: t.uuid,
+			view: "term",
+			meta: t.cwd ? { "cmd:cwd": t.cwd } : void 0
+		}));
+	}
+	scrollback(blockId, lastN = 50) {
+		const out = spawnSync("curl", [
+			"-fsS",
+			"--max-time",
+			"5",
+			this.url(`/api/tabs/${blockId}/buffer?lines=${lastN}`)
+		], { encoding: "utf-8" });
+		if (out.status !== 0 || !out.stdout) return "";
+		try {
+			return JSON.parse(out.stdout).lines.join("\n");
+		} catch {
+			return "";
+		}
+	}
+	async confirmScrollbackEmpty(blockId, attempts = 3, intervalMs = 500) {
+		for (let i = 0; i < attempts; i++) {
+			if (this.scrollback(blockId, 10).trim()) return false;
+			if (i < attempts - 1) await sleep(intervalMs);
+		}
+		return true;
+	}
+	detectSessionStatus(blockId) {
+		const tail = this.scrollback(blockId, 10);
+		if (!tail.trim()) return "unknown";
+		const lastLine = tail.split("\n").map((l) => l.trim()).filter(Boolean).at(-1) ?? "";
+		if (/[$%>]\s*$/.test(lastLine) && !lastLine.includes("claude")) return "terminal";
+		if ([
+			"Claude Code",
+			"claude.ai/code",
+			"✻ Thinking",
+			"✽ Hatching",
+			"⏵⏵ bypass"
+		].some((s) => tail.includes(s))) return "active";
+		if (lastLine.toLowerCase().includes("claude")) return "idle";
+		return "terminal";
+	}
+	deleteBlock(blockId) {
+		spawnSync("curl", [
+			"-fsS",
+			"-X",
+			"POST",
+			"--max-time",
+			"5",
+			this.url(`/api/tabs/${blockId}/close`)
+		], { encoding: "utf-8" });
+	}
+	async newTab(_focusWindowId) {
+		const r = await this.http("POST", "/api/tabs/new", {});
+		return Boolean(r);
+	}
+	async waitForNewBlock(beforeIds, timeoutMs = 15e3) {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			await sleep(250);
+			for (const b of this.blocksList()) if (!beforeIds.has(b.blockid)) return {
+				blockId: b.blockid,
+				tabId: b.tabid
+			};
+		}
+		return null;
+	}
+	async renameTab(tabId, name) {
+		await this.http("PUT", `/api/tabs/${tabId}/title`, { title: name });
+	}
+	async sendInput(blockId, text) {
+		return this.http("POST", `/api/tabs/${blockId}/send`, { data: text });
+	}
+	async getAllData() {
+		const blocks = this.blocksList();
+		const tabsById = /* @__PURE__ */ new Map();
+		for (const b of blocks) {
+			const arr = tabsById.get(b.tabid) ?? [];
+			arr.push(b);
+			tabsById.set(b.tabid, arr);
+		}
+		const tabNames = /* @__PURE__ */ new Map();
+		try {
+			const res = await fetch(this.url("/api/tabs"));
+			if (res.ok) {
+				const data = await res.json();
+				for (const t of data.tabs) tabNames.set(t.uuid, t.customTitle || t.title || t.uuid.slice(0, 8));
+			}
+		} catch {}
+		return {
+			blocks,
+			tabsById,
+			workspaces: [{
+				workspacedata: {
+					oid: "tabby",
+					name: "tabby",
+					tabids: [...tabsById.keys()]
+				},
+				windowid: ""
+			}],
+			tabNames
+		};
+	}
+	resolveTab(query, tabsById, tabNames) {
+		const q = query.toLowerCase();
+		if (query === "." || query === "self") {
+			const self = this.identifySelf();
+			return self ? [self] : [];
+		}
+		const ids = [...tabsById.keys()];
+		const exact = ids.filter((tid) => (tabNames.get(tid) ?? "").toLowerCase() === q);
+		if (exact.length > 0) return exact;
+		return ids.filter((tid) => {
+			const name = tabNames.get(tid) ?? "";
+			return tid.startsWith(query) || name.toLowerCase().startsWith(q);
+		});
+	}
+	resolveBlock(query, blocks) {
+		return blocks.filter((b) => b.blockid.startsWith(query));
+	}
+	resolveWorkspace(workspaces, _query) {
+		return workspaces.map((w) => ({
+			data: w.workspacedata,
+			windowId: w.windowid
+		}));
+	}
+	currentTabId() {
+		return this.identifySelf() ?? "";
+	}
+	currentBlockId() {
+		return this.currentTabId();
+	}
+	currentWorkspaceId() {
+		return "tabby";
+	}
+	/**
+	* Walk the process tree from `process.pid` upwards collecting PIDs, then
+	* ask the plugin which tab owns any of them. Result is cached for the
+	* lifetime of this adapter.
+	*/
+	identifySelf() {
+		if (this.cachedSelfUuid !== null) return this.cachedSelfUuid;
+		const pids = walkAncestorPids(process.pid);
+		const out = spawnSync("curl", [
+			"-fsS",
+			"-X",
+			"POST",
+			"-H",
+			"content-type: application/json",
+			"--max-time",
+			"5",
+			"--data",
+			JSON.stringify({ pids }),
+			this.url("/api/tabs/identify")
+		], { encoding: "utf-8" });
+		if (out.status !== 0 || !out.stdout) {
+			this.cachedSelfUuid = "";
+			return null;
+		}
+		try {
+			const parsed = JSON.parse(out.stdout);
+			this.cachedSelfUuid = parsed.uuid ?? "";
+			return parsed.uuid ?? null;
+		} catch {
+			this.cachedSelfUuid = "";
+			return null;
+		}
+	}
+};
 function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
+/**
+* Walk `pid → ppid → ...` via `ps`. Caps at 32 levels to avoid pathological
+* loops on misconfigured systems. Returns [pid, ppid, gppid, ...].
+*/
+function walkAncestorPids(startPid, cap = 32) {
+	const out = [startPid];
+	let cur = startPid;
+	for (let i = 0; i < cap; i++) {
+		const r = spawnSync("ps", [
+			"-o",
+			"ppid=",
+			"-p",
+			String(cur)
+		], { encoding: "utf-8" });
+		if (r.status !== 0) break;
+		const next = parseInt(r.stdout.trim(), 10);
+		if (!Number.isFinite(next) || next <= 1 || next === cur) break;
+		out.push(next);
+		cur = next;
+	}
+	return out;
+}
+//#endregion
+//#region src/core/adapter.ts
+/** Returns the adapter that matches the running terminal. Exits with a clear
+* error message if none is supported. */
+function requireAdapter() {
+	const terminal = detectTerminal();
+	if (terminal === "wave") return new WaveAdapter();
+	if (terminal === "tabby") return new TabbyAdapter();
+	printUnsupportedTerminalError(terminal);
+	process.exit(1);
+}
 //#endregion
 //#region src/commands/sessions.ts
 const sessionsCommand = define({
@@ -408,10 +825,10 @@ const sessionsCommand = define({
 	description: "List tabs with active/idle session status",
 	args: {},
 	async run() {
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, workspaces, tabNames } = await adapter.getAllData();
-		const currentTab = process.env.WAVETERM_TABID ?? "";
-		const currentWs = process.env.WAVETERM_WORKSPACEID ?? "";
+		const currentTab = adapter.currentTabId();
+		const currentWs = adapter.currentWorkspaceId();
 		console.log("Sessions");
 		console.log("=".repeat(50));
 		for (const wsp of workspaces) {
@@ -446,10 +863,11 @@ const listCommand = define({
 	description: "List all workspaces, tabs, and blocks",
 	args: {},
 	async run() {
-		const { tabsById, workspaces, tabNames } = await requireWaveAdapter().getAllData();
-		const currentBlock = process.env.WAVETERM_BLOCKID ?? "";
-		const currentTab = process.env.WAVETERM_TABID ?? "";
-		const currentWs = process.env.WAVETERM_WORKSPACEID ?? "";
+		const adapter = requireAdapter();
+		const { tabsById, workspaces, tabNames } = await adapter.getAllData();
+		const currentBlock = adapter.currentBlockId();
+		const currentTab = adapter.currentTabId();
+		const currentWs = adapter.currentWorkspaceId();
 		for (const wsp of workspaces) {
 			const { oid, name, tabids } = wsp.workspacedata;
 			const noWindow = !wsp.windowid ? "  (no window)" : "";
@@ -566,7 +984,7 @@ async function openSession(opts) {
 		process.exit(1);
 	}
 	const config = loadConfig();
-	const adapter = requireWaveAdapter();
+	const adapter = requireAdapter();
 	let focusWindowId;
 	if (workspaceQuery) {
 		const { workspaces } = await adapter.getAllData();
@@ -1207,7 +1625,7 @@ const resumeCommand = define({
 				process.exit(1);
 			}
 		}
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const matchingTabs = adapter.resolveTab(name, tabsById, tabNames);
 		if (matchingTabs.length > 1) {
@@ -1329,7 +1747,7 @@ const forkCommand = define({
 			consola.error("Source tab name is required");
 			process.exit(1);
 		}
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const matches = adapter.resolveTab(sourceQuery, tabsById, tabNames);
 		if (!matches.length) {
@@ -1380,7 +1798,7 @@ const closeCommand = define({
 			consola.error("Tab name or ID is required");
 			process.exit(1);
 		}
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const matches = adapter.resolveTab(query, tabsById, tabNames);
 		if (!matches.length) {
@@ -1421,7 +1839,7 @@ const renameCommand = define({
 			consola.error("Usage: cctabs rename <tab> <new-name>");
 			process.exit(1);
 		}
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const matches = adapter.resolveTab(query, tabsById, tabNames);
 		if (!matches.length) {
@@ -1462,7 +1880,7 @@ const scrollbackCommand = define({
 			consola.error("Tab name or block ID is required");
 			process.exit(1);
 		}
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const tabMatches = adapter.resolveTab(query, tabsById, tabNames);
 		let blockId;
@@ -1536,7 +1954,7 @@ const sendCommand = define({
 		else if (filePath) rawText = readFileSync(filePath, "utf-8").replace(/\n/g, "\r");
 		else rawText = (await readStdin()).replace(/\n/g, "\r");
 		if (appendEnter && !rawText.endsWith("\r")) rawText += "\r";
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const tabMatches = adapter.resolveTab(query, tabsById, tabNames);
 		let blockId;
@@ -1604,9 +2022,9 @@ const restoreCommand = define({
 		const rawDir = ctx.positionals[1];
 		const scopedDir = rawDir ? resolve(rawDir.replace(/^~/, homedir())) : null;
 		const dryRun = ctx.values.dry;
-		const adapter = requireWaveAdapter();
+		const adapter = requireAdapter();
 		const { tabsById, workspaces, tabNames } = await adapter.getAllData();
-		const currentTab = process.env.WAVETERM_TABID ?? "";
+		const currentTab = adapter.currentTabId();
 		const tabs = [];
 		for (const wsp of workspaces) for (const tabId of wsp.workspacedata.tabids) {
 			if (tabId === currentTab) continue;
@@ -1754,6 +2172,341 @@ const backendsCommand = define({
 	}
 });
 //#endregion
+//#region src/commands/doctor.ts
+const STATUS_GLYPH = {
+	ok: "✔",
+	warn: "⚠",
+	fail: "✘",
+	skip: "–"
+};
+function printResult(r) {
+	const line = `  ${STATUS_GLYPH[r.status]}  ${r.name}${r.detail ? " — " + r.detail : ""}`;
+	console.log(line);
+	if (r.hint) console.log(`       ↳ ${r.hint}`);
+}
+function checkTerminal(terminal) {
+	if (terminal === "wave" || terminal === "tabby") return {
+		name: "Terminal",
+		status: "ok",
+		detail: terminal
+	};
+	return {
+		name: "Terminal",
+		status: "fail",
+		detail: terminal === "unknown" ? "unrecognised" : terminal,
+		hint: "cctabs supports Wave Terminal and Tabby. Switch to one of those."
+	};
+}
+function checkWaveAccessibility() {
+	const r = spawnSync("osascript", ["-e", "tell application \"System Events\" to count processes"], {
+		encoding: "utf-8",
+		timeout: 2e3
+	});
+	const stderr = (r.stderr ?? "").trim();
+	if (r.status === 0) return {
+		name: "Wave Accessibility permission",
+		status: "ok"
+	};
+	if (stderr.includes("not allowed") || stderr.includes("1002") || stderr.includes("-1719")) return {
+		name: "Wave Accessibility permission",
+		status: "fail",
+		detail: "osascript denied",
+		hint: "System Settings → Privacy & Security → Accessibility → enable Wave Terminal"
+	};
+	return {
+		name: "Wave Accessibility permission",
+		status: "warn",
+		detail: stderr || `osascript exit ${r.status}`,
+		hint: "Could not verify automatically. If `cctabs new` errors, check Privacy & Security → Accessibility."
+	};
+}
+function probeTabbyPlugin(host, port) {
+	const r = spawnSync("curl", [
+		"-fsS",
+		"--max-time",
+		"3",
+		`http://${host}:${port}/api/health`
+	], { encoding: "utf-8" });
+	if (r.status !== 0 || !r.stdout) return {
+		ok: false,
+		error: (r.stderr || "").trim() || `exit ${r.status}`
+	};
+	try {
+		const parsed = JSON.parse(r.stdout);
+		return {
+			ok: !!parsed.ok,
+			version: parsed.version,
+			raw: r.stdout
+		};
+	} catch {
+		return {
+			ok: false,
+			error: "non-JSON response",
+			raw: r.stdout
+		};
+	}
+}
+function checkTabbyPlugin() {
+	const host = process.env.CCTABS_TABBY_HOST ?? "127.0.0.1";
+	const port = Number(process.env.CCTABS_TABBY_PORT ?? "3300");
+	const health = probeTabbyPlugin(host, port);
+	if (health.ok) return {
+		name: "Tabby cctabs plugin",
+		status: "ok",
+		detail: `${host}:${port}, version ${health.version ?? "unknown"}`
+	};
+	return {
+		name: "Tabby cctabs plugin",
+		status: "fail",
+		detail: `${host}:${port} unreachable (${health.error ?? "unknown"})`,
+		hint: "Run `cctabs install-tabby-plugin` from inside a Tabby tab — it npm-installs the plugin and reopens Tabby. Or do it by hand: `npm install --legacy-peer-deps --prefix \"$HOME/Library/Application Support/tabby/plugins\" tabby-cctabs`, then quit + reopen Tabby."
+	};
+}
+function checkWaveDb() {
+	if (!existsSync(WAVE_DB_PATH)) return { result: {
+		name: "Wave DB",
+		status: "skip",
+		detail: "not found — Wave Terminal not installed?"
+	} };
+	let reports;
+	try {
+		reports = findOrphanTabIds();
+	} catch (err) {
+		return { result: {
+			name: "Wave DB orphan-tabid scan",
+			status: "fail",
+			detail: err.message,
+			hint: "sqlite3 CLI must be on PATH (ships with macOS by default)."
+		} };
+	}
+	if (!reports.length) return { result: {
+		name: "Wave DB orphan-tabid scan",
+		status: "ok",
+		detail: "no orphans"
+	} };
+	return {
+		result: {
+			name: "Wave DB orphan-tabid scan",
+			status: "warn",
+			detail: `${reports.length} workspace(s) affected`,
+			hint: "Run `cctabs doctor --fix` (after quitting Wave) to clean up."
+		},
+		reports
+	};
+}
+async function fixWaveDb(reports, yes) {
+	console.log("");
+	consola.warn(`${reports.length} workspace(s) with orphan tabids:`);
+	for (const r of reports) {
+		console.log(`  • "${r.workspaceName}" [${r.workspaceId.slice(0, 8)}]`);
+		console.log(`      present: ${r.presentTabIds.length} tab(s)`);
+		console.log(`      orphan : ${r.orphanTabIds.length} tabid(s) → ${r.orphanTabIds.map((t) => t.slice(0, 8)).join(", ")}`);
+	}
+	console.log("");
+	console.log("These tabids point at rows that no longer exist in db_tab. Wave's");
+	console.log("BlocksList RPC aborts on the first missing tab, so `wsh blocks list`");
+	console.log("currently fails with: \"couldn't list blocks for workspace …: not found\".");
+	console.log("");
+	console.log("Fix steps:");
+	console.log("  1. Copy the Wave DB to a timestamped backup next to it.");
+	console.log("  2. For each affected workspace, rewrite `data.tabids` to drop the orphan IDs.");
+	console.log("  3. Leave Wave's db_tab untouched.");
+	console.log("");
+	console.log("IMPORTANT: Quit Wave Terminal first — otherwise Wave may overwrite the");
+	console.log("fix on its next save. (Cmd+Q on the Wave app, then re-run this command.)");
+	console.log("");
+	let proceed = yes;
+	if (!yes) {
+		const ans = await p.confirm({
+			message: "Apply the fix now?",
+			initialValue: false
+		});
+		if (p.isCancel(ans)) {
+			consola.info("Cancelled.");
+			return;
+		}
+		proceed = Boolean(ans);
+	}
+	if (!proceed) {
+		consola.info("Aborted. No changes made.");
+		return;
+	}
+	const backup = backupWaveDb();
+	consola.success(`Backup written: ${backup}`);
+	for (const r of reports) try {
+		removeOrphanTabIds(r);
+		consola.success(`Cleaned "${r.workspaceName}" [${r.workspaceId.slice(0, 8)}] — removed ${r.orphanTabIds.length} orphan tabid(s)`);
+	} catch (err) {
+		consola.error(`Failed to clean ${r.workspaceId}: ${err.message}`);
+		consola.info(`Restore from backup if anything looks wrong: cp ${JSON.stringify(backup)} ${JSON.stringify(WAVE_DB_PATH)}`);
+		process.exit(1);
+	}
+	consola.success("All orphan tabids removed. Start Wave Terminal again and re-run `cctabs sessions`.");
+}
+const doctorCommand = define({
+	name: "doctor",
+	description: "Run environment checks (terminal detection, plugin reachability, Wave DB orphan scan, Wave Accessibility) and offer fixes for known problems.",
+	args: {
+		yes: {
+			type: "boolean",
+			short: "y",
+			description: "Apply the fix without an interactive confirmation prompt"
+		},
+		fix: {
+			type: "boolean",
+			description: "Apply available fixes (currently: Wave DB orphan-tabids)"
+		}
+	},
+	async run(ctx) {
+		const yes = Boolean(ctx.values.yes);
+		const fix = Boolean(ctx.values.fix) || yes;
+		const terminal = detectTerminal();
+		console.log("cctabs doctor — environment checks");
+		console.log("─".repeat(40));
+		const results = [];
+		let waveDb = null;
+		results.push(checkTerminal(terminal));
+		if (terminal === "tabby") results.push(checkTabbyPlugin());
+		if (terminal === "wave") {
+			results.push(checkWaveAccessibility());
+			waveDb = checkWaveDb();
+			results.push(waveDb.result);
+		} else if (existsSync(WAVE_DB_PATH)) {
+			waveDb = checkWaveDb();
+			results.push({
+				...waveDb.result,
+				name: "Wave DB orphan-tabid scan (offline)"
+			});
+		}
+		for (const r of results) printResult(r);
+		const failed = results.some((r) => r.status === "fail");
+		const orphans = waveDb?.reports ?? [];
+		if (orphans.length && fix) await fixWaveDb(orphans, yes);
+		else if (orphans.length) {
+			console.log("");
+			consola.info("Re-run with `cctabs doctor --fix` to clean up orphan tabids (a DB backup is made first).");
+		}
+		if (failed) process.exit(1);
+	}
+});
+//#endregion
+//#region src/commands/install-tabby-plugin.ts
+function pluginsDir() {
+	if (platform() === "darwin") return join(homedir(), "Library", "Application Support", "tabby", "plugins");
+	if (platform() === "linux") return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "tabby", "plugins");
+	if (platform() === "win32") return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "tabby", "plugins");
+	throw new Error(`unsupported platform: ${platform()}`);
+}
+function shellQuote(s) {
+	return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+const installTabbyPluginCommand = define({
+	name: "install-tabby-plugin",
+	description: "Install the tabby-cctabs plugin via npm, then quit + reopen Tabby in the background and resume the current claude session in a new tab. Must be run from inside Tabby.",
+	args: {
+		yes: {
+			type: "boolean",
+			short: "y",
+			description: "Skip the \"this will restart Tabby\" confirmation"
+		},
+		"no-restart": {
+			type: "boolean",
+			description: "Install the plugin only; do not quit Tabby. You restart it yourself."
+		}
+	},
+	async run(ctx) {
+		const yes = Boolean(ctx.values.yes);
+		const noRestart = Boolean(ctx.values["no-restart"]);
+		if (detectTerminal() !== "tabby") {
+			consola.error("cctabs install-tabby-plugin must be run from inside a Tabby tab.");
+			consola.info("On Wave Terminal you don't need this — Wave works without a plugin.");
+			process.exit(1);
+		}
+		if (platform() !== "darwin" && platform() !== "linux") {
+			consola.error(`Auto-restart isn't implemented for ${platform()} yet. Run the manual install snippet from \`cctabs doctor\` and restart Tabby yourself.`);
+			process.exit(1);
+		}
+		const dir = pluginsDir();
+		consola.info(`Tabby plugins dir: ${dir}`);
+		mkdirSync(dir, { recursive: true });
+		const pkgPath = join(dir, "package.json");
+		if (!existsSync(pkgPath)) writeFileSync(pkgPath, "{\"private\":true}\n");
+		consola.info("Installing tabby-cctabs from npm…");
+		const npm = spawnSync("npm", [
+			"install",
+			"--legacy-peer-deps",
+			"--silent",
+			"--prefix",
+			dir,
+			"tabby-cctabs"
+		], { stdio: "inherit" });
+		if (npm.status !== 0) {
+			consola.error("npm install failed. Bail out before touching Tabby.");
+			process.exit(npm.status ?? 1);
+		}
+		consola.success("Plugin installed.");
+		if (noRestart) {
+			consola.info("Skipping restart (--no-restart). Quit and reopen Tabby manually, then run `cctabs doctor`.");
+			return;
+		}
+		const cwd = process.cwd();
+		const sessionId = findLatestSessionId(cwd);
+		if (!sessionId) consola.warn(`No prior Claude session found for ${cwd}. The restart will reopen Tabby with a plain shell tab; you can launch claude yourself.`);
+		else consola.info(`Will resume session ${sessionId.slice(0, 8)}… via --fork-session after restart.`);
+		if (!yes) {
+			consola.warn("About to quit Tabby and reopen it. ALL Tabby tabs will close.");
+			consola.warn("Tabby's session recovery may or may not restore other tabs.");
+			consola.info("Re-run with --yes to suppress this prompt.");
+			if (!await consola.prompt("Proceed?", {
+				type: "confirm",
+				initial: false
+			})) {
+				consola.info("Aborted.");
+				return;
+			}
+		}
+		const claudeBin = (spawnSync("which", ["claude"], { encoding: "utf-8" }).stdout || "").trim() || "claude";
+		const stamp = Date.now();
+		const restartScript = join("/tmp", `cctabs-tabby-restart-${stamp}.sh`);
+		const launcherScript = join("/tmp", `cctabs-tabby-launcher-${stamp}.sh`);
+		writeFileSync(launcherScript, sessionId ? `#!/bin/zsh -l
+cd ${shellQuote(cwd)} || exit 1
+exec ${claudeBin} --resume ${sessionId} --fork-session
+` : `#!/bin/zsh -l
+cd ${shellQuote(cwd)} || exit 1
+exec /bin/zsh -l
+`);
+		chmodSync(launcherScript, 493);
+		const isDarwin = platform() === "darwin";
+		writeFileSync(restartScript, `#!/usr/bin/env bash
+set -e
+exec >/tmp/cctabs-tabby-restart-${stamp}.log 2>&1
+echo "[$(date)] sleeping 2s before quitting Tabby"
+sleep 2
+echo "[$(date)] quitting Tabby"
+${isDarwin ? `osascript -e 'tell application "Tabby" to quit' >/dev/null 2>&1 || true` : `pkill -TERM -f Tabby || true`}
+echo "[$(date)] waiting for Tabby to exit"
+for i in \$(seq 1 30); do pgrep -f "Tabby" >/dev/null || break; sleep 0.5; done
+echo "[$(date)] reopening Tabby"
+${isDarwin ? `open -a Tabby` : `nohup tabby >/dev/null 2>&1 &`}
+sleep 5
+echo "[$(date)] activating + launching resume tab"
+${isDarwin ? `osascript -e 'tell application "Tabby" to activate' >/dev/null 2>&1 || true` : `:`}
+sleep 1
+${isDarwin ? `/Applications/Tabby.app/Contents/MacOS/Tabby` : `tabby`} run ${shellQuote(launcherScript)}
+echo "[$(date)] done"
+`);
+		chmodSync(restartScript, 493);
+		spawn("/bin/bash", [restartScript], {
+			detached: true,
+			stdio: "ignore"
+		}).unref();
+		consola.success("Restart worker dispatched.");
+		consola.info(`Logs: /tmp/cctabs-tabby-restart-${stamp}.log`);
+		consola.info("Tabby will quit in ~2 seconds. After it reopens, your session resumes via --fork-session in a new tab.");
+	}
+});
+//#endregion
 //#region src/commands/index.ts
 const defaultCommand = define({
 	name: "cctabs",
@@ -1776,7 +2529,9 @@ const subCommands = new Map([
 	["send", sendCommand],
 	["config", configCommand],
 	["restore", restoreCommand],
-	["backends", backendsCommand]
+	["backends", backendsCommand],
+	["doctor", doctorCommand],
+	["install-tabby-plugin", installTabbyPluginCommand]
 ]);
 async function run() {
 	await cli(process.argv.slice(2), defaultCommand, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/cctabs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {
@@ -19,6 +19,8 @@
     "check": "npm run typecheck && npm run build",
     "release": "bumpp && npm publish",
     "sync-plugin": "bash scripts/sync-plugin.sh",
+    "build:tabby-plugin": "cd tabby-plugin && npm install && npm run build",
+    "publish:tabby-plugin": "cd tabby-plugin && npm publish --access public",
     "prepack": "bash scripts/sync-plugin.sh --check && npm run build"
   },
   "keywords": [

package/skills/cctabs/SKILL.md

@@ -5,7 +5,7 @@ description: Manage Claude Code sessions across terminal tabs (NOT browser tabs)
 
 You are managing Claude Code sessions using the `cctabs` CLI.
 
-**Important:** "tabs" here means **terminal tabs** (e.g. Wave Terminal tabs), NOT browser tabs. Each terminal tab runs its own Claude Code session. This skill is for managing those terminal-based Claude Code sessions — not for browser automation.
+**Important:** "tabs" here means **terminal tabs** (Wave Terminal or Tabby), NOT browser tabs. Each terminal tab runs its own Claude Code session. This skill is for managing those terminal-based Claude Code sessions — not for browser automation.
 
 ## Before you spawn anything: is cctabs the right tool?
 
@@ -37,6 +37,64 @@ npm install -g @generativereality/cctabs
 
 Do not modify PATH or npm configuration beyond this.
 
+### 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.
+
+You don't need to detect this proactively — every cctabs command will fail with a self-documenting error if the plugin isn't running:
+
+```
+cctabs Tabby plugin not reachable at http://127.0.0.1:3300.
+  reason: …
+Install + restart Tabby in one shot from inside a Tabby tab:
+  cctabs install-tabby-plugin
+…
+```
+
+When you see that error, ask the user once:
+
+> *"You're in Tabby and the cctabs plugin isn't installed. I can `cctabs install-tabby-plugin --yes` — that npm-installs the plugin AND restarts Tabby in the background, dropping you back into a forked session. Caveat: any other Tabby tabs you have open will be killed. OK?"*
+
+On approval, run `cctabs install-tabby-plugin --yes`. Tabby quits ~2s after the command returns, reopens automatically, and spawns a new tab with your forked claude session. **Your current turn ends when Tabby quits**; the resumed claude in the new tab is where the user will continue.
+
+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.
+
+#### Auto-install + auto-restart (recommended)
+
+```bash
+cctabs install-tabby-plugin --yes
+```
+
+What it does, in order:
+1. `npm install --legacy-peer-deps --prefix <tabby-plugins-dir> tabby-cctabs`
+2. Captures the current claude session id from `~/.claude/projects/<slug>/`
+3. Spawns a detached background worker that quits Tabby, waits for it to die, reopens it, then opens a new tab running `claude --resume <id> --fork-session` in your current cwd.
+
+**Other Tabby tabs in the same window get killed.** Tabby's session recovery may or may not bring them back. Use `--no-restart` to skip step 3 if the user wants control.
+
+#### Manual install (fallback)
+
+```bash
+TABBY_PLUGINS="$HOME/Library/Application Support/tabby/plugins"
+mkdir -p "$TABBY_PLUGINS"
+[ -f "$TABBY_PLUGINS/package.json" ] || echo '{"private":true}' > "$TABBY_PLUGINS/package.json"
+npm install --legacy-peer-deps --prefix "$TABBY_PLUGINS" tabby-cctabs
+# then ask the user to quit + reopen Tabby
+```
+
+`--legacy-peer-deps` is required: the plugin's peer deps (`tabby-core`, `@angular/*`, …) live inside Tabby itself, not on npm. Tabby's GUI plugin manager handles this internally.
+
+Linux: replace `~/Library/Application Support/tabby` with `${XDG_CONFIG_HOME:-$HOME/.config}/tabby`.
+Windows: `%APPDATA%\tabby`.
+
+#### Alternative: install via Tabby's GUI
+
+If the user prefers, point them at Tabby → **Settings → Plugins**, search "cctabs", click install, then quit + reopen Tabby. Same end state.
+
+Do not assume "no Wave detected → cctabs unusable" — Tabby is fully supported.
+
 ---
 
 Each Claude Code session runs in its own **terminal tab**. `cctabs` lets you — and other Claude Code sessions — introspect and orchestrate the full session fleet.
@@ -317,17 +375,19 @@ cctabs new feature ~/Dev/myapp --worktree
 
 ## Handling `cctabs new` Timeout Errors
 
-`cctabs new` may occasionally fail with "Timed out waiting for new terminal block". This does **NOT** mean you have too many tabs or that Wave Terminal has hit a limit.
+`cctabs new` may occasionally fail with "Timed out waiting for new terminal block" (or, on Tabby, "Shell prompt never appeared in new tab"). This does **NOT** mean you have too many tabs or that the terminal has hit a limit.
 
-**Possible causes** (root cause not yet confirmed):
-- Wave Terminal may need to be in focus / foreground for tab creation to register
-- The internal timeout may be slightly too short for the current system load
-- Transient IPC timing issue between cctabs and Wave
+**Possible causes:**
+- The terminal app may need to be in focus / foreground for tab creation to register (true for both Wave and Tabby).
+- The internal timeout may be slightly too short for the current system load.
+- Transient IPC timing issue between cctabs and the terminal.
+- **Tabby only:** the cctabs plugin must be installed and running (`curl http://127.0.0.1:3300/api/health` to verify).
 
 **What to do:**
 1. **Retry the same command** — it often works on the second attempt
 2. If it fails again, wait a few seconds and retry once more
-3. If it keeps failing, ask the user to bring Wave Terminal to the foreground and try again
+3. If it keeps failing, ask the user to bring the terminal app to the foreground and try again
+4. On Tabby, also confirm the plugin is reachable (see health check above)
 
 **What NOT to do:**
 - ❌ Do NOT assume there is a "tab limit" — there isn't one