@vinh0809it/claude-sessions 0.3.1 → 0.4.0

package/README.md

@@ -25,10 +25,6 @@ npm install -g @vinh0809it/claude-sessions
 
 # Or run without installing
 npx @vinh0809it/claude-sessions
-
-# Or manually
-curl -fsSL https://raw.githubusercontent.com/vinh0809it/claude-sessions/main/index.js \
-  -o ~/.local/bin/claude-sessions && chmod +x ~/.local/bin/claude-sessions
 ```
 
 Requires Node.js 18+.
@@ -89,7 +85,7 @@ Sessions are grouped by profile in the UI. Press `m` to move a session to a diff
 |----------|---------|-------|
 | **Kitty** | ✅ new tab | Requires `allow_remote_control yes` in `kitty.conf` |
 | **WezTerm** | ✅ new tab | Uses `wezterm cli spawn` |
-| **tmux** | ✅ new window | In the current session |
+| **tmux** | ✅ new window | In the current session, also when tmux runs inside kitty or WezTerm |
 | **iTerm2** | ✅ new tab | Via `osascript` |
 | **Terminal.app** | ✅ new window | Via `osascript` |
 | **Windows Terminal** | ✅ new tab | Via `wt new-tab` (native Windows; in WSL it resumes in place) |
@@ -130,15 +126,34 @@ Deleted sessions are moved to `<config dir>/.claude-sessions-trash/`; run `claud
 
 ## Contributing
 
-Issues and PRs welcome. The entire tool is a single `index.js` with no build step.
+Issues and PRs welcome. Plain Node.js (CommonJS), no dependencies and no build step.
 
 ```sh
 git clone https://github.com/vinh0809it/claude-sessions
 cd claude-sessions
-node index.js          # run directly
-npm link               # install globally from source
-npm test               # run the test suite (Node built-in test runner, no extra deps)
-scripts/demo/record.sh # re-record docs/demo.gif from fake sessions (needs Pillow + ffmpeg)
+node bin/claude-sessions.js   # run directly
+npm link                      # install globally from source
+npm test                      # run the test suite (Node built-in test runner)
+scripts/demo/record.sh        # re-record docs/demo.gif from fake sessions (needs Pillow + ffmpeg)
+```
+
+```
+bin/claude-sessions.js   entry point
+lib/
+  cli.js                 argument handling, --list / --json output
+  config.js              usage text, flags, config dir discovery
+  sessions.js            reading session files, metadata cache, scanning
+  operations.js          move, rename, delete to trash, empty trash
+  launch.js              terminal detection, opening sessions
+  paths.js               folder-name encoding, path completion
+  format.js              dates, sizes, paths for display
+  ansi.js                escape sequences and colors
+  tui/
+    app.js               the full-screen browser
+    picker.js            profile → folder → path picker (move, new)
+    line-input.js        editable text field
+    keys.js              key codes and input splitting
+test/                    one file per module
 ```
 
 ## License

package/bin/claude-sessions.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../lib/cli').main();

