@generativereality/cctabs 0.3.1 → 0.4.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.3.1",
+  "version": "0.4.0",
   "author": {
     "name": "generativereality",
     "url": "https://cctabs.com"

package/README.md

@@ -206,11 +206,16 @@ flags = ["--allow-dangerously-skip-permissions"]
 | Terminal | Status |
 |----------|--------|
 | [Wave Terminal](https://waveterm.dev) | ✅ Full support |
+| [Tabby](https://tabby.sh) | ✅ Full support (requires the [`tabby-cctabs`](./tabby-plugin/) companion plugin) |
 | iTerm2 | Planned |
 | Ghostty | Planned |
 | Warp | Planned |
 
-Wave is supported via its unix socket RPC. Other terminals will follow as adapters — PRs welcome.
+Wave is supported via its unix socket RPC. Tabby is supported via a small companion plugin that exposes a localhost HTTP API the cctabs CLI talks to — install with `cctabs install-tabby-plugin`. Other terminals will follow as adapters — PRs welcome.
+
+### Login shells on macOS
+
+cctabs-spawned tabs default to **login shells** (`zsh -l`, `bash -l`, etc.) so PATH is initialised the same way Tabby's UI-spawned tabs are. Without `-l`, macOS's `/etc/zprofile` doesn't run, `path_helper` doesn't populate `/usr/local/bin` and `/opt/homebrew/bin` from `/etc/paths`, and brand-new tabs are missing Node, Homebrew, and anything else that lives there. Symptoms: `env: node: No such file or directory` in Claude Code's Bash tool, plugin MCP servers failing to start with ENOENT when they shell out to `npx`, and cctabs CLI itself failing inside the tab it just spawned. See [Tabby issue #2](https://github.com/Eugeny/tabby/issues/2) for the historical context. Pass an explicit `args` array (including `[]`) when calling the `/tabs` endpoint if you need a non-login shell.
 
 ## License
 

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.1";
+var version = "0.4.0";
 var description = "Claude Code tab manager. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -2601,6 +2601,38 @@ function checkTabbyPlugin() {
 		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."
 	};
 }
+/**
+* Probe whether `node` is findable in a freshly spawned shell — the canonical
+* symptom of the macOS non-login PATH bug. Spawning `zsh -l -c 'command -v
+* node'` simulates the same login-shell init (/etc/zprofile → path_helper)
+* that cctabs now uses when it opens new Tabby tabs. If this fails, brand-new
+* tabs will also fail to find Node, every plugin MCP that shells out to npx
+* will ENOENT, and the cctabs CLI itself becomes unusable from inside those
+* tabs (chicken-and-egg). The remediation hint covers both the upstream-fix
+* path (rely on a recent cctabs that defaults to `-l`) and the dotfile
+* workaround for users on older versions or non-Tabby terminals.
+*/
+function checkSpawnedShellPath() {
+	const r = spawnSync("zsh", [
+		"-l",
+		"-c",
+		"command -v node"
+	], {
+		encoding: "utf-8",
+		timeout: 3e3
+	});
+	if (r.status === 0 && r.stdout?.trim()) return {
+		name: "Spawned shell PATH (node findable)",
+		status: "ok",
+		detail: r.stdout.trim()
+	};
+	return {
+		name: "Spawned shell PATH",
+		status: "warn",
+		detail: r.error?.message ?? r.stderr?.trim() ?? "node not found in a login zsh",
+		hint: "A login zsh cannot find `node`. Either node is not installed, or PATH is broken. On macOS, `/usr/local/bin` is added by /etc/zprofile's path_helper — non-login shells skip it. Add `export PATH=\"/usr/local/bin:$PATH\"` to ~/.zshenv as a belt-and-braces fix."
+	};
+}
 function checkWaveDb() {
 	if (!existsSync(WAVE_DB_PATH)) return { result: {
 		name: "Wave DB",
@@ -2705,6 +2737,7 @@ const doctorCommand = define({
 		const results = [];
 		let waveDb = null;
 		results.push(checkTerminal(terminal));
+		results.push(checkSpawnedShellPath());
 		if (terminal === "tabby") results.push(checkTabbyPlugin());
 		if (terminal === "wave") {
 			results.push(checkWaveAccessibility());
@@ -2846,13 +2879,396 @@ 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",
 	description,
 	args: {},
 	async run() {
-		await sessionsCommand.run?.call(this, { args: {} });
+		await sessionsCommand.run?.call(this, { values: {} });
 	}
 });
 const subCommands = new Map([
@@ -2870,7 +3286,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, {

package/package.json

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

package/skills/cctabs/SKILL.md

@@ -143,6 +143,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
 ```
@@ -270,6 +273,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.