@hank-warren/pi-statusline 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @hank-warren/pi-statusline
 
+## 0.3.0
+
+### Minor Changes
+
+- 0e6c204: Add a `/statusline` settings menu for choosing a theme, toggling every footer element, setting the worktree-tracker root, and managing repo aliases. Settings persist to `~/.pi/agent/statusline-settings.json` and apply live.
+
+  Themes: `default` (unchanged), `dracula`, `github-dark`, `catppuccin-mocha`, and `white`. A theme maps eleven colour roles, so switching recolours every element without changing the rendered text.
+
+  Breaking: the built-in repo aliases and the automatic `platform-` prefix strip are gone — they were hardcoded to one machine. Repository names now render verbatim; add your own pairs under `/statusline → Repo aliases`.
+
 ## 0.2.4
 
 ### Patch Changes

package/README.md

@@ -14,7 +14,34 @@ gpt-5.6-sol | pi-extensions:main* ⇣1 | 40k/1.0m |  97·54  80
 - **Worktree lines** — when the session works in or sends tool calls into linked worktrees, one line shows the same branch/dirty/behind state for each worktree plus its associated PR number.
 - **Final line** — the full Pi session ID.
 
-It uses a fixed true-color palette with context warning thresholds.
+Colors come from a selectable [theme](#themes), with context warning thresholds. Every element can be turned off from [`/statusline`](#statusline).
+
+## `/statusline`
+
+`/statusline` opens a `/settings`-style menu (TUI mode only) for configuring the footer. Changes apply live and persist immediately:
+
+- **Theme** — the color palette, cycled with Enter or Space. See [Themes](#themes).
+- **Model**, **Directory & git**, **Context**, **Subscription usage**, **Worktree line**, **Session ID line**, **Cache celebration** — `on`/`off`, cycled with Enter or Space. Disabled segments are dropped from line 1 without leaving a stray ` | ` separator; hiding the worktree line also stops its `git`/`gh` polling, and hiding usage stops the usage poller. With every element off the footer collapses to a single blank row.
+- **Worktree root** — the directory whose immediate children are tracked as session worktrees (default `~/repos/worktrees`). `~` and `$HOME` are expanded; a relative path is rejected and the previous value kept.
+- **Repo aliases** — short display names for repositories on the worktree line. Enter edits the selected `repo → alias` pair, `d` deletes it, and `Add alias…` creates one from a `repo=alias` line.
+
+Settings live in a single global file, `~/.pi/agent/statusline-settings.json`, written atomically. Only values differing from the defaults are stored, unknown keys from a newer version are preserved, and a missing or malformed file simply yields defaults. The file is read once at session start and is not watched, so hand edits apply to the next session. Concurrent pi sessions are last-writer-wins.
+
+## Themes
+
+| Name | Notes |
+|---|---|
+| `default` | The palette this package has always used — blue model, cyan branch, neon magenta/cyan cache badge |
+| `dracula` | [Dracula](https://draculatheme.com), with the pink `#ff79c6` branch color used in Herdr sidebar configs |
+| `github-dark` | GitHub's dark default |
+| `catppuccin-mocha` | [Catppuccin](https://catppuccin.com) Mocha |
+| `white` | No color: white text, dimmed punctuation, a white/grey badge flash |
+
+A theme maps eleven roles — `model`, `path`, `branch`, `text`, `dim`, `ok`, `warn`, `caution`, `danger`, `accent`, and the two `celebration` badge frames — so switching recolors every element at once without changing a single character of rendered text. `ok`/`warn`/`caution`/`danger` drive the context meter, the usage meters, and the dirty/behind markers alike, so the warning gradient stays legible in every theme. An unknown theme name in the settings file falls back to `default`.
+
+### Repo aliases are no longer built in
+
+Up to 0.2.x this package hardcoded five alias pairs and stripped a `platform-` prefix from every other repository. Those rules were specific to one machine and shipped to everyone. From 0.3.0 the alias map starts empty and repository names render verbatim — add whatever pairs you want under `/statusline → Repo aliases`.
 
 ## Subscription usage meters
 
@@ -49,7 +76,7 @@ Output and reasoning tokens are excluded because they are not prompt-cache candi
 
 ## Worktree/PR tracking behavior
 
-- Only worktrees touched on the active Pi session branch are included.
+- Only worktrees directly under the configured worktree root and touched on the active Pi session branch are included. Absolute, `~/`, and `$HOME/` spellings of that root all match.
 - Worktree paths appearing only inside Bash heredoc payloads are ignored.
 - Merged and closed PR worktrees are hidden.
 - State is rebuilt on reload and tree navigation; deleted worktrees are pruned.

package/index.ts

@@ -1,17 +1,30 @@
+import { homedir } from "node:os";
 import { basename } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	type ExtensionAPI,
+	type ExtensionContext,
+	getSelectListTheme,
+	getSettingsListTheme,
+} from "@earendil-works/pi-coding-agent";
+import { SettingsList, truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	CacheCelebrationController,
 	type CacheCelebrationSnapshot,
 	triggerCacheCelebrationForMessage,
 } from "./cache-celebration.ts";
 import { FullRedrawScheduler } from "./redraw.ts";
+import {
+	applySettingChange,
+	buildSettingItems,
+	createAliasSubmenu,
+	createWorktreeRootSubmenu,
+} from "./settings-menu.ts";
+import { defaultSettings, repoAlias, SettingsStore, type StatuslineSettings } from "./settings.ts";
+import { resolvePalette, type StatuslinePalette, STATUSLINE_THEMES } from "./themes.ts";
 import { type UsageSnapshot, usageBand, UsageTracker } from "./usage.ts";
 import {
 	type GitRepositoryStatus,
 	readGitStatus,
-	repoAlias,
 	type SessionWorktree,
 	SessionWorktreeTracker,
 } from "./worktrees.ts";
@@ -28,19 +41,9 @@ export interface StatuslineData {
 	usage?: UsageSnapshot;
 }
 
-const BLUE = "\x1b[38;2;0;153;255m";
-const ORANGE = "\x1b[38;2;255;176;85m";
-const GREEN = "\x1b[38;2;0;175;80m";
-const CYAN = "\x1b[38;2;86;182;194m";
-const RED = "\x1b[38;2;255;85;85m";
-const YELLOW = "\x1b[38;2;230;200;0m";
-const WHITE = "\x1b[38;2;220;220;220m";
-const MAGENTA = "\x1b[38;2;190;120;255m";
-const NEON_CYAN = "\x1b[38;2;0;255;255m";
-const NEON_MAGENTA = "\x1b[38;2;255;0;255m";
-const DIM = "\x1b[2m";
 const BOLD = "\x1b[1m";
 const RESET = "\x1b[0m";
+const DEFAULT_PALETTE = STATUSLINE_THEMES.default;
 
 function styled(style: string, text: string): string {
 	return `${style}${text}${RESET}`;
@@ -48,32 +51,37 @@ function styled(style: string, text: string): string {
 
 const CLAUDE_ICON = "\uec82";
 const OPENAI_ICON = "\uec81";
-const USAGE_BAND_COLORS = { green: GREEN, yellow: YELLOW, orange: ORANGE, red: RED } as const;
 
-function remainingPercent(remaining: number): string {
-	return styled(USAGE_BAND_COLORS[usageBand(remaining)], `${remaining}`);
+function bandColor(remaining: number, palette: StatuslinePalette): string {
+	return { green: palette.ok, yellow: palette.warn, orange: palette.caution, red: palette.danger }[
+		usageBand(remaining)
+	];
 }
 
-export function renderUsageSegment(usage: UsageSnapshot): string | undefined {
+export function renderUsageSegment(
+	usage: UsageSnapshot,
+	palette: StatuslinePalette = DEFAULT_PALETTE,
+): string | undefined {
+	const percent = (remaining: number) => styled(bandColor(remaining, palette), `${remaining}`);
 	const parts: string[] = [];
 	if (usage.claude) {
-		const dot = styled(DIM, "\u00b7");
-		let claude = `${remainingPercent(usage.claude.fiveHour)}${dot}${remainingPercent(usage.claude.sevenDay)}`;
-		if (usage.claude.scopedWeekly !== undefined) claude += `${dot}${remainingPercent(usage.claude.scopedWeekly)}`;
-		parts.push(`${styled(WHITE, CLAUDE_ICON)} ${claude}`);
+		const dot = styled(palette.dim, "\u00b7");
+		let claude = `${percent(usage.claude.fiveHour)}${dot}${percent(usage.claude.sevenDay)}`;
+		if (usage.claude.scopedWeekly !== undefined) claude += `${dot}${percent(usage.claude.scopedWeekly)}`;
+		parts.push(`${styled(palette.text, CLAUDE_ICON)} ${claude}`);
 	}
 	if (usage.codex) {
-		parts.push(`${styled(WHITE, OPENAI_ICON)} ${remainingPercent(usage.codex.weekly)}`);
+		parts.push(`${styled(palette.text, OPENAI_ICON)} ${percent(usage.codex.weekly)}`);
 	}
 	return parts.length > 0 ? parts.join(" ") : undefined;
 }
 
-function contextColor(contextTokens: number, contextWindow: number): string {
+function contextColor(contextTokens: number, contextWindow: number, palette: StatuslinePalette): string {
 	const percent = contextWindow > 0 ? Math.floor((contextTokens * 100) / contextWindow) : 0;
-	if (percent >= 90) return RED;
-	if (percent >= 70) return YELLOW;
-	if (percent >= 50) return ORANGE;
-	return GREEN;
+	if (percent >= 90) return palette.danger;
+	if (percent >= 70) return palette.warn;
+	if (percent >= 50) return palette.caution;
+	return palette.ok;
 }
 
 export function formatTokenCount(tokens: number): string {
@@ -86,65 +94,106 @@ export function formatTokenCount(tokens: number): string {
 	return `${safeTokens}`;
 }
 
-function renderRepository(name: string, status: GitRepositoryStatus, nameColor = WHITE): string {
+function renderRepository(
+	name: string,
+	status: GitRepositoryStatus,
+	palette: StatuslinePalette,
+	nameColor = palette.path,
+): string {
 	let part = styled(nameColor, name);
-	part += styled(DIM, ":");
-	part += styled(CYAN, status.branch);
-	if (status.dirty) part += styled(YELLOW, "*");
-	if (status.behind > 0) part += ` ${styled(ORANGE, `⇣${status.behind}`)}`;
+	part += styled(palette.dim, ":");
+	part += styled(palette.branch, status.branch);
+	if (status.dirty) part += styled(palette.warn, "*");
+	if (status.behind > 0) part += ` ${styled(palette.caution, `⇣${status.behind}`)}`;
 	return part;
 }
 
 export function renderCacheCelebrationLine(
 	summary: string,
 	celebration: CacheCelebrationSnapshot,
+	palette: StatuslinePalette = DEFAULT_PALETTE,
 ): string {
 	const badge = `⚡${celebration.percent}%·CACHE·HIT`;
-	const color = celebration.frame % 2 === 0 ? NEON_MAGENTA : NEON_CYAN;
+	const color = palette.celebration[celebration.frame % 2 === 0 ? 0 : 1];
 	const animatedBadge = `${BOLD}${color}${badge}${RESET}`;
-	return `${summary}${styled(DIM, " | ")}${animatedBadge}`;
+	return `${summary}${styled(palette.dim, " | ")}${animatedBadge}`;
 }
 
-function renderWorktreeLine(worktrees: SessionWorktree[]): string {
-	const separator = styled(DIM, " | ");
+function renderWorktreeLine(
+	worktrees: SessionWorktree[],
+	settings: StatuslineSettings,
+	palette: StatuslinePalette,
+): string {
+	const separator = styled(palette.dim, " | ");
 	const parts = worktrees.map((worktree) => {
-		let part = renderRepository(repoAlias(worktree.repo), worktree);
+		let part = renderRepository(repoAlias(worktree.repo, settings.repoAliases), worktree, palette);
 		if (worktree.pr !== undefined) {
 			const state = worktree.prState?.toUpperCase();
-			const color = state === "OPEN" ? GREEN : state === "MERGED" ? MAGENTA : state === "CLOSED" ? RED : DIM;
+			const color =
+				state === "OPEN"
+					? palette.ok
+					: state === "MERGED"
+						? palette.accent
+						: state === "CLOSED"
+							? palette.danger
+							: palette.dim;
 			part += ` ${styled(color, `#${worktree.pr}`)}`;
 		}
 		return part;
 	});
-	return `${styled(DIM, "⑂")} ${parts.join(separator)}`;
+	return `${styled(palette.dim, "⑂")} ${parts.join(separator)}`;
 }
 
-export function renderStatusline(data: StatuslineData, width: number): string[] {
-	const lineCount = data.worktrees.length > 0 ? 3 : 2;
-	if (width <= 0) return Array.from({ length: lineCount }, () => "");
+/** Home-independent defaults; only `worktreeRoot` varies by host and rendering never reads it. */
+const RENDER_DEFAULTS = defaultSettings("");
 
-	const separator = styled(DIM, " | ");
+export function renderStatusline(
+	data: StatuslineData,
+	width: number,
+	settings: StatuslineSettings = RENDER_DEFAULTS,
+): string[] {
+	const palette = resolvePalette(settings.theme);
+	const separator = styled(palette.dim, " | ");
 	const used =
 		data.contextTokens === null
-			? styled(DIM, "?")
-			: styled(contextColor(data.contextTokens, data.contextWindow), formatTokenCount(data.contextTokens));
-	const context = `${used}${styled(DIM, "/")}${styled(WHITE, formatTokenCount(data.contextWindow))}`;
-	const cwd = data.cwdGit ? renderRepository(data.cwd, data.cwdGit) : styled(CYAN, data.cwd);
-	const usageSegment = data.usage ? renderUsageSegment(data.usage) : undefined;
-	const summary =
-		styled(BLUE, data.model) +
-		separator +
-		cwd +
-		separator +
-		context +
-		(usageSegment ? separator + usageSegment : "");
-	const firstLine = data.cacheCelebration
-		? renderCacheCelebrationLine(summary, data.cacheCelebration)
-		: summary;
+			? styled(palette.dim, "?")
+			: styled(
+					contextColor(data.contextTokens, data.contextWindow, palette),
+					formatTokenCount(data.contextTokens),
+				);
+	const usageSegment = settings.showUsage && data.usage ? renderUsageSegment(data.usage, palette) : undefined;
+	const segments = [
+		settings.showModel ? styled(palette.model, data.model) : undefined,
+		settings.showDirectory
+			? data.cwdGit
+				? renderRepository(data.cwd, data.cwdGit, palette)
+				: styled(palette.branch, data.cwd)
+			: undefined,
+		settings.showContext
+			? `${used}${styled(palette.dim, "/")}${styled(palette.text, formatTokenCount(data.contextWindow))}`
+			: undefined,
+		usageSegment,
+	].filter((segment): segment is string => segment !== undefined);
+
+	const showWorktreeLine = settings.showWorktrees && data.worktrees.length > 0;
+	const lineCount = (segments.length > 0 ? 1 : 0) + (showWorktreeLine ? 1 : 0) + (settings.showSessionId ? 1 : 0);
+	// A footer that renders nothing would collapse the block; keep one stable row.
+	if (lineCount === 0) return [""];
+	if (width <= 0) return Array.from({ length: lineCount }, () => "");
 
-	const lines = [truncateToWidth(firstLine, width)];
-	if (data.worktrees.length > 0) lines.push(truncateToWidth(renderWorktreeLine(data.worktrees), width, "…"));
-	lines.push(truncateToWidth(styled(DIM, data.sessionId), width));
+	const lines: string[] = [];
+	if (segments.length > 0) {
+		const summary = segments.join(separator);
+		// A badge-only first line is separator soup, so the celebration needs a summary.
+		const celebration = settings.showCacheCelebration ? data.cacheCelebration : undefined;
+		lines.push(
+			truncateToWidth(celebration ? renderCacheCelebrationLine(summary, celebration, palette) : summary, width),
+		);
+	}
+	if (showWorktreeLine) {
+		lines.push(truncateToWidth(renderWorktreeLine(data.worktrees, settings, palette), width, "…"));
+	}
+	if (settings.showSessionId) lines.push(truncateToWidth(styled(palette.dim, data.sessionId), width));
 	return lines;
 }
 
@@ -157,6 +206,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	let cwdGit: GitRepositoryStatus | null = null;
 	let cwdStatusAbort: AbortController | undefined;
 	let cwdStatusInFlight: Promise<void> | undefined;
+	const home = homedir();
+	const settingsStore = new SettingsStore({ home });
+	let settings = settingsStore.get();
 
 	const runInBackground = (operation: Promise<void>): void => {
 		operation.catch(() => {
@@ -193,26 +245,105 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 
 	const resetTracker = (ctx: ExtensionContext): void => {
 		tracker?.dispose();
+		tracker = undefined;
 		cwdStatusAbort?.abort();
 		cwdGit = null;
 		cwdStatusAbort = new AbortController();
 		cwdStatusInFlight = undefined;
+		runInBackground(refreshCwdStatus(ctx));
+		if (settings.showUsage) runInBackground(usageTracker.refresh());
+		// A hidden worktree line must not pay for git/gh polling.
+		if (!settings.showWorktrees) return;
 		const next = new SessionWorktreeTracker({
 			exec: (command, args, options) => pi.exec(command, args, options),
-			home: process.env.HOME ?? "",
+			worktreeRoot: settings.worktreeRoot,
+			home,
 			onChange: () => requestRender?.(),
 		});
 		tracker = next;
-		runInBackground(refreshCwdStatus(ctx));
 		runInBackground(next.seedFromEntries(ctx.sessionManager.getBranch()));
 		runInBackground(next.includeCurrentWorktree(ctx.cwd));
-		runInBackground(usageTracker.refresh());
 	};
 
+	/** Adopt a new settings snapshot: apply it live, then persist in the background. */
+	const applySettings = (ctx: ExtensionContext, next: StatuslineSettings, persist = true): void => {
+		const previous = settings;
+		settings = next;
+		settingsStore.set(next);
+
+		if (!next.showWorktrees) {
+			tracker?.dispose();
+			tracker = undefined;
+		} else if (!previous.showWorktrees || !tracker || previous.worktreeRoot !== next.worktreeRoot) {
+			resetTracker(ctx);
+		}
+		if (next.showUsage && !previous.showUsage) runInBackground(usageTracker.refresh());
+		if (!next.showCacheCelebration) cacheCelebration.dispose();
+		// Dropping a row leaves a stale one behind in fullscreen mode.
+		if (previous.showSessionId !== next.showSessionId || previous.showWorktrees !== next.showWorktrees) {
+			fullRedraw.request();
+		}
+		requestRender?.();
+
+		if (!persist) return;
+		settingsStore.save(next).catch((error: unknown) => {
+			ctx.ui.notify(
+				`Could not save statusline settings: ${error instanceof Error ? error.message : String(error)}`,
+				"warning",
+			);
+		});
+	};
+
+	pi.registerCommand("statusline", {
+		description: "Configure the statusline",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/statusline requires interactive TUI mode", "warning");
+				return;
+			}
+
+			await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
+				const settingsTheme = getSettingsListTheme();
+				const submenuHost = {
+					getSettings: () => settings,
+					commit: (next: StatuslineSettings) => applySettings(ctx, next),
+					notify: (message: string) => ctx.ui.notify(message, "warning"),
+					requestRender: () => tui.requestRender(),
+					settingsTheme,
+					selectTheme: getSelectListTheme(),
+					home,
+				};
+				return new SettingsList(
+					buildSettingItems(
+						settings,
+						{
+							worktreeRoot: createWorktreeRootSubmenu(submenuHost),
+							repoAliases: createAliasSubmenu(submenuHost),
+						},
+						home,
+					),
+					10,
+					settingsTheme,
+					(id, value) => {
+						const change = applySettingChange(settings, id, value, home);
+						if (change.kind === "error") ctx.ui.notify(change.message, "warning");
+						else if (change.kind === "settings") applySettings(ctx, change.settings);
+						tui.requestRender();
+					},
+					() => done(undefined),
+					{ enableSearch: true },
+				);
+			});
+		},
+	});
+
 	pi.on("session_start", (_event, ctx) => {
 		cacheCelebration.dispose();
 		if (ctx.mode !== "tui") return;
 
+		// setFooter is synchronous, so the first frames render with defaults.
+		runInBackground(settingsStore.load().then((loaded) => applySettings(ctx, loaded, false)));
+
 		ctx.ui.setFooter((tui, _theme, footerData) => {
 			requestRender = () => tui.requestRender();
 			// Fullscreen mode never repaints unchanged rows; the session id line is
@@ -250,6 +381,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 								usage: usageTracker.snapshot(),
 							},
 							width,
+							settings,
 						),
 					);
 				},
@@ -263,12 +395,14 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		if (tracker) runInBackground(tracker.observeToolInput(event.toolName, event.input));
 	});
 	pi.on("turn_end", (event, ctx) => {
-		if (requestRender) triggerCacheCelebrationForMessage(event.message, cacheCelebration);
+		if (requestRender && settings.showCacheCelebration) {
+			triggerCacheCelebrationForMessage(event.message, cacheCelebration);
+		}
 		fullRedraw.request();
 		requestRender?.();
 		runInBackground(refreshCwdStatus(ctx));
 		if (tracker) runInBackground(tracker.refresh());
-		runInBackground(usageTracker.refresh());
+		if (settings.showUsage) runInBackground(usageTracker.refresh());
 	});
 	pi.on("model_select", () => requestRender?.());
 	pi.on("session_tree", (_event, ctx) => resetTracker(ctx));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [
@@ -34,6 +34,9 @@
     "index.ts",
     "cache-celebration.ts",
     "redraw.ts",
+    "settings.ts",
+    "settings-menu.ts",
+    "themes.ts",
     "usage.ts",
     "worktrees.ts",
     "README.md",

package/settings-menu.ts

@@ -0,0 +1,315 @@
+import { homedir } from "node:os";
+import {
+	type Component,
+	Input,
+	type SelectItem,
+	SelectList,
+	type SelectListTheme,
+	type SettingItem,
+	type SettingsListTheme,
+	truncateToWidth,
+} from "@earendil-works/pi-tui";
+import { type BooleanSettingKey, collapseHome, resolveWorktreeRoot, type StatuslineSettings } from "./settings.ts";
+import { isThemeName, THEME_NAMES } from "./themes.ts";
+
+export const THEME_ID = "theme";
+export const WORKTREE_ROOT_ID = "worktreeRoot";
+export const REPO_ALIASES_ID = "repoAliases";
+export const ADD_ALIAS_VALUE = "\u0000add";
+
+export const ON = "on";
+export const OFF = "off";
+const TOGGLE_VALUES = [ON, OFF];
+
+export interface BooleanRow {
+	id: BooleanSettingKey;
+	label: string;
+	description: string;
+}
+
+/** Toggle rows, in statusline render order. */
+export const BOOLEAN_ROWS: readonly BooleanRow[] = [
+	{ id: "showModel", label: "Model", description: "Show the active model id." },
+	{ id: "showDirectory", label: "Directory & git", description: "Show the working directory and its git branch." },
+	{ id: "showContext", label: "Context", description: "Show context tokens used against the window." },
+	{ id: "showUsage", label: "Subscription usage", description: "Show Claude/Codex remaining-headroom meters." },
+	{ id: "showWorktrees", label: "Worktree line", description: "Show touched worktrees and their pull requests." },
+	{ id: "showSessionId", label: "Session ID line", description: "Show the full Pi session id on its own line." },
+	{
+		id: "showCacheCelebration",
+		label: "Cache celebration",
+		description: "Flash a badge after an exceptional prompt-cache hit.",
+	},
+];
+
+export function toggleValue(enabled: boolean): string {
+	return enabled ? ON : OFF;
+}
+
+export function aliasSummary(settings: StatuslineSettings): string {
+	const count = Object.keys(settings.repoAliases).length;
+	return `${count} alias${count === 1 ? "" : "es"}`;
+}
+
+export interface SettingSubmenus {
+	worktreeRoot?: SettingItem["submenu"];
+	repoAliases?: SettingItem["submenu"];
+}
+
+/** Build the `/statusline` rows for a settings snapshot. */
+export function buildSettingItems(
+	settings: StatuslineSettings,
+	submenus: SettingSubmenus = {},
+	home: string = homedir(),
+): SettingItem[] {
+	const items: SettingItem[] = [
+		{
+			id: THEME_ID,
+			label: "Theme",
+			description: "Colour palette for every statusline element.",
+			currentValue: settings.theme,
+			values: [...THEME_NAMES],
+		},
+		...BOOLEAN_ROWS.map((row) => ({
+			id: row.id,
+			label: row.label,
+			description: row.description,
+			currentValue: toggleValue(settings[row.id]),
+			values: TOGGLE_VALUES,
+		})),
+	];
+
+	items.push({
+		id: WORKTREE_ROOT_ID,
+		label: "Worktree root",
+		description: "Directory whose children are tracked as session worktrees.",
+		currentValue: collapseHome(settings.worktreeRoot, home),
+		...(submenus.worktreeRoot ? { submenu: submenus.worktreeRoot } : {}),
+	});
+	items.push({
+		id: REPO_ALIASES_ID,
+		label: "Repo aliases",
+		description: "Short display names for repositories on the worktree line.",
+		currentValue: aliasSummary(settings),
+		...(submenus.repoAliases ? { submenu: submenus.repoAliases } : {}),
+	});
+
+	return items;
+}
+
+export type SettingChange =
+	| { kind: "settings"; settings: StatuslineSettings }
+	| { kind: "error"; message: string }
+	| { kind: "ignored" };
+
+/** Map one row's new display value onto the settings object. */
+export function applySettingChange(
+	settings: StatuslineSettings,
+	id: string,
+	value: string,
+	home: string = homedir(),
+): SettingChange {
+	if (BOOLEAN_ROWS.some((row) => row.id === id)) {
+		if (value !== ON && value !== OFF) return { kind: "error", message: `Unknown value for ${id}: ${value}` };
+		return { kind: "settings", settings: { ...settings, [id]: value === ON } };
+	}
+	if (id === THEME_ID) {
+		if (!isThemeName(value)) return { kind: "error", message: `Unknown statusline theme: ${value}` };
+		if (value === settings.theme) return { kind: "ignored" };
+		return { kind: "settings", settings: { ...settings, theme: value } };
+	}
+	if (id === WORKTREE_ROOT_ID) {
+		const resolved = resolveWorktreeRoot(value, home);
+		if (!resolved.path) return { kind: "error", message: resolved.error ?? "Invalid worktree root" };
+		if (resolved.path === settings.worktreeRoot) return { kind: "ignored" };
+		return { kind: "settings", settings: { ...settings, worktreeRoot: resolved.path } };
+	}
+	// Alias edits are committed by the submenu itself; its done() value is display text.
+	return { kind: "ignored" };
+}
+
+/** Parse an `repo=alias` (or `repo → alias`) submenu line. */
+export function parseAliasEntry(input: string): { repo: string; alias: string } | undefined {
+	const [rawRepo, ...rest] = input.split(/=|→/);
+	const repo = rawRepo?.trim() ?? "";
+	const alias = rest.join("=").trim();
+	if (repo.length === 0 || alias.length === 0) return undefined;
+	return { repo, alias };
+}
+
+export function aliasItems(settings: StatuslineSettings): SelectItem[] {
+	const items: SelectItem[] = Object.entries(settings.repoAliases)
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([repo, alias]) => ({ value: repo, label: `${repo} → ${alias}`, description: "Enter to edit · d to delete" }));
+	items.push({ value: ADD_ALIAS_VALUE, label: "Add alias…", description: "Enter a new repo=alias pair" });
+	return items;
+}
+
+export interface SubmenuHost {
+	/** Read the live settings; the menu edits a single shared snapshot. */
+	getSettings(): StatuslineSettings;
+	/** Commit an edit: persists, applies live, and repaints. */
+	commit(settings: StatuslineSettings): void;
+	notify(message: string): void;
+	requestRender(): void;
+	settingsTheme: SettingsListTheme;
+	selectTheme: SelectListTheme;
+	home?: string;
+}
+
+/** Single-line text prompt used by both submenus. */
+class PromptComponent implements Component {
+	private readonly input = new Input();
+
+	constructor(
+		private readonly title: string,
+		initialValue: string,
+		private readonly hint: (text: string) => string,
+		onSubmit: (value: string) => void,
+		onCancel: () => void,
+	) {
+		this.input.setValue(initialValue);
+		this.input.focused = true;
+		this.input.onSubmit = onSubmit;
+		this.input.onEscape = onCancel;
+	}
+
+	invalidate(): void {
+		this.input.invalidate();
+	}
+
+	render(width: number): string[] {
+		return [
+			truncateToWidth(this.hint(`  ${this.title}`), width),
+			"",
+			...this.input.render(width),
+			"",
+			truncateToWidth(this.hint("  Enter to save · Esc to cancel"), width),
+		];
+	}
+
+	handleInput(data: string): void {
+		this.input.handleInput(data);
+	}
+}
+
+export function createWorktreeRootSubmenu(host: SubmenuHost): NonNullable<SettingItem["submenu"]> {
+	const home = host.home ?? homedir();
+	return (currentValue, done) =>
+		new PromptComponent(
+			"Worktree root directory",
+			currentValue,
+			host.settingsTheme.hint,
+			(value) => {
+				const resolved = resolveWorktreeRoot(value, home);
+				if (!resolved.path) {
+					host.notify(resolved.error ?? "Invalid worktree root");
+					done(undefined);
+					return;
+				}
+				host.commit({ ...host.getSettings(), worktreeRoot: resolved.path });
+				done(collapseHome(resolved.path, home));
+			},
+			() => done(undefined),
+		);
+}
+
+/** Alias list submenu: edit, add, delete, toggle the prefix rule, load the preset. */
+class AliasSubmenu implements Component {
+	private list: SelectList;
+	private prompt: PromptComponent | undefined;
+
+	constructor(
+		private readonly host: SubmenuHost,
+		private readonly done: (value?: string) => void,
+	) {
+		this.list = this.buildList();
+	}
+
+	private buildList(selectedIndex = 0): SelectList {
+		const list = new SelectList(aliasItems(this.host.getSettings()), 10, this.host.selectTheme);
+		list.setSelectedIndex(selectedIndex);
+		list.onCancel = () => this.done(aliasSummary(this.host.getSettings()));
+		list.onSelect = (item) => this.activate(item);
+		return list;
+	}
+
+	private rebuild(selectedIndex: number): void {
+		this.list = this.buildList(selectedIndex);
+		this.host.requestRender();
+	}
+
+	private activate(item: SelectItem): void {
+		const settings = this.host.getSettings();
+		const editing = item.value === ADD_ALIAS_VALUE ? "" : `${item.value}=${settings.repoAliases[item.value] ?? ""}`;
+		this.prompt = new PromptComponent(
+			item.value === ADD_ALIAS_VALUE ? "New alias (repo=alias)" : "Edit alias (repo=alias)",
+			editing,
+			this.host.settingsTheme.hint,
+			(value) => this.submitAlias(item.value, value),
+			() => {
+				this.prompt = undefined;
+				this.host.requestRender();
+			},
+		);
+		this.host.requestRender();
+	}
+
+	private submitAlias(originalRepo: string, value: string): void {
+		this.prompt = undefined;
+		const parsed = parseAliasEntry(value);
+		if (!parsed) {
+			this.host.notify("Enter an alias as repo=alias");
+			this.host.requestRender();
+			return;
+		}
+		const settings = this.host.getSettings();
+		const aliases = { ...settings.repoAliases };
+		if (originalRepo !== ADD_ALIAS_VALUE && originalRepo !== parsed.repo) delete aliases[originalRepo];
+		aliases[parsed.repo] = parsed.alias;
+		this.host.commit({ ...settings, repoAliases: aliases });
+		this.rebuild(aliasItems(this.host.getSettings()).findIndex((row) => row.value === parsed.repo));
+	}
+
+	private deleteSelected(): void {
+		const selected = this.list.getSelectedItem();
+		if (!selected || selected.value.startsWith("\u0000")) return;
+		const settings = this.host.getSettings();
+		const aliases = { ...settings.repoAliases };
+		delete aliases[selected.value];
+		this.host.commit({ ...settings, repoAliases: aliases });
+		this.rebuild(0);
+	}
+
+	invalidate(): void {
+		this.prompt?.invalidate();
+		this.list.invalidate();
+	}
+
+	render(width: number): string[] {
+		if (this.prompt) return this.prompt.render(width);
+		return [
+			truncateToWidth(this.host.settingsTheme.hint("  Repo aliases"), width),
+			"",
+			...this.list.render(width),
+			"",
+			truncateToWidth(this.host.settingsTheme.hint("  Enter to edit · d to delete · Esc to go back"), width),
+		];
+	}
+
+	handleInput(data: string): void {
+		if (this.prompt) {
+			this.prompt.handleInput(data);
+			return;
+		}
+		if (data === "d") {
+			this.deleteSelected();
+			return;
+		}
+		this.list.handleInput(data);
+	}
+}
+
+export function createAliasSubmenu(host: SubmenuHost): NonNullable<SettingItem["submenu"]> {
+	return (_currentValue, done) => new AliasSubmenu(host, done);
+}

package/settings.ts

@@ -0,0 +1,231 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { pid } from "node:process";
+import { DEFAULT_THEME, isThemeName, type StatuslineThemeName } from "./themes.ts";
+
+/** Toggle keys, in the order the `/statusline` menu lists them. */
+export const BOOLEAN_SETTING_KEYS = [
+	"showModel",
+	"showDirectory",
+	"showContext",
+	"showUsage",
+	"showWorktrees",
+	"showSessionId",
+	"showCacheCelebration",
+] as const;
+
+export type BooleanSettingKey = (typeof BOOLEAN_SETTING_KEYS)[number];
+
+export interface StatuslineSettings extends Record<BooleanSettingKey, boolean> {
+	/** Colour palette name; see themes.ts. */
+	theme: StatuslineThemeName;
+	/** Directory whose immediate children are treated as session worktrees. */
+	worktreeRoot: string;
+	/** `repository name -> display alias` overrides for the worktree line. */
+	repoAliases: Record<string, string>;
+}
+
+export function defaultWorktreeRoot(home: string = homedir()): string {
+	return join(home || homedir(), "repos", "worktrees");
+}
+
+export function defaultSettings(home: string = homedir()): StatuslineSettings {
+	return {
+		showModel: true,
+		showDirectory: true,
+		showContext: true,
+		showUsage: true,
+		showWorktrees: true,
+		showSessionId: true,
+		showCacheCelebration: true,
+		theme: DEFAULT_THEME,
+		worktreeRoot: defaultWorktreeRoot(home),
+		repoAliases: {},
+	};
+}
+
+export function defaultSettingsPath(home: string = homedir()): string {
+	return join(home || homedir(), ".pi", "agent", "statusline-settings.json");
+}
+
+/** Expand a leading `~` (and `$HOME`) against `home`; other paths are returned as-is. */
+export function expandHome(path: string, home: string = homedir()): string {
+	const trimmed = path.trim();
+	const base = home || homedir();
+	if (trimmed === "~" || trimmed === "$HOME") return base;
+	if (trimmed.startsWith("~/")) return join(base, trimmed.slice(2));
+	if (trimmed.startsWith("$HOME/")) return join(base, trimmed.slice("$HOME/".length));
+	return trimmed;
+}
+
+/** Inverse of {@link expandHome}, for compact display in the menu. */
+export function collapseHome(path: string, home: string = homedir()): string {
+	const base = home || homedir();
+	if (!base) return path;
+	if (path === base) return "~";
+	return path.startsWith(`${base}/`) ? `~/${path.slice(base.length + 1)}` : path;
+}
+
+export interface WorktreeRootResult {
+	path?: string;
+	error?: string;
+}
+
+/** Validate a user-entered worktree root: `~`-expanded, and absolute afterwards. */
+export function resolveWorktreeRoot(input: string, home: string = homedir()): WorktreeRootResult {
+	const expanded = expandHome(input, home);
+	if (expanded.length === 0) return { error: "Worktree root cannot be empty" };
+	if (!isAbsolute(expanded)) return { error: `Worktree root must be an absolute path: ${input.trim()}` };
+	return { path: expanded.replace(/\/+$/, "") || "/" };
+}
+
+/** Resolve a repository's display alias; with an empty map this is the identity. */
+export function repoAlias(repo: string, aliases: Record<string, string> = {}): string {
+	return aliases[repo] ?? repo;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeAliases(value: unknown): Record<string, string> | undefined {
+	if (!isPlainObject(value)) return undefined;
+	const aliases: Record<string, string> = {};
+	for (const [repo, alias] of Object.entries(value)) {
+		if (repo.length > 0 && typeof alias === "string" && alias.length > 0) aliases[repo] = alias;
+	}
+	return aliases;
+}
+
+export interface NormalizedSettings {
+	settings: StatuslineSettings;
+	/** Top-level keys this version does not know about, preserved on write. */
+	extra: Record<string, unknown>;
+}
+
+/**
+ * Best-effort normalization: every key falls back to its own default without
+ * discarding valid siblings, and unknown keys are carried through untouched.
+ */
+export function normalizeSettings(value: unknown, home: string = homedir()): NormalizedSettings {
+	const settings = defaultSettings(home);
+	const extra: Record<string, unknown> = {};
+	if (!isPlainObject(value)) return { settings, extra };
+
+	const known = new Set<string>([...BOOLEAN_SETTING_KEYS, "theme", "worktreeRoot", "repoAliases"]);
+	for (const [key, raw] of Object.entries(value)) {
+		if (!known.has(key)) {
+			extra[key] = raw;
+			continue;
+		}
+		if (key === "worktreeRoot") {
+			if (typeof raw === "string") {
+				const resolved = resolveWorktreeRoot(raw, home);
+				if (resolved.path) settings.worktreeRoot = resolved.path;
+			}
+			continue;
+		}
+		if (key === "repoAliases") {
+			const aliases = normalizeAliases(raw);
+			if (aliases) settings.repoAliases = aliases;
+			continue;
+		}
+		if (key === "theme") {
+			if (isThemeName(raw)) settings.theme = raw;
+			continue;
+		}
+		if (typeof raw === "boolean") settings[key as BooleanSettingKey] = raw;
+	}
+
+	return { settings, extra };
+}
+
+function sameAliases(a: Record<string, string>, b: Record<string, string>): boolean {
+	const aKeys = Object.keys(a);
+	if (aKeys.length !== Object.keys(b).length) return false;
+	return aKeys.every((key) => a[key] === b[key]);
+}
+
+/**
+ * Sparse serialization: only values differing from the defaults are written, so
+ * a later default change still reaches hosts that never touched that key.
+ */
+export function serializeSettings(
+	settings: StatuslineSettings,
+	extra: Record<string, unknown> = {},
+	home: string = homedir(),
+): Record<string, unknown> {
+	const defaults = defaultSettings(home);
+	const out: Record<string, unknown> = { ...extra };
+	for (const key of BOOLEAN_SETTING_KEYS) {
+		if (settings[key] !== defaults[key]) out[key] = settings[key];
+	}
+	if (settings.theme !== defaults.theme) out.theme = settings.theme;
+	if (settings.worktreeRoot !== defaults.worktreeRoot) out.worktreeRoot = settings.worktreeRoot;
+	if (!sameAliases(settings.repoAliases, defaults.repoAliases)) out.repoAliases = { ...settings.repoAliases };
+	return out;
+}
+
+export interface SettingsStoreOptions {
+	path?: string;
+	home?: string;
+}
+
+/**
+ * Owns the single global settings file. Extensions get no settings API, so this
+ * mirrors what usage.ts already does for its shared cache.
+ */
+export class SettingsStore {
+	private readonly home: string;
+	private readonly path: string;
+	private extra: Record<string, unknown> = {};
+	private current: StatuslineSettings;
+
+	constructor(options: SettingsStoreOptions = {}) {
+		this.home = options.home ?? homedir();
+		this.path = options.path ?? defaultSettingsPath(this.home);
+		this.current = defaultSettings(this.home);
+	}
+
+	getPath(): string {
+		return this.path;
+	}
+
+	get(): StatuslineSettings {
+		return this.current;
+	}
+
+	set(settings: StatuslineSettings): void {
+		this.current = settings;
+	}
+
+	/** Never throws: a missing, unreadable, or malformed file yields defaults. */
+	async load(): Promise<StatuslineSettings> {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(await readFile(this.path, "utf8"));
+		} catch {
+			parsed = undefined;
+		}
+		const { settings, extra } = normalizeSettings(parsed, this.home);
+		this.extra = extra;
+		this.current = settings;
+		return settings;
+	}
+
+	/** Atomic write via temp file + rename. Rejects so the caller can notify. */
+	async save(settings: StatuslineSettings = this.current): Promise<void> {
+		this.current = settings;
+		const payload = `${JSON.stringify(serializeSettings(settings, this.extra, this.home), null, "\t")}\n`;
+		const temporary = `${this.path}.${pid}.tmp`;
+		await mkdir(dirname(this.path), { recursive: true });
+		try {
+			await writeFile(temporary, payload, { mode: 0o600 });
+			await rename(temporary, this.path);
+		} catch (error) {
+			await unlink(temporary).catch(() => {});
+			throw error;
+		}
+	}
+}

package/themes.ts

@@ -0,0 +1,128 @@
+/**
+ * Statusline colour palettes. Every role is a full SGR prefix so a theme can use
+ * a true-colour value, a plain attribute (`\x1b[2m`), or both.
+ */
+export interface StatuslinePalette {
+	/** Active model id. */
+	model: string;
+	/** Repository and directory names. */
+	path: string;
+	/** Git branch names. */
+	branch: string;
+	/** Neutral figures: the context window total and the usage provider icons. */
+	text: string;
+	/** Separators, the session id, and unknown values. */
+	dim: string;
+	/** Healthy: low context use, high remaining usage, an open PR. */
+	ok: string;
+	/** First warning step, and the dirty-checkout marker. */
+	warn: string;
+	/** Second warning step, and the commits-behind marker. */
+	caution: string;
+	/** Exhausted: high context use, low remaining usage, a closed PR. */
+	danger: string;
+	/** Merged pull requests. */
+	accent: string;
+	/** The two colours the cache-hit badge alternates between. */
+	celebration: readonly [string, string];
+}
+
+const rgb = (hex: string): string => {
+	const value = Number.parseInt(hex.slice(1), 16);
+	return `\x1b[38;2;${(value >> 16) & 0xff};${(value >> 8) & 0xff};${value & 0xff}m`;
+};
+
+/** The palette this package shipped before themes existed. */
+const DEFAULT: StatuslinePalette = {
+	model: rgb("#0099ff"),
+	path: rgb("#dcdcdc"),
+	branch: rgb("#56b6c2"),
+	text: rgb("#dcdcdc"),
+	dim: "\x1b[2m",
+	ok: rgb("#00af50"),
+	warn: rgb("#e6c800"),
+	caution: rgb("#ffb055"),
+	danger: rgb("#ff5555"),
+	accent: rgb("#be78ff"),
+	celebration: [rgb("#ff00ff"), rgb("#00ffff")],
+};
+
+/** Dracula, with the pink branch colour from Hank's Herdr sidebar config. */
+const DRACULA: StatuslinePalette = {
+	model: rgb("#bd93f9"),
+	path: rgb("#f8f8f2"),
+	branch: rgb("#ff79c6"),
+	text: rgb("#f8f8f2"),
+	dim: rgb("#6272a4"),
+	ok: rgb("#50fa7b"),
+	warn: rgb("#f1fa8c"),
+	caution: rgb("#ffb86c"),
+	danger: rgb("#ff5555"),
+	accent: rgb("#8be9fd"),
+	celebration: [rgb("#ff79c6"), rgb("#8be9fd")],
+};
+
+const GITHUB_DARK: StatuslinePalette = {
+	model: rgb("#58a6ff"),
+	path: rgb("#c9d1d9"),
+	branch: rgb("#39c5cf"),
+	text: rgb("#c9d1d9"),
+	dim: rgb("#8b949e"),
+	ok: rgb("#3fb950"),
+	warn: rgb("#d29922"),
+	caution: rgb("#db6d28"),
+	danger: rgb("#f85149"),
+	accent: rgb("#bc8cff"),
+	celebration: [rgb("#bc8cff"), rgb("#39c5cf")],
+};
+
+const CATPPUCCIN_MOCHA: StatuslinePalette = {
+	model: rgb("#cba6f7"),
+	path: rgb("#cdd6f4"),
+	branch: rgb("#89dceb"),
+	text: rgb("#cdd6f4"),
+	dim: rgb("#6c7086"),
+	ok: rgb("#a6e3a1"),
+	warn: rgb("#f9e2af"),
+	caution: rgb("#fab387"),
+	danger: rgb("#f38ba8"),
+	accent: rgb("#f5c2e7"),
+	celebration: [rgb("#cba6f7"), rgb("#89dceb")],
+};
+
+/** No colour at all: white text, dimmed punctuation, a grey badge flash. */
+const WHITE: StatuslinePalette = {
+	model: rgb("#ffffff"),
+	path: rgb("#ffffff"),
+	branch: rgb("#ffffff"),
+	text: rgb("#ffffff"),
+	dim: "\x1b[2m",
+	ok: rgb("#ffffff"),
+	warn: rgb("#ffffff"),
+	caution: rgb("#ffffff"),
+	danger: rgb("#ffffff"),
+	accent: rgb("#ffffff"),
+	celebration: [rgb("#ffffff"), rgb("#888888")],
+};
+
+export const STATUSLINE_THEMES = {
+	default: DEFAULT,
+	dracula: DRACULA,
+	"github-dark": GITHUB_DARK,
+	"catppuccin-mocha": CATPPUCCIN_MOCHA,
+	white: WHITE,
+} as const satisfies Record<string, StatuslinePalette>;
+
+export type StatuslineThemeName = keyof typeof STATUSLINE_THEMES;
+
+export const DEFAULT_THEME: StatuslineThemeName = "default";
+export const THEME_NAMES = Object.keys(STATUSLINE_THEMES) as StatuslineThemeName[];
+
+export function isThemeName(value: unknown): value is StatuslineThemeName {
+	return typeof value === "string" && value in STATUSLINE_THEMES;
+}
+
+/** Resolve a theme name to its palette; anything unknown falls back to the default. */
+export function resolvePalette(name: string): StatuslinePalette {
+	return isThemeName(name) ? STATUSLINE_THEMES[name] : STATUSLINE_THEMES[DEFAULT_THEME];
+}

package/worktrees.ts

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ExecResult } from "@earendil-works/pi-coding-agent";
 
@@ -34,7 +35,10 @@ export interface WorktreeTrackerHost {
 		args: string[],
 		options: { cwd?: string; timeout?: number; signal?: AbortSignal },
 	): Promise<ExecResult>;
-	home: string;
+	/** Directory whose immediate children are tracked as session worktrees. */
+	worktreeRoot: string;
+	/** Home directory used to recognise `~`/`$HOME` spellings of the root. */
+	home?: string;
 	now?: () => number;
 	onChange?: () => void;
 }
@@ -94,24 +98,48 @@ function visitStrings(value: unknown, visit: (value: string) => void): void {
 	for (const item of Object.values(value)) visitStrings(item, visit);
 }
 
-export function extractWorktreePaths(value: unknown, home: string): string[] {
+function trimTrailingSlashes(path: string): string {
+	return path.replace(/\/+$/, "") || path.slice(0, 1);
+}
+
+/**
+ * Spellings of the configured root that may appear in tool arguments: the
+ * absolute path, plus the `~/` and `$HOME/` forms when it lives under home.
+ */
+export function worktreeRootNeedles(worktreeRoot: string, home: string = homedir()): string[] {
+	const root = trimTrailingSlashes(worktreeRoot);
+	if (root.length === 0) return [];
+	const needles = [`${root}/`];
+	const base = trimTrailingSlashes(home ?? "");
+	if (base.length > 0 && root.startsWith(`${base}/`)) {
+		const relative = root.slice(base.length + 1);
+		if (relative.length > 0) needles.push(`~/${relative}/`, `$HOME/${relative}/`);
+	}
+	return needles;
+}
+
+export function extractWorktreePaths(value: unknown, worktreeRoot: string, home: string = homedir()): string[] {
 	const names = new Set<string>();
-	const needle = "repos/worktrees/";
+	const needles = worktreeRootNeedles(worktreeRoot, home);
+	if (needles.length === 0) return [];
 
 	visitStrings(value, (text) => {
-		let rest = text;
-		while (true) {
-			const index = rest.indexOf(needle);
-			if (index < 0) break;
-			rest = rest.slice(index + needle.length);
-			const name = rest.match(/^[a-zA-Z0-9._-]+/)?.[0];
-			if (name) names.add(name);
-			if (rest.length === 0) break;
-			rest = rest.slice(Math.max(1, name?.length ?? 0));
+		for (const needle of needles) {
+			let rest = text;
+			while (true) {
+				const index = rest.indexOf(needle);
+				if (index < 0) break;
+				rest = rest.slice(index + needle.length);
+				const name = rest.match(/^[a-zA-Z0-9._-]+/)?.[0];
+				if (name) names.add(name);
+				if (rest.length === 0) break;
+				rest = rest.slice(Math.max(1, name?.length ?? 0));
+			}
 		}
 	});
 
-	return [...names].sort().map((name) => join(home, "repos", "worktrees", name));
+	const root = trimTrailingSlashes(worktreeRoot);
+	return [...names].sort().map((name) => join(root, name));
 }
 
 function stripHeredocBodies(command: string): string {
@@ -137,17 +165,28 @@ function stripHeredocBodies(command: string): string {
 	return visible.join("\n");
 }
 
-export function extractWorktreePathsFromToolCall(toolName: string, input: unknown, home: string): string[] {
+export function extractWorktreePathsFromToolCall(
+	toolName: string,
+	input: unknown,
+	worktreeRoot: string,
+	home: string = homedir(),
+): string[] {
 	const baseName = toolName.slice(toolName.lastIndexOf(".") + 1);
 	if (baseName !== "bash" || !input || typeof input !== "object" || Array.isArray(input)) {
-		return extractWorktreePaths(input, home);
+		return extractWorktreePaths(input, worktreeRoot, home);
 	}
 
 	const command = (input as { command?: unknown }).command;
-	return typeof command === "string" ? extractWorktreePaths(stripHeredocBodies(command), home) : [];
+	return typeof command === "string"
+		? extractWorktreePaths(stripHeredocBodies(command), worktreeRoot, home)
+		: [];
 }
 
-export function extractWorktreePathsFromEntries(entries: readonly unknown[], home: string): string[] {
+export function extractWorktreePathsFromEntries(
+	entries: readonly unknown[],
+	worktreeRoot: string,
+	home: string = homedir(),
+): string[] {
 	const paths = new Set<string>();
 
 	for (const entry of entries) {
@@ -161,30 +200,15 @@ export function extractWorktreePathsFromEntries(entries: readonly unknown[], hom
 			if (!block || typeof block !== "object") continue;
 			const toolCall = block as { type?: unknown; name?: unknown; arguments?: unknown };
 			if (toolCall.type !== "toolCall" || typeof toolCall.name !== "string") continue;
-			for (const path of extractWorktreePathsFromToolCall(toolCall.name, toolCall.arguments, home)) paths.add(path);
+			for (const path of extractWorktreePathsFromToolCall(toolCall.name, toolCall.arguments, worktreeRoot, home)) {
+				paths.add(path);
+			}
 		}
 	}
 
 	return [...paths].sort();
 }
 
-export function repoAlias(repo: string): string {
-	switch (repo) {
-		case "model-runtime-engine":
-			return "mre";
-		case "frontend":
-			return "fe";
-		case "infrastructure":
-			return "infra";
-		case "platform-releases":
-			return "rel";
-		case "np-integration-testing":
-			return "tests";
-		default:
-			return repo.startsWith("platform-") ? repo.slice("platform-".length) : repo;
-	}
-}
-
 export async function readWorktreeMetadata(path: string): Promise<WorktreeMetadata | undefined> {
 	try {
 		const gitFile = await readFile(join(path, ".git"), "utf8");
@@ -242,13 +266,15 @@ export class SessionWorktreeTracker {
 	}
 
 	async seedFromEntries(entries: readonly unknown[]): Promise<void> {
-		for (const path of extractWorktreePathsFromEntries(entries, this.host.home)) this.trackedPaths.add(path);
+		for (const path of extractWorktreePathsFromEntries(entries, this.host.worktreeRoot, this.host.home)) {
+			this.trackedPaths.add(path);
+		}
 		await this.refresh();
 	}
 
 	async observeToolInput(toolName: string, input: unknown): Promise<void> {
 		const added: string[] = [];
-		for (const path of extractWorktreePathsFromToolCall(toolName, input, this.host.home)) {
+		for (const path of extractWorktreePathsFromToolCall(toolName, input, this.host.worktreeRoot, this.host.home)) {
 			if (this.trackedPaths.has(path)) continue;
 			this.trackedPaths.add(path);
 			added.push(path);