quickclaude 1.0.8 → 1.1.1

package/.github/workflows/publish.yml

@@ -2,8 +2,8 @@ name: Publish to npm
 
 on:
   push:
-    tags:
-      - "v*"
+    branches:
+      - main
 
 jobs:
   publish:
@@ -12,11 +12,12 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: 22
-      - run: npm install -g npm@latest
-      - run: npm --version
+          registry-url: https://registry.npmjs.org
       - run: npm ci
       - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,27 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+quickclaude is a CLI launcher for Claude Code. It scans `~/.claude/projects/` for project directories, presents an interactive selection menu, and spawns `claude` in the chosen directory.
+
+## Commands
+
+- **Run**: `node bin/quickclaude.js` or `npm start`
+- **Install globally (for testing)**: `npm install -g .`
+- **No build step or test suite** — this is a single-file Node.js CLI tool
+
+## Architecture
+
+The entire tool lives in `bin/quickclaude.js` (ESM, `#!/usr/bin/env node`):
+
+- **`resolvePath(encoded)`** — Converts Claude's encoded project directory names (e.g., `-Users-dongwoo-projects-my-app`) back to real filesystem paths. Uses greedy longest-match against the filesystem, trying both `-` and space as segment joiners. Handles Windows drive letters (`C--Users-...`).
+- **`getProjects()`** — Reads `~/.claude/projects/`, resolves each subdirectory name via `resolvePath`, filters out worktree dirs and non-existent paths.
+- **`main()`** — Uses `@clack/prompts` for the interactive select UI, then spawns `claude` with `stdio: "inherit"` in the selected directory.
+
+## Key Details
+
+- Single dependency: `@clack/prompts` for terminal UI
+- Published to npm as `quickclaude` (global install / npx)
+- Requires Node.js 18+ and Claude Code installed

package/README.md

@@ -1,9 +1,7 @@
 # quickclaude
 
-CLI launcher for Claude Code.
+CLI launcher for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 Quickly launch Claude Code in your project directories.
-<img width="762" height="383" alt="Screenshot 2026-03-28 at 6 25 10 PM" src="https://github.com/user-attachments/assets/4f368300-9748-4190-87c1-f2a1fcfd8a63" />
-
 
 ```
 $ quickclaude
@@ -11,12 +9,37 @@ $ quickclaude
 ┌  quickclaude
 │
 ◆  Select a project
-│  ● ~/Documents/projects/my-app1
-│  ○ ~/Documents/projects/my-app2
-│  ○ ~/Documents/projects/my-app3
+│  ● 2h ago · ~/Documents/projects/my-app1
+│  ○ 3d ago · ~/Documents/projects/my-app2
+│  ○ 1w ago · ~/Documents/projects/my-app3
 └
 ```
 