package/lib/ansi.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Terminal escape sequences and text styling.
+//
+// Each style helper resets only its own attribute, so a row background survives
+// nested colors. NO_COLOR (https://no-color.org) drops colors but keeps
+// bold, dim and inverse.
+
+const ESC = '\x1b';
+const COLOR = !process.env.NO_COLOR;
+
+const screen = {
+  clearLine:  `${ESC}[2K`,
+  clearToEnd: `${ESC}[K`,
+  clear:      `${ESC}[2J`,
+  hideCursor: `${ESC}[?25l`,
+  showCursor: `${ESC}[?25h`,
+  altBuffer:  `${ESC}[?1049h`,
+  mainBuffer: `${ESC}[?1049l`,
+  reset:      `${ESC}[0m`,
+  moveTo:     (row, col) => `${ESC}[${row};${col}H`,
+};
+
+const bold = s => `${ESC}[1m${s}${ESC}[22m`;
+const dim  = s => `${ESC}[2m${s}${ESC}[22m`;
+const inv  = s => `${ESC}[7m${s}${ESC}[27m`;
+const fg   = (code, s) => COLOR ? `${ESC}[${code}m${s}${ESC}[22;39m` : s;
+const bg   = (code, s) => COLOR ? `${ESC}[${code}m${s}${ESC}[49m` : s;
+
+const trunc = (s, n) => n > 0 && s.length > n ? s.slice(0, n - 1) + '…' : s;
+const pad   = (s, n) => s.padEnd(n).slice(0, n);
+
+const SELECTED_BG = `${ESC}[48;5;236m`;
+
+/**
+ * A selected line: dark background with an accent bar, or inverse video when
+ * colors are off. `styled` must color every visible part explicitly so the line
+ * stays readable on light themes; `plain` is the same text without styling.
+ */
+function selectedLine(styled, plain, width) {
+  return COLOR
+    ? `${SELECTED_BG}${fg('96', '▌')}${styled}${screen.clearToEnd}${screen.reset}`
+    : inv(pad(` ${plain}`, width));
+}
+
+/** "Enter=open  /=search" → each key in bold, its label dimmed. */
+function styleHints(s) {
+  return s.replace(/(\S+)=(.+?)(?=  |$)/g, (_, key, label) => `${bold(key)} ${dim(label)}`);
+}
+
+/**
+ * "keycloak/fix-login" → the group prefix gets its own color so related
+ * sessions stand out. `style` lets plain-output callers pass their own helper.
+ */
+function groupTitle(title, color, style = fg) {
+  const i = title.indexOf('/');
+  return i > 0
+    ? style('95', title.slice(0, i + 1)) + style(color, title.slice(i + 1))
+    : style(color, title);
+}
+
+module.exports = {
+  COLOR, screen,
+  bold, dim, inv, fg, bg, trunc, pad,
+  selectedLine, styleHints, groupTitle,
+};

package/lib/cli.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const path = require('path');
+const { version } = require('../package.json');
+const { groupTitle } = require('./ansi');
+const { USAGE, parseArgs, discoverConfigDirs } = require('./config');
+const { fmtDate, fmtSize, shortenPath } = require('./format');
+const { cache, loadSessions } = require('./sessions');
+const { emptyTrash } = require('./operations');
+const { App } = require('./tui/app');
+
+/** Color helper for plain output: styled only when writing to a terminal. */
+function color(code, s) {
+  return process.stdout.isTTY && !process.env.NO_COLOR ? `\x1b[${code}m${s}\x1b[0m` : s;
+}
+
+/** Sessions grouped by profile and project, for --list or piped output. */
+function printList(sessions) {
+  if (!sessions.length) { console.log('No sessions found.'); return; }
+  let lastConfig = null, lastProject = null;
+  for (const s of sessions) {
+    if (s.configDir !== lastConfig) {
+      if (lastConfig) console.log();
+      console.log(color('1;36', `[${s.configDir}]`));
+      lastConfig = s.configDir;
+      lastProject = null;
+    }
+    if (s.project !== lastProject) {
+      console.log(color('33', `  ${shortenPath(s.project)}`));
+      lastProject = s.project;
+    }
+    const label = s.title
+      ? groupTitle(s.title, '1;32', color)
+      : color('2', `(${(s.firstMessage || 'untitled').slice(0, 60)}…)`);
+    console.log(`    ${label}  ${color('2', `${fmtDate(s.lastModified)}  ${fmtSize(s.size)}`)}`);
+    console.log(color('2', `    id: ${s.sessionId}`));
+  }
+}
+
+function printJson(sessions) {
+  const out = sessions.map(({ jsonlPath: _j, configDirPath: _c, ...rest }) => rest);
+  console.log(JSON.stringify(out, null, 2));
+}
+
+function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.version) { console.log(version); return; }
+  if (opts.help)    { console.log(USAGE); return; }
+  if (opts.noCache) cache.enabled = false;
+
+  if (opts.emptyTrash) {
+    const dirs = opts.dir ? [path.resolve(opts.dir)] : discoverConfigDirs();
+    console.log(`Freed ${fmtSize(emptyTrash(dirs))}`);
+    return;
+  }
+
+  const sessions = loadSessions(opts);
+  if (opts.json) printJson(sessions);
+  else if (opts.list || !process.stdout.isTTY || !process.stdin.isTTY) printList(sessions);
+  else new App(sessions, opts).start();
+}
+
+module.exports = { main };

