claude-starter 1.3.4 → 1.4.0

package/README.md

@@ -11,8 +11,12 @@
 <h1 align="center">🚀 Claude Starter</h1>
 
 <p align="center">
-  <strong>Claude Code 的主页。</strong>你的所有会话，一目了然。<br/>
-  <strong>Your homepage for Claude Code.</strong> All your sessions, at a glance.
+  <strong>Your homepage for Claude Code.</strong> All your sessions, at a glance.<br/>
+  <strong>Claude Code 的主页。</strong>你的所有会话，一目了然。
+</p>
+
+<p align="center">
+  Built for <strong>AI-native developer workflows</strong>: local-first, searchable, resumable, and fast — so the next session starts faster than the last one ended.
 </p>
 
 <p align="center">
@@ -25,122 +29,14 @@
 
 ---
 
-# 🇨🇳 中文
-
-## 痛点
-
-用过 Claude Code 的 `/resume` 吗？它给你的是这样一坨东西：
-
-```
-? Select a conversation
-  3ee0f33a-b882-424f-9ba4-260342e4dd5b - 4/3/2026, 10:53:41 AM
-  87570bab-ee92-4681-9591-54abf2fcb486 - 4/3/2026, 10:18:55 AM
-  ...200 个 UUID...
-```
-
-一堆 UUID，没有上下文，无法搜索。**想找到上周帮你调过 bug 的那个 session？祝你好运。**
-
-## 解决方案
-
-**Claude Starter** 是一个精美的终端可视化工具，让你能像浏览网页一样浏览所有 Claude 历史会话。它是你的 **Claude 主页** —— 每次打开终端，`claude-starter` 一敲，所有 session 一目了然。
-
-```bash
-claude-starter
-```
-
-精美的分屏 UI，Tokyo Night 配色。左侧列表一目了然，右侧实时预览对话详情。不是 UUID，是你**真正说过的话**。
-
-## 🔍 搜索 — 杀手级功能
-
-按 `/` 开始输入，**就这么简单**。无需按回车。
-
-跨项目名、Git 分支、对话内容**全文实时搜索**。输入即过滤，`↑↓` 直接导航结果。
-
-- `auth` → 所有认证相关的对话
-- `refactor` → 上周的代码重构
-- `web-app fix` → 某个项目的 bug 修复
-
-**不需要管理模式，不需要确认。输入即搜，方向键即走。**
-
-## 核心能力
-
-| | 功能 | 说明 |
-|---|---|---|
-| 🎨 | **精美 TUI** | Tokyo Night 配色，分屏布局，终端里的 App |
-| ✨ | **一键新建** | 列表顶部直接新建对话 |
-| 🔍 | **即时搜索** | `/` 全文搜索，无需回车 |
-| 📂 | **项目过滤** | `p` 按项目筛选 |
-| ⚡ | **秒级恢复** | 选中 → Enter → 回到对话 |
-| 📋 | **对话预览** | 右侧面板展示完整元数据和对话历史 |
-| 🔀 | **多种排序** | 时间 / 大小 / 消息数 / 项目 |
-| 📎 | **复制 ID** | `c` 一键复制到剪贴板 |
-| 🔒 | **权限模式** | `m` 设置权限模式，`d` 一键 danger 模式恢复 |
-| ✏️ | **重命名会话** | `r` 直接重命名，支持中文输入 |
-| 🗑️ | **删除会话** | `x` 删除不需要的会话 |
-| ⌨️ | **Vim 快捷键** | `j`/`k` 上下，`g`/`G` 跳顶/底 |
-| 🧠 | **智能 CLI** | 自动检测 `mai-claude` / `claude` |
-| 🔐 | **完全本地** | 不联网，不上传，不追踪 |
-
-## 安装
-
-```bash
-npm install -g claude-starter
-```
-
-或者从源码安装：
-
-```bash
-git clone https://github.com/Bojun-Vvibe/claude-starter.git
-cd claude-starter
-npm install
-npm link
-```
-
-然后运行 `claude-starter`，就这么简单。
-
-## CLI 参数
-
-```bash
-claude-starter              # 启动交互式 TUI
-claude-starter --list [N]   # 打印最近 N 个会话（默认 30）
-claude-starter --version    # 显示版本号
-claude-starter --update     # 检查并更新到最新版本
-claude-starter --help       # 显示帮助信息
-```
-
-## 快捷键
-
-| 按键 | 功能 |
-|:---:|------|
-| `↑` `↓` / `j` `k` | 上下导航 |
-| `Enter` | 新建 / 恢复对话 |
-| `n` | 直接新建 |
-| `d` | Danger 模式恢复（bypassPermissions） |
-| `m` | 权限模式选择器 |
-| `r` | 重命名会话 |
-| `/` | 搜索 |
-| `Backspace` | 删除搜索字符，删空自动退出 |
-| `Esc` | 清空搜索 |
-| `p` | 按项目过滤 |
-| `s` | 切换排序（时间/大小/消息数/项目） |
-| `c` | 复制 Session ID |
-| `x` / `Delete` | 删除会话 |
-| `g` / `G` | 跳到顶 / 底 |
-| `Ctrl-D` / `Ctrl-U` | 翻页 |
-| `q` / `Ctrl-C` | 退出 |
-
-## 原理
-
-读取 `~/.claude/projects/` 下的 JSONL 会话文件，解析元数据和对话内容。200 个 session 加载耗时 ~10ms。**所有数据留在本地，不联网。**
-
----
-
-# 🇬🇧 English
+# English
 
 ## The Problem
 
 Claude Code's `/resume` gives you a wall of UUIDs:
 