+## How it works
+
+Claude Code stores [auto memory](https://docs.anthropic.com/en/docs/claude-code/memory) for each project under `~/.claude/projects/`. Every time you run Claude Code in a directory, it creates a subdirectory there to save project-specific memory like build commands, debugging patterns, and architecture notes.
+
+quickclaude uses this directory structure in reverse — it scans `~/.claude/projects/` to build a list of projects you've used with Claude Code, then lets you pick one and launch `claude` right there.
+
+1. Scans `~/.claude/projects/` to discover your Claude Code projects
+2. Sorts by most recently used, with relative timestamps (e.g. `2h ago`)
+3. Shows an interactive selection menu with fuzzy search
+4. Launches `claude` in the selected directory
+
+Any CLI arguments are forwarded to `claude`:
+
+```bash
+quickclaude --resume
+# equivalent to: cd <selected-project> && claude --resume
+```
+
+## Features
+
+- **Fuzzy search** — Type to filter projects instantly (start typing to search)
+- **Smart sorting** — Projects sorted by most recently used, with relative timestamps
+- **Path resolution** — Accurately resolves encoded project directory names back to real paths
+- **Argument forwarding** — Any CLI arguments are passed through to `claude`
+
 ## Install
 
 ```bash
@@ -29,11 +52,11 @@ Or run without installing:
 npx quickclaude
 ```
 
-## How it works
+## Update
 
-1. Scans `~/.claude/projects/` for Claude Code project directories
-2. Shows an interactive list to pick from
-3. Launches `claude` in the selected directory
+```bash
+npm update -g quickclaude
+```
 
 ## Requirements
 

package/bin/quickclaude.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
-import * as p from "@clack/prompts";
-import { readdirSync, existsSync } from "fs";
+import prompts from "prompts";
+import { readdirSync, existsSync, statSync, realpathSync } from "fs";
 import { join, sep } from "path";
 import { homedir } from "os";
-import { execSync, spawn } from "child_process";
+import { execFileSync, spawn } from "child_process";
+import { fileURLToPath } from "url";
 
 const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
 
@@ -12,31 +13,36 @@ const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
 // "-Users-seunghyunhong-Documents-projects-mcp-overwatch" 같은 경우
 // -를 /로 바꾸면 mcp/overwatch가 되어 틀려짐
 // → 파일시스템을 실제로 탐색하며 매칭
-function resolvePath(encoded) {
+function resolvePath(encoded, root = sep) {
   const parts = encoded.replace(/^-/, "").split("-");
-  let current = sep;
+  if (parts.length === 0 || (parts.length === 1 && parts[0] === "")) return null;
+  let current = root;
   let i = 0;
 
   // Windows: "C--Users-..." → drive letter "C:" 처리
-  if (parts.length >= 1 && /^[A-Za-z]$/.test(parts[0])) {
+  if (root === sep && parts.length >= 1 && /^[A-Za-z]$/.test(parts[0])) {
     const drive = parts[0].toUpperCase() + ":\\";
     if (existsSync(drive)) {
       current = drive;
       i = 1;
     }
   }
+
   while (i < parts.length) {
+    let entries;
+    try {
+      entries = new Set(readdirSync(current));
+    } catch {
+      return null;
+    }
+
     let matched = false;
-    // 긴 조합부터 시도 (mcp-overwatch, Unreal Projects 등)
     for (let len = parts.length - i; len >= 1; len--) {
       const segment = parts.slice(i, i + len);
-      // "-"와 " " 두 가지 구분자 조합을 모두 시도
-      const separators = ["-", " "];
-      for (const joiner of separators) {
+      for (const joiner of ["-", " "]) {
         const candidate = segment.join(joiner);
-        const fullPath = join(current, candidate);
-        if (existsSync(fullPath)) {
-          current = fullPath;
+        if (entries.has(candidate)) {
+          current = join(current, candidate);
           i += len;
           matched = true;
           break;
@@ -50,6 +56,25 @@ function resolvePath(encoded) {
   return current;
 }
 
+function getLatestMtime(dirPath) {
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    let latest = 0;
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const mtime = statSync(join(dirPath, entry.name)).mtimeMs;
+      if (mtime > latest) latest = mtime;
+    }
+    return latest || statSync(dirPath).mtimeMs;
+  } catch {
+    try {
+      return statSync(dirPath).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+}
+
 function getProjects() {
   if (!existsSync(CLAUDE_PROJECTS_DIR)) {
     return [];
@@ -68,50 +93,114 @@ function getProjects() {
       if (p.path.includes(`claude${sep}worktrees`)) return false;
       return existsSync(p.path);
     })
-    .sort((a, b) => a.path.localeCompare(b.path));
+    .map((p) => {
+      const projectDir = join(CLAUDE_PROJECTS_DIR, p.dirName);
+      const mtime = getLatestMtime(projectDir);
+      return { ...p, mtime };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+}
+
+function timeAgo(mtimeMs) {
+  const seconds = Math.floor((Date.now() - mtimeMs) / 1000);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 4) return `${weeks}w ago`;
+  const months = Math.floor(days / 30);
+  return `${months}mo ago`;
 }
 
-function getProjectLabel(path) {
+function getProjectLabel(path, mtimeMs) {
   const home = homedir();
   const display = path.startsWith(home) ? "~" + path.slice(home.length) : path;
-  return display;
+  return `${timeAgo(mtimeMs)} · ${display}`;
 }
 
 async function main() {
-  p.intro("quickclaude");
+  console.log("\n  quickclaude\n");
 
   const projects = getProjects();
 
   if (projects.length === 0) {
-    p.cancel("No Claude projects found.");
+    console.error("  No Claude projects found.\n");
     process.exit(1);
   }
 
-  const selected = await p.select({
-    message: "Select a project",
-    options: projects.map((proj) => ({
-      value: proj.path,
-      label: getProjectLabel(proj.path),
-    })),
+  const choices = projects.map((proj) => ({
+    title: getProjectLabel(proj.path, proj.mtime),
+    value: proj.path,
+  }));
+
+  const response = await prompts({
+    type: "autocomplete",
+    name: "project",
+    message: "Select a project (type to search)",
+    choices,
+    suggest: (input, choices) => {
+      if (!input) return Promise.resolve(choices);
+      const lower = input.toLowerCase();
+      return Promise.resolve(
+        choices.filter((c) => {
+          const title = c.title.toLowerCase();
+          let j = 0;
+          for (let i = 0; i < title.length && j < lower.length; i++) {
+            if (title[i] === lower[j]) j++;
+          }
+          return j === lower.length;
+        })
+      );
+    },
   });
 
-  if (p.isCancel(selected)) {
-    p.cancel("Cancelled");
+  if (!response.project) {
+    console.log("  Cancelled\n");
     process.exit(0);
   }
 
-  p.outro(`Launching Claude in ${selected}`);
+  const args = process.argv.slice(2);
 
-  // claude 실행 (현재 터미널에서 interactive하게)
-  const child = spawn("claude", [], {
-    cwd: selected,
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  try {
+    execFileSync(whichCmd, ["claude"], { stdio: "ignore" });
+  } catch {
+    console.error(
+      "Error: Claude Code is not installed.\n" +
+      "Install it with: npm install -g @anthropic-ai/claude-code"
+    );
+    process.exit(1);
+  }
+
+  console.log(`  Launching Claude in ${response.project}\n`);
+
+  const child = spawn("claude", args, {
+    cwd: response.project,
     stdio: "inherit",
-    shell: true,
   });
 
   child.on("exit", (code) => {
     process.exit(code ?? 0);
   });
+
+  child.on("error", (err) => {
+    console.error(`Failed to launch Claude: ${err.message}`);
+    process.exit(1);
+  });
 }
 
-main();
+export { resolvePath, timeAgo, getProjectLabel, getProjects, getLatestMtime };
+
+try {
+  if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main();
+  }
+} catch {
+  if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main();
+  }
+}

package/docs/superpowers/plans/2026-04-04-quickclaude-improvements.md

@@ -0,0 +1,641 @@
+# quickclaude Improvements Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Improve quickclaude across 7 areas: performance, reliability, testing, UX, and CI.
+
+**Architecture:** Single-file CLI stays in `bin/quickclaude.js` with named exports for testability. Functions are guarded by `import.meta.url` check so the file works as both a CLI entry point and an importable module. Tests use `node:test` with temp directories.
+
+**Tech Stack:** Node.js 18+, `node:test`, `prompts` (replaces `@clack/prompts`), GitHub Actions
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|------|--------|----------------|
+| `bin/quickclaude.js` | Modify | CLI entry point + all functions (add exports, optimize resolvePath, mtime, error handling, prompts migration, remove shell:true) |
+| `test/resolvePath.test.js` | Create | Unit tests for resolvePath with temp directory fixtures |
+| `test/timeAgo.test.js` | Create | Unit tests for timeAgo boundary values |
+| `test/getProjects.test.js` | Create | Integration tests for getProjects with temp directory fixtures |
+| `package.json` | Modify | Replace `@clack/prompts` with `prompts`, add `test` script |
+| `.github/workflows/publish.yml` | Modify | Tag-based trigger |
+
+---
+
+### Task 1: Module restructure + test infrastructure
+
+**Files:**
+- Modify: `bin/quickclaude.js:1-139`
+- Modify: `package.json`
+
+- [ ] **Step 1: Add exports and main guard to quickclaude.js**
+
+Add `fileURLToPath` import at line 5, add named exports, and guard `main()`:
+
+```js
+// Add to imports at top:
+import { fileURLToPath } from "url";
+
+// Replace the bare `main();` at line 139 with:
+export { resolvePath, timeAgo, getProjectLabel, getProjects };
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}
+```
+
+- [ ] **Step 2: Add test script to package.json**
+
+Add to the `"scripts"` section:
+
+```json
+"scripts": {
+  "start": "node bin/quickclaude.js",
+  "test": "node --test test/"
+}
+```
+
+- [ ] **Step 3: Create a smoke test to verify the setup**
+
+Create `test/timeAgo.test.js` with one basic test:
+
+```js
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { timeAgo } from "../bin/quickclaude.js";
+
+describe("timeAgo", () => {
+  it("returns 'just now' for current time", () => {
+    assert.equal(timeAgo(Date.now()), "just now");
+  });
+});
+```
+
+- [ ] **Step 4: Run the test**
+
+Run: `npm test`
+Expected: 1 test passes
+
+- [ ] **Step 5: Verify CLI still works**
+
+Run: `node bin/quickclaude.js --help` (or just run and Ctrl+C)
+Expected: Interactive menu appears normally
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add bin/quickclaude.js package.json test/timeAgo.test.js
+git commit -m "refactor: add exports and test infrastructure"
+```
+
+---
+
+### Task 2: timeAgo tests
+
+**Files:**
+- Modify: `test/timeAgo.test.js`
+
+- [ ] **Step 1: Write comprehensive timeAgo tests**
+
+Replace `test/timeAgo.test.js` with:
+
+```js
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { timeAgo } from "../bin/quickclaude.js";
+
+describe("timeAgo", () => {
+  function msAgo(ms) {
+    return Date.now() - ms;
+  }
+
+  it("returns 'just now' for <60 seconds ago", () => {
+    assert.equal(timeAgo(msAgo(0)), "just now");
+    assert.equal(timeAgo(msAgo(30_000)), "just now");
+    assert.equal(timeAgo(msAgo(59_000)), "just now");
+  });
+
+  it("returns minutes for 1-59 minutes ago", () => {
+    assert.equal(timeAgo(msAgo(60_000)), "1m ago");
+    assert.equal(timeAgo(msAgo(30 * 60_000)), "30m ago");
+    assert.equal(timeAgo(msAgo(59 * 60_000)), "59m ago");
+  });
+
+  it("returns hours for 1-23 hours ago", () => {
+    assert.equal(timeAgo(msAgo(60 * 60_000)), "1h ago");
+    assert.equal(timeAgo(msAgo(12 * 60 * 60_000)), "12h ago");
+    assert.equal(timeAgo(msAgo(23 * 60 * 60_000)), "23h ago");
+  });
+
+  it("returns days for 1-6 days ago", () => {
+    assert.equal(timeAgo(msAgo(24 * 60 * 60_000)), "1d ago");
+    assert.equal(timeAgo(msAgo(6 * 24 * 60 * 60_000)), "6d ago");
+  });
+
+  it("returns weeks for 7-27 days ago", () => {
+    assert.equal(timeAgo(msAgo(7 * 24 * 60 * 60_000)), "1w ago");
+    assert.equal(timeAgo(msAgo(21 * 24 * 60 * 60_000)), "3w ago");
+  });
+
+  it("returns months for 28+ days ago", () => {
+    assert.equal(timeAgo(msAgo(30 * 24 * 60 * 60_000)), "1mo ago");
+    assert.equal(timeAgo(msAgo(90 * 24 * 60 * 60_000)), "3mo ago");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `npm test`
+Expected: All tests pass
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/timeAgo.test.js
+git commit -m "test: add comprehensive timeAgo unit tests"
+```
+
+---
+
+### Task 3: resolvePath performance optimization + tests
+
+**Files:**
+- Modify: `bin/quickclaude.js:15-51` (resolvePath function)
+- Create: `test/resolvePath.test.js`
+
+- [ ] **Step 1: Write resolvePath tests**
+
+Create `test/resolvePath.test.js`:
+
+```js
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { resolvePath } from "../bin/quickclaude.js";
+
+describe("resolvePath", () => {
+  let root;
+
+  before(() => {
+    root = mkdtempSync(join(tmpdir(), "qc-test-"));
+    // Create directory structure:
+    // root/Users/test/projects/my-app/
+    // root/Users/test/projects/mcp-overwatch/
+    // root/Users/test/My Documents/
+    mkdirSync(join(root, "Users", "test", "projects", "my-app"), { recursive: true });
+    mkdirSync(join(root, "Users", "test", "projects", "mcp-overwatch"), { recursive: true });
+    mkdirSync(join(root, "Users", "test", "My Documents"), { recursive: true });
+  });
+
+  after(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("resolves a simple path", () => {
+    const encoded = "-Users-test-projects-my-app";
+    assert.equal(resolvePath(encoded, root), join(root, "Users", "test", "projects", "my-app"));
+  });
+
+  it("resolves hyphenated directory names", () => {
+    const encoded = "-Users-test-projects-mcp-overwatch";
+    assert.equal(resolvePath(encoded, root), join(root, "Users", "test", "projects", "mcp-overwatch"));
+  });
+
+  it("resolves space-separated directory names", () => {
+    const encoded = "-Users-test-My-Documents";
+    assert.equal(resolvePath(encoded, root), join(root, "Users", "test", "My Documents"));
+  });
+
+  it("returns null for non-existent paths", () => {
+    const encoded = "-Users-test-nonexistent";
+    assert.equal(resolvePath(encoded, root), null);
+  });
+
+  it("returns null for empty input", () => {
+    assert.equal(resolvePath("", root), null);
+  });
+});
+```
+
+- [ ] **Step 2: Add `root` parameter to resolvePath**
+
+In `bin/quickclaude.js`, change the function signature:
+
+```js
+function resolvePath(encoded, root = sep) {
+  const parts = encoded.replace(/^-/, "").split("-");
+  if (parts.length === 0 || (parts.length === 1 && parts[0] === "")) return null;
+  let current = root;
+  let i = 0;
+```
+
+Also change the Windows drive check to only apply when using default root:
+
+```js
+  // Windows: "C--Users-..." → drive letter "C:" 처리
+  if (root === sep && parts.length >= 1 && /^[A-Za-z]$/.test(parts[0])) {
+    const drive = parts[0].toUpperCase() + ":\\";
+    if (existsSync(drive)) {
+      current = drive;
+      i = 1;
+    }
+  }
+```
+
+- [ ] **Step 3: Run tests to verify they pass**
+
+Run: `npm test`
+Expected: resolvePath tests pass (the logic is already correct, we just made it testable)
+
+- [ ] **Step 4: Optimize resolvePath with readdirSync**
+
+Replace the inner while loop in `resolvePath`. Instead of calling `existsSync` for each candidate, read the directory once and check against a Set:
+
+```js
+  while (i < parts.length) {
+    let entries;
+    try {
+      entries = new Set(readdirSync(current));
+    } catch {
+      return null;
+    }
+
+    let matched = false;
+    for (let len = parts.length - i; len >= 1; len--) {
+      const segment = parts.slice(i, i + len);
+      for (const joiner of ["-", " "]) {
+        const candidate = segment.join(joiner);
+        if (entries.has(candidate)) {
+          current = join(current, candidate);
+          i += len;
+          matched = true;
+          break;
+        }
+      }
+      if (matched) break;
+    }
+    if (!matched) return null;
+  }
+```
+
+Note: also add `readdirSync` to the import if not already present (it is — line 4 already imports it).
+
+- [ ] **Step 5: Run tests again**
+
+Run: `npm test`
+Expected: All tests still pass
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add bin/quickclaude.js test/resolvePath.test.js
+git commit -m "perf: optimize resolvePath with readdirSync + add tests"
+```
+
+---
+
+### Task 4: mtime accuracy improvement
+
+**Files:**
+- Modify: `bin/quickclaude.js:53-77` (getProjects function)
+
+- [ ] **Step 1: Write test for getLatestMtime**
+
+Add to `test/getProjects.test.js`:
+
+```js
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { getLatestMtime } from "../bin/quickclaude.js";
+
+describe("getLatestMtime", () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), "qc-mtime-"));
+    // Create files with different mtimes
+    writeFileSync(join(dir, "old.md"), "old");
+    writeFileSync(join(dir, "new.md"), "new");
+    // Set old.md to 1 hour ago
+    const oneHourAgo = new Date(Date.now() - 3600_000);
+    utimesSync(join(dir, "old.md"), oneHourAgo, oneHourAgo);
+  });
+
+  after(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns the most recent file mtime in a directory", () => {
+    const latest = getLatestMtime(dir);
+    // new.md was just created, so latest should be very recent
+    assert.ok(Date.now() - latest < 5000);
+  });
+
+  it("ignores subdirectories, only checks direct files", () => {
+    mkdirSync(join(dir, "subdir"));
+    const latest = getLatestMtime(dir);
+    assert.ok(latest > 0);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test`
+Expected: FAIL — `getLatestMtime` is not exported / doesn't exist
+
+- [ ] **Step 3: Implement getLatestMtime and update getProjects**
+
+Add the new function in `bin/quickclaude.js` (before `getProjects`):
+
+```js
+function getLatestMtime(dirPath) {
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    let latest = 0;
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const mtime = statSync(join(dirPath, entry.name)).mtimeMs;
+      if (mtime > latest) latest = mtime;
+    }
+    return latest || statSync(dirPath).mtimeMs;
+  } catch {
+    return statSync(dirPath).mtimeMs;
+  }
+}
+```
+
+Update `getProjects` to use it. Replace the mtime line:
+
+```js
+    .map((p) => {
+      const projectDir = join(CLAUDE_PROJECTS_DIR, p.dirName);
+      const mtime = getLatestMtime(projectDir);
+      return { ...p, mtime };
+    })
+```
+
+Add `getLatestMtime` to the export statement:
+
+```js
+export { resolvePath, timeAgo, getProjectLabel, getProjects, getLatestMtime };
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `npm test`
+Expected: All tests pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add bin/quickclaude.js test/getProjects.test.js
+git commit -m "fix: use file mtime for accurate project recency"
+```
+
+---
+
+### Task 5: Error handling
+
+**Files:**
+- Modify: `bin/quickclaude.js:100-137` (main function)
+
+- [ ] **Step 1: Add claude existence check before spawn**
+
+In the `main()` function, after the `p.outro(...)` line (or its replacement) and before the `spawn(...)` call, add:
+
+```js
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  try {
+    execFileSync(whichCmd, ["claude"], { stdio: "ignore" });
+  } catch {
+    console.error(
+      "Error: Claude Code is not installed.\n" +
+      "Install it with: npm install -g @anthropic-ai/claude-code"
+    );
+    process.exit(1);
+  }
+```
+
+Add `execFileSync` to the imports (replace `execSync` since it's unused):
+
+```js
+import { execFileSync, spawn } from "child_process";
+```
+
+- [ ] **Step 2: Add spawn error handler**
+
+After the existing `child.on("exit", ...)`, add:
+
+```js
+  child.on("error", (err) => {
+    console.error(`Failed to launch Claude: ${err.message}`);
+    process.exit(1);
+  });
+```
+
+- [ ] **Step 3: Test manually**
+
+Run: `node bin/quickclaude.js` — should work normally.
+Temporarily rename `claude` or test with a non-existent command to verify the error message.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add bin/quickclaude.js
+git commit -m "feat: add error handling for missing claude installation"
+```
+
+---
+
+### Task 6: Replace @clack/prompts with prompts
+
+**Files:**
+- Modify: `bin/quickclaude.js:1-3, 100-125` (imports and main function)
+- Modify: `package.json`
+
+- [ ] **Step 1: Swap dependencies**
+
+```bash
+npm uninstall @clack/prompts
+npm install prompts
+```
+
+- [ ] **Step 2: Update imports in quickclaude.js**
+
+Replace line 3:
+
+```js
+// Remove: import * as p from "@clack/prompts";
+// Add:
+import prompts from "prompts";
+```
+
+- [ ] **Step 3: Rewrite the main function UI**
+
+Replace the entire `main()` function body with:
+
+```js
+async function main() {
+  console.log("\n  quickclaude\n");
+
+  const projects = getProjects();
+
+  if (projects.length === 0) {
+    console.error("  No Claude projects found.\n");
+    process.exit(1);
+  }
+
+  const choices = projects.map((proj) => ({
+    title: getProjectLabel(proj.path, proj.mtime),
+    value: proj.path,
+  }));
+
+  const response = await prompts({
+    type: "autocomplete",
+    name: "project",
+    message: "Select a project",
+    choices,
+    suggest: (input, choices) =>
+      Promise.resolve(
+        choices.filter((c) =>
+          c.title.toLowerCase().includes(input.toLowerCase())
+        )
+      ),
+  });
+
+  if (!response.project) {
+    console.log("  Cancelled\n");
+    process.exit(0);
+  }
+
+  const args = process.argv.slice(2);
+
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  try {
+    execFileSync(whichCmd, ["claude"], { stdio: "ignore" });
+  } catch {
+    console.error(
+      "Error: Claude Code is not installed.\n" +
+      "Install it with: npm install -g @anthropic-ai/claude-code"
+    );
+    process.exit(1);
+  }
+
+  console.log(`  Launching Claude in ${response.project}\n`);
+
+  const child = spawn("claude", args, {
+    cwd: response.project,
+    stdio: "inherit",
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+
+  child.on("error", (err) => {
+    console.error(`Failed to launch Claude: ${err.message}`);
+    process.exit(1);
+  });
+}
+```
+
+Note: this step also includes Task 5 error handling and Task 7 `shell: true` removal (since we're rewriting the function anyway).
+
+- [ ] **Step 4: Run and verify**
+
+Run: `node bin/quickclaude.js`
+Expected: Interactive autocomplete menu appears. Type to filter projects. Select one and claude launches.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add bin/quickclaude.js package.json package-lock.json
+git commit -m "feat: replace @clack/prompts with prompts for search support
+
+Adds type-to-filter autocomplete when selecting projects.
+Also removes shell:true from spawn for safety."
+```
+
+---
+
+### Task 7: Tag-based publish workflow
+
+**Files:**
+- Modify: `.github/workflows/publish.yml`
+
+- [ ] **Step 1: Update workflow trigger**
+
+Replace the entire `.github/workflows/publish.yml` with:
+
+```yaml
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm install -g npm@latest
+      - run: npm --version
+      - run: npm ci
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .github/workflows/publish.yml
+git commit -m "ci: switch publish trigger from push-to-main to version tags"
+```
+
+---
+
+### Task 8: Final verification
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `npm test`
+Expected: All tests pass (timeAgo, resolvePath, getProjects/getLatestMtime)
+
+- [ ] **Step 2: Run the CLI end-to-end**
+
+Run: `node bin/quickclaude.js`
+Expected:
+- Header "quickclaude" prints
+- Autocomplete project list appears, sorted by recent usage
+- Typing filters projects
+- Selecting a project launches claude in that directory
+
+- [ ] **Step 3: Verify no leftover @clack/prompts references**
+
+Run: `grep -r "clack" bin/ package.json`
+Expected: No matches
+
+- [ ] **Step 4: Final commit if any cleanup needed**
+
+```bash
+git add -A
+git commit -m "chore: final cleanup after improvements"
+```

package/docs/superpowers/specs/2026-04-04-quickclaude-improvements-design.md

@@ -0,0 +1,68 @@
+# quickclaude Improvements Design
+
+## Overview
+
+Seven improvements to quickclaude addressing performance, reliability, UX, and maintainability.
+
+## 1. `resolvePath` Performance
+
+**Problem:** Greedy longest-match tries all segment lengths in reverse, calling `existsSync` for each combination. Theoretical worst-case is factorial in segment count.
+
+**Solution:** Cache matched path segments to avoid redundant `existsSync` calls. The greedy approach stays the same — it's correct — but repeated lookups for the same prefix are eliminated.
+
+## 2. Publish Workflow: Tag-Based Trigger
+
+**Problem:** Current workflow runs `npm publish` on every push to `main`. Fails if version hasn't changed.
+
+**Solution:** Change trigger from `on: push → branches: main` to `on: push → tags: 'v*'`. Publish only runs when a version tag is pushed (e.g., `git tag v1.2.0 && git push --tags`).
+
+## 3. Error Handling
+
+**Problem:** No user-facing error messages when `claude` is not installed or spawn fails.
+
+**Solution:**
+- Before spawning, check if `claude` exists on PATH using `execFileSync("which", ["claude"])` (or platform equivalent)
+- If not found, print a clear message: "Claude Code is not installed" with install instructions
+- Add `error` event handler on the spawned child process
+
+## 4. Tests with `node:test`
+
+**Problem:** No tests exist. `resolvePath` has many edge cases that are easy to break.
+
+**Solution:** Use Node.js built-in `node:test` (zero dependencies, Node 18+).
+
+**Test files:**
+- `test/resolvePath.test.js` — normal paths, hyphenated dirs, spaces, Windows drives, non-existent paths
+- `test/timeAgo.test.js` — boundary values for each time unit
+- `test/getProjects.test.js` — filtering logic (worktrees, non-existent paths)
+
+**Module restructure:** Extract `resolvePath`, `timeAgo`, `getProjectLabel`, `getProjects` into importable functions. Keep `main()` as the CLI entry point. The simplest approach: add named exports alongside the existing CLI execution, guarded by an `import.meta.url` check.
+
+## 5. Replace `@clack/prompts` with `prompts`
+
+**Problem:** `@clack/prompts` `select` does not support type-to-filter. With many projects, finding the right one is slow.
+
+**Solution:** Switch to `prompts` library, using its `autocomplete` prompt type. User types to filter projects by path. Display format (relative time + path) stays the same.
+
+## 6. Remove `shell: true`
+
+**Problem:** `spawn("claude", args, { shell: true })` passes arguments through the shell, risking unintended shell expansion.
+
+**Solution:** Remove `shell: true`. Use `spawn("claude", args, { cwd: selected, stdio: "inherit" })`.
+
+## 7. Improved mtime Accuracy
+
+**Problem:** Using the project directory's own `mtime` which only updates when directory entries change, not when files inside are modified.
+
+**Solution:** Read files inside `~/.claude/projects/<dir>/` and use the most recent file `mtime` as the project's last-used time. This reflects actual Claude Code usage since Claude updates files in this directory during sessions.
+
+## Scope
+
+All changes are within a single file (`bin/quickclaude.js`) plus new test files and workflow update. No new runtime dependencies beyond replacing `@clack/prompts` with `prompts`.
+
+## Testing Strategy
+
+- Unit tests for pure functions (`resolvePath`, `timeAgo`) with mock filesystem where needed
+- Integration test for `getProjects` with a temporary directory structure
+- Manual verification of `autocomplete` UX
+- `npm test` script added to `package.json`

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "quickclaude",
-  "version": "1.0.8",
+  "version": "1.1.1",
   "description": "Quickly launch Claude Code in your project directories",
   "type": "module",
   "bin": {
     "quickclaude": "bin/quickclaude.js"
   },
   "scripts": {
-    "start": "node bin/quickclaude.js"
+    "start": "node bin/quickclaude.js",
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "claude",
@@ -16,11 +17,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/strurao/quickclaude.git"
+    "url": "git+https://github.com/onsenhyo/quickclaude.git"
   },
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@clack/prompts": "^1.1.0"
+    "prompts": "^2.4.2"
   }
 }

package/test/getProjects.test.js

@@ -0,0 +1,36 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { getLatestMtime } from "../bin/quickclaude.js";
+
+describe("getLatestMtime", () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), "qc-mtime-"));
+    // Create files with different mtimes
+    writeFileSync(join(dir, "old.md"), "old");
+    writeFileSync(join(dir, "new.md"), "new");
+    // Set old.md to 1 hour ago
+    const oneHourAgo = new Date(Date.now() - 3600_000);
+    utimesSync(join(dir, "old.md"), oneHourAgo, oneHourAgo);
+  });
+
+  after(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns the most recent file mtime in a directory", () => {
+    const latest = getLatestMtime(dir);
+    // new.md was just created, so latest should be very recent
+    assert.ok(Date.now() - latest < 5000);
+  });
+
+  it("ignores subdirectories, only checks direct files", () => {
+    mkdirSync(join(dir, "subdir"));
+    const latest = getLatestMtime(dir);
+    assert.ok(latest > 0);
+  });
+});

package/test/resolvePath.test.js

@@ -0,0 +1,56 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { resolvePath } from "../bin/quickclaude.js";
+
+describe("resolvePath", () => {
+  let root;
+
+  before(() => {
+    root = mkdtempSync(join(tmpdir(), "qc-test-"));
+    // Create directory structure:
+    // root/Users/test/projects/my-app/
+    // root/Users/test/projects/mcp-overwatch/
+    // root/Users/test/My Documents/
+    mkdirSync(join(root, "Users", "test", "projects", "my-app"), { recursive: true });
+    mkdirSync(join(root, "Users", "test", "projects", "mcp-overwatch"), { recursive: true });
+    mkdirSync(join(root, "Users", "test", "My Documents"), { recursive: true });
+  });
+
+  after(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("resolves a simple path", () => {
+    const encoded = "-Users-test-projects-my-app";
+    assert.equal(resolvePath(encoded, root), join(root, "Users", "test", "projects", "my-app"));
+  });
+
+  it("resolves hyphenated directory names", () => {
+    const encoded = "-Users-test-projects-mcp-overwatch";
+    assert.equal(resolvePath(encoded, root), join(root, "Users", "test", "projects", "mcp-overwatch"));
+  });
+
+  it("resolves space-separated directory names", () => {
+    const encoded = "-Users-test-My-Documents";
+    assert.equal(resolvePath(encoded, root), join(root, "Users", "test", "My Documents"));
+  });
+
+  it("returns null for non-existent paths", () => {
+    const encoded = "-Users-test-nonexistent";
+    assert.equal(resolvePath(encoded, root), null);
+  });
+
+  it("returns null for empty input", () => {
+    assert.equal(resolvePath("", root), null);
+  });
+
+  it("skips Windows drive logic when custom root is provided", () => {
+    // "C" as first part should not be treated as drive letter when root is custom
+    mkdirSync(join(root, "C", "stuff"), { recursive: true });
+    const encoded = "-C-stuff";
+    assert.equal(resolvePath(encoded, root), join(root, "C", "stuff"));
+  });
+});

package/test/timeAgo.test.js

@@ -0,0 +1,42 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { timeAgo } from "../bin/quickclaude.js";
+
+describe("timeAgo", () => {
+  function msAgo(ms) {
+    return Date.now() - ms;
+  }
+
+  it("returns 'just now' for <60 seconds ago", () => {
+    assert.equal(timeAgo(msAgo(0)), "just now");
+    assert.equal(timeAgo(msAgo(30_000)), "just now");
+    assert.equal(timeAgo(msAgo(59_000)), "just now");
+  });
+
+  it("returns minutes for 1-59 minutes ago", () => {
+    assert.equal(timeAgo(msAgo(60_000)), "1m ago");
+    assert.equal(timeAgo(msAgo(30 * 60_000)), "30m ago");
+    assert.equal(timeAgo(msAgo(59 * 60_000)), "59m ago");
+  });
+
+  it("returns hours for 1-23 hours ago", () => {
+    assert.equal(timeAgo(msAgo(60 * 60_000)), "1h ago");
+    assert.equal(timeAgo(msAgo(12 * 60 * 60_000)), "12h ago");
+    assert.equal(timeAgo(msAgo(23 * 60 * 60_000)), "23h ago");
+  });
+
+  it("returns days for 1-6 days ago", () => {
+    assert.equal(timeAgo(msAgo(24 * 60 * 60_000)), "1d ago");
+    assert.equal(timeAgo(msAgo(6 * 24 * 60 * 60_000)), "6d ago");
+  });
+
+  it("returns weeks for 7-27 days ago", () => {
+    assert.equal(timeAgo(msAgo(7 * 24 * 60 * 60_000)), "1w ago");
+    assert.equal(timeAgo(msAgo(21 * 24 * 60 * 60_000)), "3w ago");
+  });
+
+  it("returns months for 28+ days ago", () => {
+    assert.equal(timeAgo(msAgo(30 * 24 * 60 * 60_000)), "1mo ago");
+    assert.equal(timeAgo(msAgo(90 * 24 * 60 * 60_000)), "3mo ago");
+  });
+});