@generativereality/cctabs 0.4.5 → 0.4.6

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

package/dist/index.js

@@ -11,7 +11,7 @@ import { consola } from "consola";
 import * as p from "@clack/prompts";
 //#region package.json
 var name = "@generativereality/cctabs";
-var version = "0.4.5";
+var version = "0.4.6";
 var description = "Claude Code tab manager. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -28,8 +28,10 @@ var package_default = {
 		"dev": "bun run ./src/index.ts",
 		"build": "tsdown",
 		"typecheck": "tsc --noEmit",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
 		"lint": "eslint src/",
-		"check": "npm run typecheck && npm run build",
+		"check": "npm run typecheck && npm run test && 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",
@@ -63,6 +65,7 @@ var package_default = {
 		"update-notifier": "^7.3.1"
 	},
 	devDependencies: {
+		"@types/bun": "^1.3.14",
 		"@types/node": "^22.0.0",
 		"@types/update-notifier": "^6.0.8",
 		"bumpp": "^9.11.1",
@@ -957,6 +960,97 @@ function findSessionsByName(dir, name) {
 	return matches.sort((a, b) => b.mtime - a.mtime);
 }
 /**
+* Per-project-dir cache of `customTitle → newest session`. Built once per
+* project directory and reused, so callers that resolve many tabs (e.g.
+* `cctabs sessions --json` over 40+ tabs sharing one repo's project dir)
+* scan each directory a single time instead of once per tab.
+*
+* Cleared implicitly per process — cctabs commands are one-shot, so a stale
+* cache is never a concern within a single invocation.
+*/
+const titleIndexCache = /* @__PURE__ */ new Map();
+function buildTitleIndex(projectDir) {
+	const cached = titleIndexCache.get(projectDir);
+	if (cached) return cached;
+	const index = /* @__PURE__ */ new Map();
+	if (!existsSync(projectDir)) {
+		titleIndexCache.set(projectDir, index);
+		return index;
+	}
+	for (const f of readdirSync(projectDir)) {
+		if (extname(f) !== ".jsonl") continue;
+		const full = join(projectDir, f);
+		let title = "";
+		let cwd = "";
+		try {
+			const content = readFileSync(full, "utf-8");
+			for (const line of content.split("\n")) {
+				const hasTitle = line.includes("\"customTitle\"");
+				const hasCwd = !cwd && line.includes("\"cwd\"");
+				if (!hasTitle && !hasCwd) continue;
+				try {
+					const e = JSON.parse(line);
+					if (e.customTitle !== void 0) title = e.customTitle;
+					if (!cwd && typeof e.cwd === "string") cwd = e.cwd;
+				} catch {}
+			}
+		} catch {
+			continue;
+		}
+		if (!title) continue;
+		let mtime = 0;
+		try {
+			mtime = statSync(full).mtimeMs;
+		} catch {}
+		const id = basename(f, ".jsonl");
+		const prev = index.get(title);
+		if (!prev || mtime > prev.mtime) index.set(title, {
+			id,
+			cwd,
+			mtime
+		});
+	}
+	titleIndexCache.set(projectDir, index);
+	return index;
+}
+/**
+* Resolve the Claude session a *tab* is running, given the tab's shell cwd and
+* its name. Crucially worktree-aware: a tab opened with `--worktree <name>`
+* keeps its shell cwd at the repo root, but Claude runs inside
+* `<repo>/.claude/worktrees/<name>` — so its session lives under that
+* worktree's project slug, NOT the repo-root slug. Resolving by the repo-root
+* cwd alone (as a naive name lookup does) finds an older same-named session in
+* the repo root, or nothing — the exact bug that made restore resume the wrong
+* conversation for worktree tabs.
+*
+* Returns the matched session id AND the directory Claude must be launched from
+* to resume it (the worktree path for worktree tabs), or null if none matches.
+*/
+function resolveTabSession(cwd, name, projectsRoot = join(homedir(), ".claude", "projects")) {
+	const namedWtPath = join(cwd, ".claude", "worktrees", name);
+	const namedHit = buildTitleIndex(join(projectsRoot, pathToProjectSlug(namedWtPath))).get(name);
+	if (namedHit) return {
+		id: namedHit.id,
+		dir: namedHit.cwd || namedWtPath
+	};
+	const candidates = [join(projectsRoot, pathToProjectSlug(cwd))];
+	const worktreesDir = join(cwd, ".claude", "worktrees");
+	if (existsSync(worktreesDir)) for (const entry of readdirSync(worktreesDir)) candidates.push(join(projectsRoot, pathToProjectSlug(join(worktreesDir, entry))));
+	let best = null;
+	for (const projectDir of candidates) {
+		const hit = buildTitleIndex(projectDir).get(name);
+		if (hit && (!best || hit.mtime > best.mtime)) best = {
+			id: hit.id,
+			dir: hit.cwd || cwd,
+			mtime: hit.mtime
+		};
+	}
+	return best ? {
+		id: best.id,
+		dir: best.dir
+	} : null;
+}
+/**
 * Like findSessionsByName, but searches every project directory under
 * ~/.claude/projects. Each match carries the cwd recorded in the session.
 * Used by `cctabs restore` so callers don't have to guess the right dir.
@@ -1023,6 +1117,48 @@ function findSessionsByNameGlobally(name) {
 	return matches.sort((a, b) => b.mtime - a.mtime);
 }
 /**
+* Single-pass scan of every ~/.claude/projects/*\/*.jsonl: for each session,
+* return its current customTitle (the LAST one in the file — sessions can be
+* renamed) and its mtime. Used by `cctabs sort` to score tab activity.
+*
+* Returns Map<customTitle, latestMtimeMs>: when a title appears in multiple
+* sessions (forks, restarts), we keep the most recent mtime.
+*/
+function buildTitleActivityMap() {
+	const projectsRoot = join(homedir(), ".claude", "projects");
+	const result = /* @__PURE__ */ new Map();
+	if (!existsSync(projectsRoot)) return result;
+	for (const slug of readdirSync(projectsRoot)) {
+		const projectDir = join(projectsRoot, slug);
+		let isDir = false;
+		try {
+			isDir = statSync(projectDir).isDirectory();
+		} catch {
+			continue;
+		}
+		if (!isDir) continue;
+		for (const f of readdirSync(projectDir)) {
+			if (extname(f) !== ".jsonl") continue;
+			const fullPath = join(projectDir, f);
+			try {
+				const mtime = statSync(fullPath).mtimeMs;
+				const content = readFileSync(fullPath, "utf-8");
+				let currentTitle = "";
+				for (const line of content.split("\n")) {
+					if (!line.trim()) continue;
+					try {
+						const entry = JSON.parse(line);
+						if (entry.customTitle !== void 0) currentTitle = entry.customTitle;
+					} catch {}
+				}
+				if (!currentTitle) continue;
+				if (mtime > (result.get(currentTitle) ?? 0)) result.set(currentTitle, mtime);
+			} catch {}
+		}
+	}
+	return result;
+}
+/**
 * List all unique session names (customTitle) in a project directory.
 * Used to show available names when a resume lookup fails.
 */
@@ -1119,15 +1255,19 @@ const sessionsCommand = define({
 					const status = adapter.detectSessionStatus(b.blockid);
 					const lastLine = adapter.scrollback(b.blockid, 5).split("\n").map((l) => l.trim()).filter(Boolean).at(-1) ?? "";
 					let sessionId = null;
+					let sessionDir = cwd;
 					if (cwd) try {
-						const matches = findSessionsByName(cwd, tabName);
-						if (matches.length) sessionId = matches[0].id;
+						const resolved = resolveTabSession(cwd, tabName);
+						if (resolved) {
+							sessionId = resolved.id;
+							sessionDir = resolved.dir;
+						}
 					} catch {}
 					wsRow.sessions.push({
 						block_id: b.blockid,
 						tab_id: tabId,
 						name: tabName,
-						cwd,
+						cwd: sessionDir,
 						current: tabId === currentTab,
 						status,
 						last_line: lastLine.slice(0, 200),
@@ -1328,11 +1468,11 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 * long / multi-line prompt collapses to a "[Pasted text #N +M lines]" chip.
 */
 async function sendInitialPrompt(adapter, blockId, initialPromptFile) {
+	const readySignal = /❯|auto mode|for agents|Try ["'“]/;
 	try {
-		await waitForScrollbackMatch(adapter, blockId, "❯", "Claude prompt", 3e4);
+		await waitForScrollbackMatch(adapter, blockId, readySignal, "Claude prompt", 45e3);
 	} catch {
-		adapter.closeSocket();
-		throw new Error("Claude prompt (❯) never appeared — not sending initial prompt. Check that claude started successfully.");
+		consola.warn("Could not confirm Claude was ready within 45s — sending the prompt anyway (will verify it lands).");
 	}
 	if (/trustthisfolder|Yes,?Itrustthis|Isthisaproject/i.test(adapter.scrollback(blockId, 40).replace(/\s+/g, ""))) for (let attempt = 0; attempt < 18; attempt++) {
 		const screen = adapter.scrollback(blockId, 14).replace(/\s+/g, "");
@@ -1365,9 +1505,9 @@ async function sendInitialPrompt(adapter, blockId, initialPromptFile) {
 		consola.warn("Initial prompt may not have landed in the input box — switch to the tab and press Enter (re-type if the box is empty).");
 		return;
 	}
-	for (let attempt = 0; attempt < 4; attempt++) {
+	for (let attempt = 0; attempt < 8; attempt++) {
 		await adapter.sendInput(blockId, "\r");
-		await sleep(500);
+		await sleep(700);
 		const tail = adapter.scrollback(blockId, 40);
 		if (/[✻✽✶✳✢]/.test(tail) || /esctointerrupt/i.test(tail.replace(/\s+/g, ""))) return;
 	}
@@ -1681,6 +1821,89 @@ function listBackends() {
 	}));
 }
 //#endregion
+//#region src/core/worktree.ts
+function runGit(cwd, args) {
+	return execFileSync("git", [
+		"-C",
+		cwd,
+		...args
+	], {
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+}
+/**
+* Create (or reuse) `<dir>/.claude/worktrees/<name>` anchored at <dir>'s current HEAD.
+*
+* Why this exists: `claude --worktree <name>` historically does not always branch
+* from the current HEAD — with un-pushed local commits it can branch from the
+* upstream tracking ref instead, silently producing a worktree at a stale
+* commit. cctabs creates the worktree explicitly so the new tab starts from
+* exactly the commit the parent session was working on.
+*/
+function setupWorktree(dir, name) {
+	const absDir = resolve(dir.replace(/^~/, homedir()));
+	const worktreePath = join(absDir, ".claude", "worktrees", name);
+	const branchName = `worktree-${name}`;
+	try {
+		runGit(absDir, ["rev-parse", "--is-inside-work-tree"]);
+	} catch {
+		throw new Error(`Not a git repository: ${absDir}`);
+	}
+	const parentHeadSha = runGit(absDir, ["rev-parse", "HEAD"]);
+	if (existsSync(worktreePath)) return {
+		worktreePath,
+		branchName,
+		baseSha: runGit(worktreePath, ["rev-parse", "HEAD"]),
+		parentHeadSha,
+		created: false,
+		reusedBranch: false
+	};
+	const branchExists = (() => {
+		try {
+			runGit(absDir, [
+				"show-ref",
+				"--verify",
+				`refs/heads/${branchName}`
+			]);
+			return true;
+		} catch {
+			return false;
+		}
+	})();
+	try {
+		if (branchExists) runGit(absDir, [
+			"worktree",
+			"add",
+			worktreePath,
+			branchName
+		]);
+		else runGit(absDir, [
+			"worktree",
+			"add",
+			"-b",
+			branchName,
+			worktreePath,
+			parentHeadSha
+		]);
+	} catch (e) {
+		const stderr = e?.stderr?.toString?.() ?? e?.message ?? String(e);
+		throw new Error(`git worktree add failed for ${worktreePath}: ${stderr.trim()}`);
+	}
+	return {
+		worktreePath,
+		branchName,
+		baseSha: runGit(worktreePath, ["rev-parse", "HEAD"]),
+		parentHeadSha,
+		created: true,
+		reusedBranch: branchExists
+	};
+}
+//#endregion
 //#region src/commands/new.ts
 const newCommand = define({
 	name: "new",
@@ -1779,14 +2002,27 @@ const newCommand = define({
 			initialPromptFile = join(tmpdir(), `cctabs-prompt-${Date.now()}.txt`);
 			writeFileSync(initialPromptFile, promptText);
 		} else if (promptFile) initialPromptFile = promptFile;
+		let sessionDir = dir;
+		let worktreeInfo;
+		if (useWorktree) try {
+			const wt = setupWorktree(dir, name);
+			sessionDir = wt.worktreePath;
+			worktreeInfo = wt;
+			if (wt.created) {
+				const branchNote = wt.reusedBranch ? ` (reused existing branch ${wt.branchName})` : "";
+				consola.info(`Worktree created at ${wt.worktreePath} (base ${wt.baseSha.slice(0, 8)})${branchNote}`);
+				if (wt.baseSha !== wt.parentHeadSha) consola.warn(`Worktree base ${wt.baseSha.slice(0, 8)} differs from ${dir} HEAD ${wt.parentHeadSha.slice(0, 8)} — branch '${wt.branchName}' already existed and was checked out at its prior tip.`);
+			} else consola.info(`Worktree already present at ${wt.worktreePath} (base ${wt.baseSha.slice(0, 8)}) — reusing`);
+		} catch (e) {
+			consola.error(e?.message ?? String(e));
+			process.exit(1);
+		}
 		let claudeCmd;
-		if (resolvedSessionId) {
-			const worktreePart = useWorktree ? ` --worktree ${JSON.stringify(name)}` : "";
-			claudeCmd = `claude --resume ${resolvedSessionId}${worktreePart} --name ${JSON.stringify(name)}`;
-		} else claudeCmd = useWorktree ? `claude --worktree ${JSON.stringify(name)}` : "claude";
+		if (resolvedSessionId) claudeCmd = `claude --resume ${resolvedSessionId} --name ${JSON.stringify(name)}`;
+		else claudeCmd = "claude";
 		const tabId = await openSession({
 			tabName: name,
-			dir,
+			dir: sessionDir,
 			claudeCmd,
 			workspaceQuery: workspace,
 			initialPromptFile,
@@ -1794,7 +2030,7 @@ const newCommand = define({
 			modelOverride: resolvedModel,
 			afterActive: true
 		});
-		const wt = useWorktree ? ` (worktree: .claude/worktrees/${name})` : "";
+		const wt = worktreeInfo ? ` (worktree: .claude/worktrees/${name} @ ${worktreeInfo.baseSha.slice(0, 8)})` : "";
 		const be = backendName ? ` [backend: ${backendName}${resolvedModel ? ` → ${resolvedModel}` : ""}]` : "";
 		const rs = resolvedSessionId ? ` --resume ${resolvedSessionId.slice(0, 8)}…` : "";
 		consola.success(`Tab "${name}" [${tabId.slice(0, 8)}] → claude${rs} at ${dir}${wt}${be}`);
@@ -1918,8 +2154,10 @@ const resumeCommand = define({
 				consola.error(`No terminal block found in tab '${name}'`);
 				process.exit(1);
 			}
+			const isCurrentTab = tabId === adapter.currentTabId();
+			const insideClaude = !!process.env.CLAUDECODE;
 			const status = adapter.detectSessionStatus(termBlock.blockid);
-			if (status === "active" || status === "idle") {
+			if ((status === "active" || status === "idle") && !(isCurrentTab && !insideClaude)) {
 				adapter.closeSocket();
 				consola.warn(`Claude is already running in tab "${name}" (${status}) — skipping resume`);
 				process.exit(0);
@@ -1946,6 +2184,11 @@ const resumeCommand = define({
 			const modelPart = resolvedModel ? ` --model ${JSON.stringify(resolvedModel)}` : "";
 			const cmd = `cd ${JSON.stringify(dir)} && ${envPrefix}claude${extraFlags ? " " + extraFlags : ""} --resume ${sessionId} --name ${JSON.stringify(name)}${modelPart}\r`;
 			await adapter.sendInput(termBlock.blockid, cmd);
+			if (isCurrentTab) {
+				adapter.closeSocket();
+				consola.success(`Tab "${name}" [${tabId.slice(0, 8)}] → claude --resume ${sessionId.slice(0, 8)}… at ${dir} (queued in this shell)`);
+				return;
+			}
 			let verified = false;
 			const deadline = Date.now() + 15e3;
 			while (Date.now() < deadline) {
@@ -2218,7 +2461,7 @@ const sendCommand = define({
 		"wait-for-prompt": {
 			type: "boolean",
 			short: "w",
-			description: "Poll the buffer until a shell prompt ($, %, >, ❯) is visible before sending. Useful for freshly-spawned tabs."
+			description: "Poll the buffer until a ready prompt is visible before sending — a shell prompt ($, %, >) or a ready Claude TUI (❯ input line / \"auto mode\" footer). Useful for freshly-spawned tabs."
 		},
 		"wait-timeout": {
 			type: "number",
@@ -2240,7 +2483,11 @@ const sendCommand = define({
 		if (inlineText !== void 0) rawText = inlineText.replace(/\\n/g, "\r").replace(/\\r/g, "\r").replace(/\\t/g, "	");
 		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";
+		let sendEnter = appendEnter;
+		if (rawText.endsWith("\r")) {
+			rawText = rawText.replace(/\r+$/, "");
+			sendEnter = true;
+		}
 		const adapter = requireAdapter();
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const tabMatches = adapter.resolveTab(query, tabsById, tabNames);
@@ -2274,8 +2521,10 @@ const sendCommand = define({
 			const deadline = Date.now() + waitTimeoutSec * 1e3;
 			let ready = false;
 			while (Date.now() < deadline) {
-				const lastLine = adapter.scrollback(blockId, 5).split("\n").map((l) => l.trim()).filter(Boolean).at(-1) ?? "";
-				if (/[$%>❯]\s*$/.test(lastLine)) {
+				const tail = adapter.scrollback(blockId, 8);
+				const lastLine = tail.split("\n").map((l) => l.trim()).filter(Boolean).at(-1) ?? "";
+				const stripped = tail.replace(/\s+/g, "");
+				if (/[$%>]\s*$/.test(lastLine) || /^❯/.test(lastLine) || /automode|foragents/i.test(stripped)) {
 					ready = true;
 					break;
 				}
@@ -2283,18 +2532,25 @@ const sendCommand = define({
 			}
 			if (!ready) {
 				adapter.closeSocket();
-				consola.error(`Timed out after ${waitTimeoutSec}s waiting for shell prompt in ${blockId.slice(0, 8)}`);
+				consola.error(`Timed out after ${waitTimeoutSec}s waiting for a ready prompt in ${blockId.slice(0, 8)}`);
 				process.exit(1);
 			}
 		}
-		const resp = await adapter.sendInput(blockId, rawText);
+		let resp;
+		if (rawText.length > 0) resp = await adapter.sendInput(blockId, rawText);
+		if (sendEnter) {
+			if (rawText.length > 0) await new Promise((r) => setTimeout(r, 200));
+			const enterResp = await adapter.sendInput(blockId, "\r");
+			resp ??= enterResp;
+		}
 		adapter.closeSocket();
 		if (resp && resp.error) {
 			consola.error(String(resp.error));
 			process.exit(1);
 		}
 		const preview = rawText.slice(0, 80).replace(/\n/g, "↵").replace(/\t/g, "→");
-		consola.success(`Sent to ${blockId.slice(0, 8)}: ${JSON.stringify(preview)}${rawText.length > 80 ? "…" : ""}`);
+		const label = rawText.length > 0 ? `${JSON.stringify(preview)}${rawText.length > 80 ? "…" : ""}${sendEnter ? " ⏎" : ""}` : "⏎";
+		consola.success(`Sent to ${blockId.slice(0, 8)}: ${label}`);
 	}
 });
 //#endregion
@@ -2433,15 +2689,27 @@ async function runManifestMode(manifestPath, createMissing, dryRun) {
 	const extraFlags = loadConfig().claude.flags.map(shellQuoteArg).join(" ");
 	for (const entry of entries) {
 		let resolvedSessionId = entry.session_id;
+		let resolvedDir = entry.dir;
 		if (entry.session_id) {
 			const expanded = expandSessionId(entry.session_id, entry.dir) ?? expandSessionId(entry.session_id);
 			if (expanded) resolvedSessionId = expanded;
 		} else {
-			const sessions = findSessionsByName(entry.dir, entry.name);
-			if (sessions.length === 1) resolvedSessionId = sessions[0].id;
-			else if (sessions.length > 1) resolvedSessionId = sessions[0].id;
+			const resolved = resolveTabSession(entry.dir, entry.name);
+			if (resolved) {
+				resolvedSessionId = resolved.id;
+				resolvedDir = resolved.dir;
+			}
 		}
-		const matchingTabs = adapter.resolveTab(entry.name, tabsById, tabNames).filter((tid) => wsTabIds.has(tid) && tid !== currentTab);
+		const allMatches = adapter.resolveTab(entry.name, tabsById, tabNames).filter((tid) => wsTabIds.has(tid));
+		if (allMatches.length === 1 && allMatches[0] === currentTab) {
+			consola.log(`  ${entry.name} — current tab, already present`);
+			results.push({
+				name: entry.name,
+				result: "current tab — already present"
+			});
+			continue;
+		}
+		const matchingTabs = allMatches.filter((tid) => tid !== currentTab);
 		if (matchingTabs.length > 1) {
 			consola.log(`  ${entry.name} — multiple matching tabs, skipping`);
 			results.push({
@@ -2486,7 +2754,7 @@ async function runManifestMode(manifestPath, createMissing, dryRun) {
 				continue;
 			}
 			consola.log(`  ${entry.name} → resuming ${resolvedSessionId.slice(0, 8)}… in existing tab`);
-			const cmd = `cd ${JSON.stringify(entry.dir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${resolvedSessionId} --name ${JSON.stringify(entry.name)}\r`;
+			const cmd = `cd ${JSON.stringify(resolvedDir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${resolvedSessionId} --name ${JSON.stringify(entry.name)}\r`;
 			await adapter.sendInput(termBlock.blockid, cmd);
 			await new Promise((r) => setTimeout(r, 500));
 			results.push({
@@ -2505,7 +2773,7 @@ async function runManifestMode(manifestPath, createMissing, dryRun) {
 		}
 		if (dryRun) {
 			const sid = resolvedSessionId ? `${resolvedSessionId.slice(0, 8)}…` : "fresh";
-			consola.log(`  ${entry.name} → would spawn new tab in ${entry.dir} (${sid})`);
+			consola.log(`  ${entry.name} → would spawn new tab in ${resolvedDir} (${sid})`);
 			results.push({
 				name: entry.name,
 				result: `dry run: spawn (${sid})`
@@ -2514,6 +2782,7 @@ async function runManifestMode(manifestPath, createMissing, dryRun) {
 		}
 		toSpawn.push({
 			...entry,
+			dir: resolvedDir,
 			session_id: resolvedSessionId
 		});
 	}
@@ -3511,6 +3780,86 @@ const importCommand = define({
 	}
 });
 //#endregion
+//#region src/commands/sort.ts
+function relAge(ms) {
+	const s = Math.floor(ms / 1e3);
+	if (s < 60) return `${s}s ago`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m ago`;
+	const h = Math.floor(m / 60);
+	if (h < 48) return `${h}h ago`;
+	return `${Math.floor(h / 24)}d ago`;
+}
+const sortCommand = define({
+	name: "sort",
+	description: "Reorder tabs by Claude session activity (most-recent first).",
+	args: {
+		"dry-run": {
+			type: "boolean",
+			short: "n",
+			description: "Show planned order without applying it"
+		},
+		reverse: {
+			type: "boolean",
+			short: "r",
+			description: "Oldest first instead of newest"
+		}
+	},
+	async run(ctx) {
+		const dryRun = !!ctx.values["dry-run"];
+		const reverse = !!ctx.values.reverse;
+		const adapter = requireAdapter();
+		if (typeof adapter.reorderTabs !== "function") {
+			consola.error("Tab reordering is not supported by this terminal (Tabby only for now).");
+			process.exit(1);
+		}
+		const { tabsById, workspaces, tabNames } = await adapter.getAllData();
+		const titleMtimes = buildTitleActivityMap();
+		const now = Date.now();
+		for (const wsp of workspaces) {
+			const tabIds = wsp.workspacedata.tabids.filter((t) => tabsById.has(t));
+			if (!tabIds.length) continue;
+			const ranked = tabIds.map((tid, origIndex) => {
+				const name = tabNames.get(tid) ?? tid.slice(0, 8);
+				return {
+					tid,
+					name,
+					mtime: titleMtimes.get(name) ?? 0,
+					origIndex
+				};
+			});
+			ranked.sort((a, b) => {
+				if (!a.mtime && !b.mtime) return a.origIndex - b.origIndex;
+				if (!a.mtime) return 1;
+				if (!b.mtime) return -1;
+				return reverse ? a.mtime - b.mtime : b.mtime - a.mtime;
+			});
+			consola.info(`${reverse ? "Oldest" : "Newest"} first:`);
+			for (const r of ranked) {
+				const age = r.mtime ? relAge(now - r.mtime) : "(no session)";
+				consola.log(`  ${r.name.padEnd(32)}  ${age}`);
+			}
+			const desiredOrder = ranked.map((r) => r.tid);
+			if (desiredOrder.every((id, i) => id === tabIds[i])) {
+				consola.info("Already in order.");
+				continue;
+			}
+			if (dryRun) {
+				consola.info("Dry run — no changes applied.");
+				continue;
+			}
+			try {
+				await adapter.reorderTabs(desiredOrder);
+				consola.success(`Reordered ${desiredOrder.length} tab(s).`);
+			} catch (err) {
+				consola.error(`Failed to reorder tabs: ${err.message}`);
+				process.exitCode = 1;
+			}
+		}
+		adapter.closeSocket();
+	}
+});
+//#endregion
 //#region src/commands/index.ts
 const defaultCommand = define({
 	name: "cctabs",
@@ -3537,7 +3886,8 @@ const subCommands = new Map([
 	["doctor", doctorCommand],
 	["install-tabby-plugin", installTabbyPluginCommand],
 	["export", exportCommand],
-	["import", importCommand]
+	["import", importCommand],
+	["sort", sortCommand]
 ]);
 async function run() {
 	await cli(process.argv.slice(2), defaultCommand, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/cctabs",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {
@@ -15,8 +15,10 @@
     "dev": "bun run ./src/index.ts",
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
     "lint": "eslint src/",
-    "check": "npm run typecheck && npm run build",
+    "check": "npm run typecheck && npm run test && 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",
@@ -52,6 +54,7 @@
     "update-notifier": "^7.3.1"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@types/node": "^22.0.0",
     "@types/update-notifier": "^6.0.8",
     "bumpp": "^9.11.1",

package/skills/cctabs/SKILL.md

@@ -3,9 +3,9 @@ name: cctabs
 description: |
   Manage Claude Code sessions across terminal tabs (Wave Terminal or Tabby) — list, open, fork, close, inspect output, send input. Each terminal tab runs its own Claude Code session.
 
-  TRIGGER when the user says any of: "open a new tab", "open a new cctab" (singular alias), "spawn a tab", "a new cctabs session", "in another tab", "in a separate tab", "fork this tab", "list my tabs", "close that tab", "send to <tab>", "resume <name>" — anything that refers to a terminal tab running Claude Code. ALSO trigger for: "/cctabs", or when the user mentions Wave Terminal / Tabby tab management for Claude Code.
+  TRIGGER when the user says any of: "open a tab", "open a new tab", "open a tab with prompt …", "open a tab and <do X>", "open a tab that <does X>", "open a new cctab" (singular alias), "spawn a tab", "a new cctabs session", "in another tab", "in a separate tab", "fork this tab", "list my tabs", "close that tab", "send to <tab>", "resume <name>" — anything that refers to a terminal tab running Claude Code. ALSO trigger for: "/cctabs", or when the user mentions Wave Terminal / Tabby tab management for Claude Code.
 
-  DO NOT confuse with the Agent tool (background subagents): if the user explicitly says "tab" / "cctab" / "cctabs" they want a separate Claude Code session in a real terminal tab — call this skill, not Agent. The Agent tool is correct when the user says "subagent", "background agent", "spawn an agent", "do this in parallel without a new tab", or when the work is interconnected with the current session's filesystem state.
+  The word "tab" is DECISIVE. If the user says "tab" / "cctab" / "cctabs" — even paired with a task, and even when that task sounds like background or parallel work (e.g. "open a tab with prompt 'do X asap'", "open a tab and fix Y") — they mean a real terminal tab running its own Claude Code session: CALL THIS SKILL, not the Agent tool. Handing a task to a fresh tab is the single most common use: "open a tab with prompt <task>" maps directly to `cctabs new <name> [dir] --prompt "<task>"`. A background/fork subagent (the Agent tool) is NOT a tab and must never be substituted when the user said "tab" — its output is invisible in the terminal and it cannot be attached to, resumed, watched, or driven as a session. Use the Agent tool ONLY when the user explicitly says "subagent", "background agent", "spawn an agent", "do this in parallel without a new tab", or when the work is tightly interconnected with the current session's filesystem state and must share it.
 
   NOT for: browser tabs (use playwright/browser-automation), tmux panes, screen sessions, or non-Claude terminals.
 ---
@@ -358,13 +358,10 @@ cctabs send payments "yes\n"   # quick replies
 
 ### Spawning gotchas (hard-won)
 
-1. **Verify the worktree base immediately after spawn.** `--worktree` does not always branch from your current HEAD — if you have local un-pushed commits, the child session may branch from an older commit (whatever the remote tracking branch points at). Always check:
+1. **Worktree base.** `cctabs new --worktree` anchors the new worktree at the target dir's current HEAD (cctabs runs `git worktree add` explicitly, not delegating to `claude --worktree`). The spawn line confirms the base SHA, e.g. `Worktree created at … (base 9d4a26d…)`. If a branch named `worktree-<name>` already exists from a prior run, the worktree is checked out at *that branch's* tip and cctabs prints a warning — verify it's what you want before sending work into the tab. To double-check after spawn:
    ```bash
-   cctabs new kid ~/Dev/myapp --worktree -p "..."
-   # Then in the ORCHESTRATOR tab:
    git -C ~/Dev/myapp/.claude/worktrees/kid log --oneline -1
    ```
-   If the base is not what you expected, abort and fix: either push your commits to the tracking branch first, or spawn without `--worktree` and let the subagent work on your branch directly.
 
 2. **Never instruct a subagent to "rebase your branch on main/next."** Subagents interpret this liberally. A common failure mode: the subagent does `git reset --hard <remote>` and throws away its own completed commits, trying to redo the work from scratch. Instead:
    - Have the orchestrator handle rebases after the subagent is done.
@@ -400,9 +397,10 @@ echo "do the thing" | cctabs send auth       # pipe via stdin
 
 ```bash
 cctabs new feature-name ~/Dev/myapp --worktree
-# Equivalent to: cd ~/Dev/myapp && claude --worktree "feature-name" --name "feature-name"
-# Claude creates: ~/Dev/myapp/.claude/worktrees/feature-name/
-# Claude creates branch: worktree-feature-name
+# cctabs creates the worktree itself, pinned to ~/Dev/myapp's current HEAD:
+#   git -C ~/Dev/myapp worktree add -b worktree-feature-name \
+#     ~/Dev/myapp/.claude/worktrees/feature-name <current HEAD>
+# Then opens a tab at the worktree path and runs plain `claude --name feature-name`.
 ```
 
 ### Existing branch — ask Claude to enter the worktree mid-session
@@ -426,7 +424,7 @@ cctabs new feature ~/Dev/myapp --worktree
 
 **Why:** Manually created worktree dirs placed outside the repo confuse Claude Code's session tracking, project memory lookup (`.claude/` is in the main repo), and CLAUDE.md resolution. Claude Code's built-in worktree support keeps everything co-located under `.claude/worktrees/` and handles cleanup on session exit.
 
-**Worktree base-commit caveat:** after spawning with `--worktree`, verify the branch base matches your expectation (see "Spawning gotchas" above). If your orchestrator has local commits that haven't been pushed, the worktree may branch from the stale remote tip instead of HEAD. This bites hardest when parallel tabs need to share schema/types your orchestrator has been working on — they won't see those changes if they branched before the commits landed upstream.
+**Worktree base commit:** cctabs anchors the new worktree at the target dir's current HEAD (it runs `git worktree add` explicitly rather than delegating to `claude --worktree`), so un-pushed local commits *are* visible to the child session. The success line prints the base SHA — confirm it matches what you expect, especially if you reuse a worktree name and see a "branch already existed" warning.
 
 ## Handling `cctabs new` Timeout Errors