+If you use Claude Code as part of a real development loop, session history stops being archive data and becomes working context. You need to find old agent work by repo, topic, and intent — not by opaque IDs.
+
 ```
 ? Select a conversation
   3ee0f33a-b882-424f-9ba4-260342e4dd5b - 4/3/2026, 10:53:41 AM
@@ -158,6 +54,8 @@ claude-starter
 
 Beautiful split-pane UI with Tokyo Night colors. The left panel shows every session with project, time, and topic. The right panel previews the full conversation. Not UUIDs — your **actual words**.
 
+`claude-starter` is built for developers treating coding agents as part of a daily workflow: keep everything local, cut resume friction, and make past conversations actually reusable.
+
 ## 🔍 Search — The Killer Feature
 
 Press `/` and start typing. **That's it.** No Enter needed.
@@ -250,12 +148,127 @@ Reads the JSONL session files from `~/.claude/projects/`, parses metadata and co
 - **Node.js** >= 18
 - **Claude Code** ([`claude`](https://docs.anthropic.com/en/docs/claude-code) in PATH)
 
+## Related Projects
+
+- **[codex-starter](https://github.com/Bojun-Vvibe/codex-starter)** — the Codex counterpart with the same local-first workflow philosophy
+- **[Bojun-Vvibe](https://github.com/Bojun-Vvibe)** — more terminal UX and AI-native workflow experiments
+
 ## License
 
 MIT
 
 ---
 
+# 中文
+
+## 痛点
+
+用过 Claude Code 的 `/resume` 吗？它给你的是这样一坨东西：
+
+```
+? Select a conversation
+  3ee0f33a-b882-424f-9ba4-260342e4dd5b - 4/3/2026, 10:53:41 AM
+  87570bab-ee92-4681-9591-54abf2fcb486 - 4/3/2026, 10:18:55 AM
+  ...200 个 UUID...
+```
+
+一堆 UUID，没有上下文，无法搜索。**想找到上周帮你调过 bug 的那个 session？祝你好运。**
+
+## 解决方案
+
+**Claude Starter** 是一个精美的终端可视化工具，让你能像浏览网页一样浏览所有 Claude 历史会话。它是你的 **Claude 主页** —— 每次打开终端，`claude-starter` 一敲，所有 session 一目了然。
+
+```bash
+claude-starter
+```
+
+精美的分屏 UI，Tokyo Night 配色。左侧列表一目了然，右侧实时预览对话详情。不是 UUID，是你**真正说过的话**。
+
+## 🔍 搜索 — 杀手级功能
+
+按 `/` 开始输入，**就这么简单**。无需按回车。
+
+跨项目名、Git 分支、对话内容**全文实时搜索**。输入即过滤，`↑↓` 直接导航结果。
+
+- `auth` → 所有认证相关的对话
+- `refactor` → 上周的代码重构
+- `web-app fix` → 某个项目的 bug 修复
+
+**不需要管理模式，不需要确认。输入即搜，方向键即走。**
+
+## 核心能力
+
+| | 功能 | 说明 |
+|---|---|---|
+| 🎨 | **精美 TUI** | Tokyo Night 配色，分屏布局，终端里的 App |
+| ✨ | **一键新建** | 列表顶部直接新建对话 |
+| 🔍 | **即时搜索** | `/` 全文搜索，无需回车 |
+| 📂 | **项目过滤** | `p` 按项目筛选 |
+| ⚡ | **秒级恢复** | 选中 → Enter → 回到对话 |
+| 📋 | **对话预览** | 右侧面板展示完整元数据和对话历史 |
+| 🔀 | **多种排序** | 时间 / 大小 / 消息数 / 项目 |
+| 📎 | **复制 ID** | `c` 一键复制到剪贴板 |
+| 🔒 | **权限模式** | `m` 设置权限模式，`d` 一键 danger 模式恢复 |
+| ✏️ | **重命名会话** | `r` 直接重命名，支持中文输入 |
+| 🗑️ | **删除会话** | `x` 删除不需要的会话 |
+| ⌨️ | **Vim 快捷键** | `j`/`k` 上下，`g`/`G` 跳顶/底 |
+| 🧠 | **智能 CLI** | 自动检测 `mai-claude` / `claude` |
+| 🔐 | **完全本地** | 不联网，不上传，不追踪 |
+
+## 安装
+
+```bash
+npm install -g claude-starter
+```
+
+或者从源码安装：
+
+```bash
+git clone https://github.com/Bojun-Vvibe/claude-starter.git
+cd claude-starter
+npm install
+npm link
+```
+
+然后运行 `claude-starter`，就这么简单。
+
+## CLI 参数
+
+```bash
+claude-starter              # 启动交互式 TUI
+claude-starter --list [N]   # 打印最近 N 个会话（默认 30）
+claude-starter --version    # 显示版本号
+claude-starter --update     # 检查并更新到最新版本
+claude-starter --help       # 显示帮助信息
+```
+
+## 快捷键
+
+| 按键 | 功能 |
+|:---:|------|
+| `↑` `↓` / `j` `k` | 上下导航 |
+| `Enter` | 新建 / 恢复对话 |
+| `n` | 直接新建 |
+| `d` | Danger 模式恢复（bypassPermissions） |
+| `m` | 权限模式选择器 |
+| `r` | 重命名会话 |
+| `/` | 搜索 |
+| `Backspace` | 删除搜索字符，删空自动退出 |
+| `Esc` | 清空搜索 |
+| `p` | 按项目过滤 |
+| `s` | 切换排序（时间/大小/消息数/项目） |
+| `c` | 复制 Session ID |
+| `x` / `Delete` | 删除会话 |
+| `g` / `G` | 跳到顶 / 底 |
+| `Ctrl-D` / `Ctrl-U` | 翻页 |
+| `q` / `Ctrl-C` | 退出 |
+
+## 原理
+
+读取 `~/.claude/projects/` 下的 JSONL 会话文件，解析元数据和对话内容。200 个 session 加载耗时 ~10ms。**所有数据留在本地，不联网。**
+
+---
+
 <p align="center">
   <sub>Built with 💜 by <a href="https://github.com/Bojun-Vvibe">Bojun</a> — powered by Claude Code itself</sub>
 </p>

package/index.js

@@ -9,6 +9,7 @@
  *   claude-starter            # Launch interactive TUI
  *   claude-starter --list     # Print sessions as a table (no TUI)
  *   claude-starter --list N   # Print the latest N sessions
+ *   claude-starter --exclude "pat"  # Exclude sessions matching regex (repeatable)
  *   claude-starter --version  # Show version
  *   claude-starter --update   # Update to the latest version
  *
@@ -35,6 +36,10 @@ const path = require('path');
 const { spawn, execSync } = require('child_process');
 const os = require('os');
 
+let excludePatterns = [];
+
+function setExcludePatterns(patterns) { excludePatterns = patterns; }
+
 // ─── CLI Detection ──────────────────────────────────────────────────────────
 // Detect whether `mai-claude` is available (binary, alias, or function).
 // First checks PATH directly, then sources shell config non-interactively
@@ -417,6 +422,7 @@ function loadAllSessions() {
         if (session.firstTs
             && session.topic !== '(no user messages)'
             && !/^warmup$/i.test(session.topic.trim())
+            && !excludePatterns.some(re => re.test(session.topic))
         ) sessions.push(session);
       } catch (e) { /* skip */ }
     }
@@ -1508,67 +1514,127 @@ function createApp() {
   listPanel.focus();
 }
 
+// ─── Exports for Testing ────────────────────────────────────────────────────
+// When required as a module (e.g. by tests), export helpers without launching
+// the CLI / TUI.  The entry-point logic only runs when executed directly.
+
+if (typeof module !== 'undefined') {
+  module.exports = {
+    // Data helpers
+    getProjectDisplayName,
+    extractUserText,
+    loadSessionQuick,
+    loadSessionDetail,
+    loadAllSessions,
+    // Formatting
+    formatTimestamp,
+    formatFileSize,
+    getProjectColor,
+    esc,
+    // Meta
+    loadMeta,
+    saveMeta,
+    getSessionMeta,
+    getEffectivePermissionMode,
+    setSessionPermissionMode,
+    setGlobalPermissionMode,
+    setExcludePatterns,
+    // Constants
+    PERMISSION_MODES,
+    PROJECT_COLORS,
+    CLAUDE_DIR,
+    PROJECTS_DIR,
+    META_FILE,
+    // CLI
+    detectCLI,
+    // List mode (for integration tests)
+    runListMode,
+    // TUI (for interaction tests)
+    createApp,
+  };
+}
+
 // ─── Entry Point ─────────────────────────────────────────────────────────────
+// Only run CLI/TUI when executed directly (not when required as a module).
 
-const PKG = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
+if (require.main === module) {
+  const PKG = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
 
-const args = process.argv.slice(2);
+  const args = process.argv.slice(2);
 
-if (args.includes('--version') || args.includes('-v') || args.includes('-V')) {
-  console.log(`claude-starter v${PKG.version}`);
-  process.exit(0);
-}
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--exclude' && args[i + 1]) {
+      try { excludePatterns.push(new RegExp(args[i + 1], 'i')); } catch {}
+      i++;
+    }
+  }
+  if (process.env.CLAUDE_STARTER_EXCLUDE) {
+    for (const p of process.env.CLAUDE_STARTER_EXCLUDE.split(',')) {
+      if (p.trim()) {
+        try { excludePatterns.push(new RegExp(p.trim(), 'i')); } catch {}
+      }
+    }
+  }
 
-if (args.includes('--update') || args.includes('-u')) {
-  const C = {
-    reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
-    cyan: '\x1b[36m', yellow: '\x1b[33m', green: '\x1b[32m',
-    red: '\x1b[31m',
-  };
-  console.log(`\n${C.cyan}🔄 Checking for updates…${C.reset}\n`);
+  if (args.includes('--version') || args.includes('-v') || args.includes('-V')) {
+    console.log(`claude-starter v${PKG.version}`);
+    process.exit(0);
+  }
 
-  try {
-    const latest = execSync('npm view claude-starter version 2>/dev/null', {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 10000,
-    }).toString().trim();
+  if (args.includes('--update') || args.includes('-u')) {
+    const C = {
+      reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
+      cyan: '\x1b[36m', yellow: '\x1b[33m', green: '\x1b[32m',
+      red: '\x1b[31m',
+    };
+    console.log(`\n${C.cyan}🔄 Checking for updates…${C.reset}\n`);
 
-    if (latest === PKG.version) {
-      console.log(`${C.green}✓ Already on the latest version (v${PKG.version})${C.reset}\n`);
-      process.exit(0);
-    }
+    try {
+      const latest = execSync('npm view claude-starter version 2>/dev/null', {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+      }).toString().trim();
+
+      if (latest === PKG.version) {
+        console.log(`${C.green}✓ Already on the latest version (v${PKG.version})${C.reset}\n`);
+        process.exit(0);
+      }
 
-    console.log(`${C.yellow}  Current: v${PKG.version}${C.reset}`);
-    console.log(`${C.green}  Latest:  v${latest}${C.reset}\n`);
-    console.log(`${C.cyan}📦 Updating…${C.reset}\n`);
+      console.log(`${C.yellow}  Current: v${PKG.version}${C.reset}`);
+      console.log(`${C.green}  Latest:  v${latest}${C.reset}\n`);
+      console.log(`${C.cyan}📦 Updating…${C.reset}\n`);
 
-    try {
-      execSync('npm install -g claude-starter@latest', { stdio: 'inherit', timeout: 60000 });
-      console.log(`\n${C.green}${C.bold}✓ Updated to v${latest}${C.reset}\n`);
+      try {
+        execSync('npm install -g claude-starter@latest', { stdio: 'inherit', timeout: 60000 });
+        console.log(`\n${C.green}${C.bold}✓ Updated to v${latest}${C.reset}\n`);
+      } catch (e) {
+        console.error(`\n${C.red}✗ Update failed. Try manually:${C.reset}`);
+        console.log(`${C.yellow}  npm install -g claude-starter@latest${C.reset}\n`);
+        process.exit(1);
+      }
     } catch (e) {
-      console.error(`\n${C.red}✗ Update failed. Try manually:${C.reset}`);
-      console.log(`${C.yellow}  npm install -g claude-starter@latest${C.reset}\n`);
+      console.error(`${C.red}✗ Could not check for updates (network error or npm not found)${C.reset}\n`);
       process.exit(1);
     }
-  } catch (e) {
-    console.error(`${C.red}✗ Could not check for updates (network error or npm not found)${C.reset}\n`);
-    process.exit(1);
-  }
 
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-if (args.includes('--help') || args.includes('-h')) {
-  console.log(`
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
 \x1b[36m🚀 Claude Starter\x1b[0m  \x1b[2mv${PKG.version}\x1b[0m
 
 Usage:
   claude-starter              Launch interactive TUI
   claude-starter --list [N]   Print latest N sessions (default: 30)
+  claude-starter --exclude "pat"  Exclude sessions matching regex (repeatable)
   claude-starter --version    Show version
   claude-starter --update     Update to the latest version
   claude-starter --help       Show this help
 
+Environment Variables:
+  CLAUDE_STARTER_EXCLUDE=pat1,pat2   Comma-separated regex patterns to exclude
+
 TUI Keyboard Shortcuts:
   ↑/↓           Navigate sessions
   Enter         Start new / resume selected session
@@ -1585,14 +1651,15 @@ TUI Keyboard Shortcuts:
   Esc           Clear filter
   q / Ctrl-C    Quit
 `);
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-if (args.includes('--list') || args.includes('-l')) {
-  const limitIdx = args.indexOf('--list') !== -1 ? args.indexOf('--list') : args.indexOf('-l');
-  const limit = parseInt(args[limitIdx + 1]) || 30;
-  runListMode(limit);
-  process.exit(0);
-}
+  if (args.includes('--list') || args.includes('-l')) {
+    const limitIdx = args.indexOf('--list') !== -1 ? args.indexOf('--list') : args.indexOf('-l');
+    const limit = parseInt(args[limitIdx + 1]) || 30;
+    runListMode(limit);
+    process.exit(0);
+  }
 
-createApp();
+  createApp();
+}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "claude-starter",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "A beautiful terminal UI for managing Claude Code sessions — start new or resume past conversations",
   "main": "index.js",
   "bin": {
     "claude-starter": "./index.js"
   },
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "test": "node --test test.js",
+    "test:tui": "node --test --test-force-exit test-tui.js",
+    "test:all": "node --test --test-force-exit test.js test-tui.js",
+    "prepublishOnly": "npm run test:all"
   },
   "keywords": [
     "claude",
@@ -16,7 +20,11 @@
     "terminal",
     "session",
     "resume",
-    "ai"
+    "ai",
+    "ai-native",
+    "developer-workflow",
+    "local-first",
+    "agentic-tooling"
   ],
   "author": "Bojun Chai <just_cbj@sina.com>",
   "license": "MIT",
@@ -24,6 +32,10 @@
     "type": "git",
     "url": "https://github.com/Bojun-Vvibe/claude-starter.git"
   },
+  "homepage": "https://github.com/Bojun-Vvibe/claude-starter#readme",
+  "bugs": {
+    "url": "https://github.com/Bojun-Vvibe/claude-starter/issues"
+  },
   "engines": {
     "node": ">=18"
   },