package/lib/config.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { expandHome } = require('./paths');
+
+const USAGE = `\
+claude-sessions — Terminal UI for Claude Code sessions
+
+Usage:
+  claude-sessions [folder]        TUI, optionally filtered by folder path
+  claude-sessions --list [folder] Plain list output
+  claude-sessions --named-only    Only /rename'd sessions
+  claude-sessions --json          JSON output
+  claude-sessions -d <path>       Scan a specific config dir
+  claude-sessions --empty-trash   Permanently remove deleted sessions
+  claude-sessions --no-cache      Ignore the metadata cache
+  claude-sessions --version       Print version
+  claude-sessions -h              Help
+
+TUI keys:
+  ↑ ↓  j k         Navigate
+  PgUp PgDn        Page up / down
+  g G              Jump to top / bottom
+  /                Search (↑↓ select, Enter open, Tab keep filter)
+  Esc              Clear search / marks
+  Enter            Open session (new tab if supported, else here)
+  o                Open session in this terminal
+  p                Toggle preview of recent messages
+  r                Rename session
+  s                Cycle sort: date / size / name
+  Space            Mark session (for bulk delete)
+  n                New session
+  m                Move session to another config / folder
+  d                Delete session(s) to trash
+  ?                Help
+  q  Ctrl-C        Quit
+
+Environment variables:
+  CLAUDE_SESSIONS_TERMINAL    Force terminal: kitty | wezterm | tmux | iterm2 | apple-terminal | windows-terminal | here
+  CLAUDE_SESSIONS_OPEN_CMD    Custom open command (placeholders: %cmd% %title% %project%)
+  CLAUDE_CONFIG_DIR           Also scanned when set
+  NO_COLOR                    Disable colors`;
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const opts = {
+    dir: null, namedOnly: false, json: false, list: false, help: false, version: false,
+    filterPath: null, emptyTrash: false, noCache: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if      (a === '-d' || a === '--dir')     opts.dir = argv[++i];
+    else if (a === '--named-only')            opts.namedOnly = true;
+    else if (a === '--json')                  opts.json = true;
+    else if (a === '--list')                  opts.list = true;
+    else if (a === '--empty-trash')           opts.emptyTrash = true;
+    else if (a === '--no-cache')              opts.noCache = true;
+    else if (a === '--version' || a === '-v') opts.version = true;
+    else if (a === '-h' || a === '--help')    opts.help = true;
+    else if (!a.startsWith('-'))              opts.filterPath = path.resolve(expandHome(a));
+  }
+  return opts;
+}
+
+function hasProjects(dir) {
+  try { return fs.statSync(path.join(dir, 'projects')).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Every Claude Code config dir: ~/.claude, ~/.claude-*, and $CLAUDE_CONFIG_DIR.
+ * Named profiles come first, the default ~/.claude last.
+ */
+function discoverConfigDirs() {
+  const home = os.homedir();
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(home)
+      .filter(n => n === '.claude' || n.startsWith('.claude-'))
+      .map(n => path.join(home, n));
+  } catch {}
+  if (process.env.CLAUDE_CONFIG_DIR) dirs.push(path.resolve(process.env.CLAUDE_CONFIG_DIR));
+  return [...new Set(dirs)]
+    .filter(hasProjects)
+    .sort((a, b) => {
+      const na = path.basename(a), nb = path.basename(b);
+      if (na === '.claude') return 1;
+      if (nb === '.claude') return -1;
+      return na.localeCompare(nb);
+    });
+}
+
+module.exports = { USAGE, parseArgs, discoverConfigDirs };

package/lib/format.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const os   = require('os');
+const path = require('path');
+
+/** "2026-11-10 15:45" in local time. */
+function fmtDate(date) {
+  const t = new Date(date);
+  const p = n => String(n).padStart(2, '0');
+  return `${t.getFullYear()}-${p(t.getMonth() + 1)}-${p(t.getDate())} ${p(t.getHours())}:${p(t.getMinutes())}`;
+}
+
+/** "just now", "5m ago", "2h ago", "3d ago", "2mo ago", "1y ago". */
+function fmtAgo(date, now = Date.now()) {
+  const minutes = Math.floor((now - new Date(date)) / 60000);
+  if (minutes < 1)      return 'just now';
+  if (minutes < 60)     return `${minutes}m ago`;
+  if (minutes < 1440)   return `${Math.floor(minutes / 60)}h ago`;
+  if (minutes < 43200)  return `${Math.floor(minutes / 1440)}d ago`;
+  if (minutes < 525600) return `${Math.floor(minutes / 43200)}mo ago`;
+  return `${Math.floor(minutes / 525600)}y ago`;
+}
+
+/** Bytes as "512B", "1.5K", "13M", "1.2G". */
+function fmtSize(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  const units = ['K', 'M', 'G'];
+  let n = bytes, i = -1;
+  do { n /= 1024; i++; } while (n >= 1024 && i < units.length - 1);
+  return `${n < 10 ? n.toFixed(1) : Math.round(n)}${units[i]}`;
+}
+
+/** "/home/me/x" → "~/x". */
+function shortenPath(p) {
+  const home = os.homedir();
+  const underHome = p === home || p.startsWith(home + path.sep) || p.startsWith(home + '/');
+  return underHome ? '~' + p.slice(home.length) : p;
+}
+
+/** ".claude-work" → "work", ".claude" → "default". */
+function shortConfig(configDir) {
+  return path.basename(configDir).replace(/^\.claude-?/, '') || 'default';
+}
+
+module.exports = { fmtDate, fmtAgo, fmtSize, shortenPath, shortConfig };

package/lib/launch.js

@@ -0,0 +1,164 @@
+'use strict';
+
+// Starting `claude` for a session: in a new terminal tab when the terminal
+// supports it, otherwise in the current one.
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { readSession } = require('./sessions');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+// Tab commands return at once; this keeps a stuck one (e.g. `kitty @` waiting
+// for a reply that never comes) from freezing the UI.
+const SPAWN_TIMEOUT_MS = 5000;
+
+/**
+ * kitty | wezterm | tmux | iterm2 | apple-terminal | windows-terminal | here
+ * (`here` = run in the current terminal).
+ */
+function detectTerminal(env = process.env, platform = process.platform) {
+  if (env.CLAUDE_SESSIONS_TERMINAL) return env.CLAUDE_SESSIONS_TERMINAL;
+  // tmux first: it is always the innermost layer, and a tmux started from kitty or
+  // WezTerm inherits their variables even though their tab commands can't reach it.
+  if (env.TMUX)                              return 'tmux';
+  if (env.KITTY_WINDOW_ID !== undefined)     return 'kitty';
+  if (env.WEZTERM_PANE    !== undefined)     return 'wezterm';
+  if (env.TERM_PROGRAM === 'iTerm.app')      return 'iterm2';
+  if (env.TERM_PROGRAM === 'Apple_Terminal') return 'apple-terminal';
+  // WSL also sees WT_SESSION, but there `wt` would open a Windows shell, not Linux.
+  if (env.WT_SESSION && platform === 'win32') return 'windows-terminal';
+  return 'here';
+}
+
+/** POSIX shell single-quoting. */
+function shellEsc(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
+
+/** AppleScript string literal. */
+function appleStr(s) { return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'; }
+
+function trySpawn(cmd, args) {
+  const r = spawnSync(cmd, args, { stdio: ['ignore', 'ignore', 'pipe'], timeout: SPAWN_TIMEOUT_MS });
+  if (r.error) {
+    const reason = r.error.code === 'ENOENT' ? 'not found'
+      : r.error.code === 'ETIMEDOUT' ? 'timed out'
+      : r.error.message;
+    return { ok: false, msg: `${cmd}: ${reason}` };
+  }
+  return r.status === 0
+    ? { ok: true }
+    : { ok: false, msg: r.stderr?.toString().trim() || `${cmd} exited with ${r.status}` };
+}
+
+/**
+ * The directory to resume a session in: the folder's .project-path hint, else
+ * the cwd of a sibling session, else the recorded project, else $HOME.
+ */
+function resolveProjectPath(session) {
+  const sessionDir = path.dirname(session.jsonlPath);
+  try {
+    const hint = fs.readFileSync(path.join(sessionDir, '.project-path'), 'utf8').trim();
+    if (hint && fs.existsSync(hint)) return hint;
+  } catch {}
+  try {
+    const siblings = fs.readdirSync(sessionDir)
+      .filter(f => f.endsWith('.jsonl') && f !== path.basename(session.jsonlPath));
+    for (const sibling of siblings) {
+      const { cwd } = readSession(path.join(sessionDir, sibling));
+      if (cwd && fs.existsSync(cwd)) return cwd;
+    }
+  } catch {}
+  return fs.existsSync(session.project) ? session.project : os.homedir();
+}
+
+/**
+ * @typedef {object} LaunchPlan
+ * @property {string}   cwd            Directory to start claude in
+ * @property {string[]} args           Arguments for claude
+ * @property {string}   configDirPath  CLAUDE_CONFIG_DIR for the profile
+ * @property {string}   title          Tab title
+ */
+
+/** @returns {LaunchPlan} */
+function resumePlan(session) {
+  return {
+    cwd:           resolveProjectPath(session),
+    args:          ['-r', session.sessionId],
+    configDirPath: session.configDirPath,
+    title:         session.title || session.sessionId.slice(0, 8),
+  };
+}
+
+/** @returns {LaunchPlan} */
+function newPlan(configDirPath, projectPath) {
+  return { cwd: projectPath, args: [], configDirPath, title: path.basename(projectPath) };
+}
+
+/** A POSIX shell command that runs the plan and then leaves an interactive shell. */
+function planShellCmd(plan) {
+  const claude = ['claude', ...plan.args].join(' ');
+  return `cd ${shellEsc(plan.cwd)} && CLAUDE_CONFIG_DIR=${shellEsc(plan.configDirPath)} ${claude}; exec "\${SHELL:-bash}"`;
+}
+
+/**
+ * `wt new-tab` arguments. wt treats ';' as a command separator, so it is
+ * escaped; cmd's `set X=v&& …` takes everything up to && as the value.
+ */
+function wtArgs(plan) {
+  const escSemi = v => String(v).replace(/;/g, '\\;');
+  const command = `set CLAUDE_CONFIG_DIR=${plan.configDirPath}&& claude ${plan.args.join(' ')}`.trim();
+  return ['-w', '0', 'nt', '--title', escSemi(plan.title), '-d', escSemi(plan.cwd), 'cmd', '/k', escSemi(command)];
+}
+
+/**
+ * Opens the plan in a new tab. Returns { ok, msg }, or { here: true } when the
+ * terminal has no tab support and the caller should use runHere().
+ */
+function launchInTab(plan) {
+  const shellCmd = planShellCmd(plan);
+  const template = process.env.CLAUDE_SESSIONS_OPEN_CMD;
+  if (template) {
+    const command = template
+      .replace(/%cmd%/g,     shellEsc(shellCmd))
+      .replace(/%title%/g,   shellEsc(plan.title))
+      .replace(/%project%/g, shellEsc(plan.cwd));
+    const r = spawnSync('bash', ['-c', command], { stdio: 'ignore' });
+    return r.status === 0 ? { ok: true } : { ok: false, msg: `Custom open command failed (exit ${r.status})` };
+  }
+
+  switch (detectTerminal()) {
+    case 'kitty':
+      return trySpawn('kitty', ['@', 'launch', '--type=tab', `--tab-title=${plan.title}`, 'bash', '-i', '-c', shellCmd]);
+    case 'wezterm':
+      return trySpawn('wezterm', ['cli', 'spawn', '--', 'bash', '-i', '-c', shellCmd]);
+    case 'tmux':
+      return trySpawn('tmux', ['new-window', '-n', plan.title.slice(0, 20), `bash -i -c ${shellEsc(shellCmd)}`]);
+    case 'iterm2':
+      return trySpawn('osascript', ['-e',
+        `tell application "iTerm2" to tell current window to create tab with default profile command ${appleStr('bash -i -c ' + shellEsc(shellCmd))}`]);
+    case 'apple-terminal':
+      return trySpawn('osascript', ['-e', `tell application "Terminal" to do script ${appleStr(shellCmd)}`]);
+    case 'windows-terminal':
+      return trySpawn('wt', wtArgs(plan));
+    default:
+      return { here: true };
+  }
+}
+
+/** Runs claude in the current terminal and waits for it to exit. */
+function runHere(plan) {
+  const r = spawnSync('claude', plan.args, {
+    cwd:   plan.cwd,
+    env:   { ...process.env, CLAUDE_CONFIG_DIR: plan.configDirPath },
+    stdio: 'inherit',
+    shell: IS_WINDOWS, // claude may be a .cmd shim on Windows
+  });
+  if (r.error) return { ok: false, msg: r.error.code === 'ENOENT' ? '`claude` not found on PATH' : r.error.message };
+  return { ok: true };
+}
+
+module.exports = {
+  detectTerminal, resolveProjectPath, resumePlan, newPlan, wtArgs, launchInTab, runHere,
+};

package/lib/operations.js

@@ -0,0 +1,137 @@
+'use strict';
+
+// Changes to session files: move, rename, delete to trash, empty trash.
+
+const fs   = require('fs');
+const path = require('path');
+const { readSession } = require('./sessions');
+const { shortenPath } = require('./format');
+
+const TRASH_DIR = '.claude-sessions-trash';
+
+/** rename(2), falling back to copy + remove across filesystems (EXDEV). */
+function movePath(src, dest) {
+  try { fs.renameSync(src, dest); }
+  catch (e) {
+    if (e.code !== 'EXDEV') throw e;
+    fs.cpSync(src, dest, { recursive: true, errorOnExist: true, force: false });
+    fs.rmSync(src, { recursive: true, force: true });
+  }
+}
+
+/** <id>.jsonl may have a sibling <id>/ folder (subagent transcripts, tool output). */
+function companionDir(jsonlPath) {
+  return jsonlPath.replace(/\.jsonl$/, '');
+}
+
+function moveWithCompanion(jsonlPath, destJsonl) {
+  movePath(jsonlPath, destJsonl);
+  const dir = companionDir(jsonlPath);
+  try { if (fs.statSync(dir).isDirectory()) movePath(dir, companionDir(destJsonl)); } catch {}
+}
+
+/**
+ * Moves a session into <configDir>/.claude-sessions-trash/<folder>/ (same
+ * filesystem, so it is a cheap rename). Returns the trash folder.
+ */
+function deleteSessionFiles(session) {
+  const folderName = path.basename(path.dirname(session.jsonlPath));
+  const trashDir   = path.join(session.configDirPath, TRASH_DIR, folderName);
+  fs.mkdirSync(trashDir, { recursive: true });
+  let base = path.basename(session.jsonlPath, '.jsonl');
+  if (fs.existsSync(path.join(trashDir, base + '.jsonl'))) base += '-' + Date.now();
+  moveWithCompanion(session.jsonlPath, path.join(trashDir, base + '.jsonl'));
+  return trashDir;
+}
+
+function diskUsage(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    if (!stat.isDirectory()) return stat.size;
+    return fs.readdirSync(p).reduce((sum, n) => sum + diskUsage(path.join(p, n)), 0);
+  } catch { return 0; }
+}
+
+/** Permanently removes the trash of each config dir. Returns the bytes freed. */
+function emptyTrash(configDirs) {
+  let freed = 0;
+  for (const dir of configDirs) {
+    const trash = path.join(dir, TRASH_DIR);
+    if (!fs.existsSync(trash)) continue;
+    freed += diskUsage(trash);
+    fs.rmSync(trash, { recursive: true, force: true });
+  }
+  return freed;
+}
+
+/**
+ * Moves a session to another config dir and/or project folder, updating the
+ * session object in place. `targetRawPath` is recorded as the folder's
+ * .project-path hint when the folder is new.
+ */
+function moveSession(session, targetConfigDirPath, targetFolderName, targetRawPath = null) {
+  const folderName  = targetFolderName || path.basename(path.dirname(session.jsonlPath));
+  const targetDir   = path.join(targetConfigDirPath, 'projects', folderName);
+  const targetJsonl = path.join(targetDir, path.basename(session.jsonlPath));
+  if (path.resolve(targetJsonl) === path.resolve(session.jsonlPath)) return;
+  if (fs.existsSync(targetJsonl)) throw new Error('a session with this id already exists there');
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  moveWithCompanion(session.jsonlPath, targetJsonl);
+
+  if (targetRawPath) {
+    try { fs.writeFileSync(path.join(targetDir, '.project-path'), targetRawPath, 'utf8'); } catch {}
+  }
+
+  session.configDir     = path.basename(targetConfigDirPath);
+  session.configDirPath = targetConfigDirPath;
+  session.jsonlPath     = targetJsonl;
+}
+
+/** Appends a custom-title record, the same thing /rename writes. */
+function renameSession(session, title) {
+  title = title.trim();
+  if (!title) throw new Error('empty title');
+  const fd = fs.openSync(session.jsonlPath, 'r+');
+  try {
+    const size = fs.fstatSync(fd).size;
+    let prefix = '';
+    if (size > 0) {
+      const last = Buffer.alloc(1);
+      fs.readSync(fd, last, 0, 1, size - 1);
+      if (last[0] !== 0x0a) prefix = '\n';
+    }
+    const record = JSON.stringify({ type: 'custom-title', customTitle: title, sessionId: session.sessionId });
+    fs.writeSync(fd, prefix + record + '\n', size);
+  } finally { fs.closeSync(fd); }
+  session.title = title;
+}
+
+/** Project folders of a config dir with a readable path for each, sorted by that path. */
+function listProjectFolders(configDirPath) {
+  const projectsDir = path.join(configDirPath, 'projects');
+  const displayPathOf = (folderName) => {
+    const folderDir = path.join(projectsDir, folderName);
+    try {
+      const hint = fs.readFileSync(path.join(folderDir, '.project-path'), 'utf8').trim();
+      if (hint) return shortenPath(hint);
+    } catch {
+      try {
+        const file = fs.readdirSync(folderDir).find(f => f.endsWith('.jsonl'));
+        const cwd  = file && readSession(path.join(folderDir, file)).cwd;
+        if (cwd) return shortenPath(cwd);
+      } catch {}
+    }
+    return folderName;
+  };
+  try {
+    return fs.readdirSync(projectsDir)
+      .filter(d => { try { return fs.statSync(path.join(projectsDir, d)).isDirectory(); } catch { return false; } })
+      .map(d => ({ projectDirName: d, displayPath: displayPathOf(d) }))
+      .sort((a, b) => a.displayPath.localeCompare(b.displayPath));
+  } catch { return []; }
+}
+
+module.exports = {
+  deleteSessionFiles, emptyTrash, moveSession, renameSession, listProjectFolders,
+};