@yyyeader/claude-recall 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+<p align="center">
+  <h1 align="center">claude-recall</h1>
+  <p align="center">
+    <strong>Never lose a Claude Code session again.</strong>
+  </p>
+  <p align="center">
+    Search, find, and resume any Claude Code conversation across all your projects — instantly.
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/claude-recall"><img src="https://img.shields.io/npm/v/claude-recall.svg" alt="npm version"></a>
+    <a href="https://github.com/yyyeader/claude-recall/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/claude-recall.svg" alt="license"></a>
+    <a href="https://www.npmjs.com/package/claude-recall"><img src="https://img.shields.io/npm/dm/claude-recall.svg" alt="downloads"></a>
+  </p>
+</p>
+
+---
+
+## The Problem
+
+You've been deep in a Claude Code session — debugging, architecting, iterating. You close the terminal, switch projects, and when you come back:
+
+```
+$ claude --resume abc123
+No conversation found with session ID: abc123
+```
+
+Claude Code's `/resume` only searches the **current directory**. If you're not in the exact same folder where the session was created, it's invisible.
+
+You know the session exists somewhere in `~/.claude/projects/`, but good luck finding it manually across dozens of encoded directories.
+
+## The Solution
+
+```bash
+npm install -g claude-recall
+```
+
+```bash
+claude-recall debug          # Find that debugging session from last week
+claude-recall                # Browse everything with fzf
+claude-recall -j | jq        # Pipe JSON to your own tools
+```
+
+`claude-recall` scans **all** your Claude Code sessions, lets you search by keyword, and gives you the exact command to resume — from any directory.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g claude-recall
+```
+
+### 2. Add the shell wrapper (recommended)
+
+Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+cr() {
+  local cmd
+  cmd=$(claude-recall "$@" 2>/dev/null | tail -1)
+  if [ -n "$cmd" ] && echo "$cmd" | grep -q "^cd "; then
+    eval "$cmd"
+  fi
+}
+```
+
+### 3. Use it
+
+```bash
+cr                    # Browse all sessions with fzf
+cr e2b                # Search + select + auto cd + resume
+cr terraform          # Find that infra session from days ago
+```
+
+One command. Search, select, resume. Done.
+
+### Claude Code `/recall` command
+
+Want to search sessions from *inside* Claude Code?
+
+```bash
+# Install the slash command
+claude-recall-install
+# Or manually:
+cp node_modules/claude-recall/commands/recall.md ~/.claude/commands/
+```
+
+Then:
+
+```
+You: /recall authentication
+Claude: Found 3 sessions matching "authentication":
+  1. 2024-03-10 /Users/you/myapp — "help me add JWT auth to the API..."
+  2. ...
+```
+
+## All Options
+
+```
+claude-recall [keyword]         Interactive search (fzf)
+claude-recall -l [keyword]      List mode (no interaction)
+claude-recall -j [keyword]      JSON output (for scripting)
+claude-recall -p <project>      Filter by project name
+claude-recall -n <number>       Limit results (default: 50)
+claude-recall -h                Help
+```
+
+## How It Works
+
+Claude Code stores sessions as JSONL files in `~/.claude/projects/`, with directory names like:
+
+```
+-Users-you-projects-my-cool-app    →    /Users/you/projects/my-cool-app
+```
+
+The catch? `-` could be a path separator OR part of a directory name (`e2b-infra`, `my-cool-app`). Simple string replacement breaks.
+
+`claude-recall` uses a **greedy path resolution algorithm**: it tries the longest possible directory name first, checks if it exists on disk, and falls back to shorter segments. This correctly resolves ambiguous paths like:
+
+```
+-Users-you-work-e2b-infra    →    /Users/you/work/e2b-infra      (not /work/e2b/infra)
+```
+
+Then it stream-parses each JSONL file, extracts user messages as summaries, and presents everything through fzf for instant fuzzy search.
+
+## Requirements
+
+- **Node.js** >= 18
+- **[fzf](https://github.com/junegunn/fzf)** — optional but recommended (falls back to built-in selector)
+
+## Contributing
+
+Issues and PRs welcome. This is a simple tool — the best contributions are bug fixes, platform compatibility improvements, and better session parsing.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <sub>Built because <code>/resume</code> kept saying "No conversation found" one too many times.</sub>
+</p>

package/bin/claude-recall.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { scanSessions } from "../src/scanner.js";
+import { formatTable, formatJSON, formatFzf } from "../src/formatter.js";
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const flags = {
+  list: false,
+  json: false,
+  limit: 50,
+  project: null,
+  help: false,
+  keyword: [],
+};
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case "--list":
+    case "-l":
+      flags.list = true;
+      break;
+    case "--json":
+    case "-j":
+      flags.json = true;
+      break;
+    case "--limit":
+    case "-n":
+      flags.limit = parseInt(args[++i], 10) || 50;
+      break;
+    case "--project":
+    case "-p":
+      flags.project = args[++i];
+      break;
+    case "--help":
+    case "-h":
+      flags.help = true;
+      break;
+    default:
+      if (!args[i].startsWith("-")) {
+        flags.keyword.push(args[i]);
+      }
+      break;
+  }
+}
+
+if (flags.help) {
+  console.log(`claude-recall - Search and resume Claude Code sessions
+
+Usage:
+  claude-recall [keyword]          Interactive search with fzf
+  claude-recall -l [keyword]       List sessions (no interaction)
+  claude-recall -j [keyword]       Output as JSON
+  claude-recall -p <project>       Filter by project name
+  claude-recall -n <number>        Limit results (default: 50)
+
+Options:
+  -l, --list       List mode (no fzf)
+  -j, --json       JSON output
+  -p, --project    Filter by project name
+  -n, --limit      Max number of sessions to scan
+  -h, --help       Show this help
+
+Examples:
+  claude-recall                    Browse all recent sessions
+  claude-recall e2b                Search sessions mentioning "e2b"
+  claude-recall -l claudia         List sessions about "claudia"
+  claude-recall -j --limit 10     Export 10 most recent sessions as JSON`);
+  process.exit(0);
+}
+
+const keyword = flags.keyword.join(" ") || undefined;
+
+// Scan sessions
+const sessions = await scanSessions({
+  keyword,
+  project: flags.project,
+  limit: flags.limit,
+});
+
+if (sessions.length === 0) {
+  console.error(keyword ? `No sessions matching "${keyword}"` : "No sessions found");
+  process.exit(1);
+}
+
+// JSON mode
+if (flags.json) {
+  console.log(formatJSON(sessions));
+  process.exit(0);
+}
+
+// List mode
+if (flags.list) {
+  console.log(formatTable(sessions));
+  process.exit(0);
+}
+
+// Interactive mode: try fzf, fallback to built-in selector
+const selected = await selectSession(sessions, keyword);
+if (!selected) process.exit(0);
+
+console.log(`\n\x1b[36m📂 ${selected.workDir}\x1b[0m`);
+console.log(`\x1b[2m🔗 ${selected.sessionId}\x1b[0m\n`);
+
+if (!existsSync(selected.workDir)) {
+  console.error(`⚠️  Directory does not exist: ${selected.workDir}`);
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await new Promise((resolve) => {
+    rl.question("Still try to resume? (y/N) ", resolve);
+  });
+  rl.close();
+  if (answer.toLowerCase() !== "y") process.exit(0);
+}
+
+// Output the resume command — user's shell will execute it
+// When used with shell function wrapper, this enables cd + resume
+console.log(`cd "${selected.workDir}" && claude --resume "${selected.sessionId}"`);
+
+// ---
+
+async function selectSession(sessions, initialQuery) {
+  // Try fzf first
+  if (hasFzf()) {
+    return selectWithFzf(sessions, initialQuery);
+  }
+  return selectWithBuiltin(sessions);
+}
+
+function hasFzf() {
+  try {
+    execFileSync("which", ["fzf"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function selectWithFzf(sessions, initialQuery) {
+  return new Promise((resolve) => {
+    const input = sessions
+      .map((s, i) => {
+        const time = formatTimeShort(s.modifiedAt);
+        const dir = s.workDir.length > 42 ? "..." + s.workDir.slice(-39) : s.workDir;
+        const summary = (s.summary || "").slice(0, 80);
+        return `${i + 1}│${time} │ ${dir.padEnd(42)} │ ${summary}`;
+      })
+      .join("\n");
+
+    const fzfArgs = [
+      "--height=80%",
+      "--border",
+      "--header=  Time             │ Directory                                    │ Summary",
+      "--no-sort",
+      "--ansi",
+      "--delimiter=│",
+      "--with-nth=2..",
+    ];
+    if (initialQuery) {
+      fzfArgs.push(`--query=${initialQuery}`);
+    }
+
+    const fzf = spawn("fzf", fzfArgs, {
+      stdio: ["pipe", "pipe", "inherit"],
+    });
+
+    let output = "";
+    fzf.stdout.on("data", (d) => (output += d.toString()));
+
+    fzf.on("close", (code) => {
+      if (code !== 0 || !output.trim()) {
+        resolve(null);
+        return;
+      }
+      const idx = parseInt(output.trim().split("│")[0], 10) - 1;
+      resolve(sessions[idx] || null);
+    });
+
+    fzf.stdin.write(input);
+    fzf.stdin.end();
+  });
+}
+
+async function selectWithBuiltin(sessions) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+
+  console.error("\nSelect a session:\n");
+  const displayed = sessions.slice(0, 20);
+  displayed.forEach((s, i) => {
+    const time = formatTimeShort(s.modifiedAt);
+    const summary = (s.summary || "").slice(0, 60);
+    console.error(`  \x1b[33m${String(i + 1).padStart(3)}\x1b[0m  ${time}  ${summary}`);
+  });
+
+  if (sessions.length > 20) {
+    console.error(`\n  ... and ${sessions.length - 20} more (use fzf for full list)`);
+  }
+
+  const answer = await new Promise((resolve) => {
+    rl.question("\nEnter number (or q to quit): ", resolve);
+  });
+  rl.close();
+
+  if (answer === "q" || answer === "") return null;
+  const idx = parseInt(answer, 10) - 1;
+  return displayed[idx] || null;
+}
+
+function formatTimeShort(date) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  const h = String(date.getHours()).padStart(2, "0");
+  const min = String(date.getMinutes()).padStart(2, "0");
+  return `${y}-${m}-${d} ${h}:${min}`;
+}

package/commands/recall.md

@@ -0,0 +1,25 @@
+---
+description: Search and resume Claude Code sessions across all projects
+allowed-tools: Bash(claude-recall:*), Bash(node:*)
+argument-hint: [keyword]
+---
+
+Search Claude Code sessions across all projects. The user wants to find and resume a previous session.
+
+Run the search command:
+
+!`claude-recall --json $ARGUMENTS 2>/dev/null | head -100`
+
+Present the results to the user as a clear numbered table with these columns:
+- # (index)
+- Time (when the session was last modified)
+- Directory (the project directory)
+- Summary (first user messages from the session)
+
+Ask the user which session they want to resume. Once they choose, tell them the exact command to run:
+
+```
+cd <workDir> && claude --resume <sessionId>
+```
+
+If no results are found, let the user know and suggest they try a different keyword.

package/install-command.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Install the /recall command for Claude Code
+
+set -e
+
+COMMANDS_DIR="$HOME/.claude/commands"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+mkdir -p "$COMMANDS_DIR"
+cp "$SCRIPT_DIR/commands/recall.md" "$COMMANDS_DIR/recall.md"
+
+echo "Installed /recall command to $COMMANDS_DIR/recall.md"
+echo "Use /recall [keyword] in Claude Code to search sessions."

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@yyyeader/claude-recall",
+  "version": "1.0.0",
+  "description": "Search and resume Claude Code sessions across all projects",
+  "main": "src/index.js",
+  "bin": {
+    "claude-recall": "bin/claude-recall.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node bin/claude-recall.js --list"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-code-session",
+    "session",
+    "search",
+    "resume",
+    "cli",
+    "ai",
+    "anthropic",
+    "developer-tools",
+    "productivity",
+    "fzf",
+    "terminal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yyyeader/claude-recall.git"
+  },
+  "homepage": "https://github.com/yyyeader/claude-recall#readme",
+  "bugs": {
+    "url": "https://github.com/yyyeader/claude-recall/issues"
+  },
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "commands/",
+    "install-command.sh",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/formatter.js

@@ -0,0 +1,71 @@
+/**
+ * Format session data for terminal or JSON output.
+ */
+
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
+
+function formatTime(date) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  const h = String(date.getHours()).padStart(2, "0");
+  const min = String(date.getMinutes()).padStart(2, "0");
+  return `${y}-${m}-${d} ${h}:${min}`;
+}
+
+/**
+ * Format sessions as a colored terminal table.
+ */
+export function formatTable(sessions) {
+  if (sessions.length === 0) return "No sessions found.";
+
+  const lines = sessions.map((s) => {
+    const time = formatTime(s.modifiedAt);
+    const dir = truncate(s.workDir, 45);
+    const summary = truncate(s.summary || "", 70);
+    return `${DIM}${time}${RESET}  ${CYAN}${dir.padEnd(45)}${RESET}  ${summary}`;
+  });
+
+  const header = `${YELLOW}${"Time".padEnd(18)}${"Directory".padEnd(47)}Summary${RESET}`;
+  return [header, ...lines].join("\n");
+}
+
+/**
+ * Format sessions as JSON.
+ */
+export function formatJSON(sessions) {
+  return JSON.stringify(
+    sessions.map((s) => ({
+      sessionId: s.sessionId,
+      workDir: s.workDir,
+      modifiedAt: s.modifiedAt.toISOString(),
+      summary: s.summary,
+    })),
+    null,
+    2
+  );
+}
+
+/**
+ * Format sessions for fzf input (tab-separated, one per line).
+ * Format: index\ttime\tworkDir\tsessionId\tsummary
+ */
+export function formatFzf(sessions) {
+  return sessions
+    .map((s, i) => {
+      const time = formatTime(s.modifiedAt);
+      const dir = truncate(s.workDir, 45);
+      const summary = truncate(s.summary || "", 80);
+      return `${i + 1}\t${time}\t${dir}\t${s.sessionId}\t${summary}`;
+    })
+    .join("\n");
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { scanSessions } from "./scanner.js";
+export { resolvePath } from "./resolver.js";
+export { extractSummary } from "./parser.js";
+export { formatTable, formatJSON, formatFzf } from "./formatter.js";

package/src/parser.js

@@ -0,0 +1,46 @@
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+
+/**
+ * Extract a summary from a Claude Code session JSONL file.
+ * Reads the first few user messages and concatenates their text content.
+ */
+export async function extractSummary(filePath, maxMessages = 3) {
+  const texts = [];
+
+  const rl = createInterface({
+    input: createReadStream(filePath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    if (texts.length >= maxMessages) break;
+
+    try {
+      const entry = JSON.parse(line);
+      if (entry.type !== "user") continue;
+
+      const content = entry.message?.content;
+      if (!content) continue;
+
+      let text;
+      if (typeof content === "string") {
+        text = content;
+      } else if (Array.isArray(content)) {
+        // Extract text blocks, skip tool_result blocks
+        text = content
+          .filter((b) => b.type === "text" && b.text)
+          .map((b) => b.text)
+          .join(" ");
+      }
+
+      if (text && text.trim()) {
+        texts.push(text.trim());
+      }
+    } catch {
+      // Skip malformed lines
+    }
+  }
+
+  return texts.join(" ").replace(/\s+/g, " ").slice(0, 300);
+}

package/src/resolver.js

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+
+/**
+ * Resolve an encoded Claude Code project directory name back to a real filesystem path.
+ *
+ * Claude Code encodes project paths by replacing `/` with `-`:
+ *   /Users/fuxianda/VMWokrSpace/e2b-infra  →  -Users-fuxianda-VMWokrSpace-e2b-infra
+ *
+ * The challenge is that directory names themselves may contain hyphens,
+ * so we use a greedy algorithm: try the longest possible segment first,
+ * check if it exists on disk, and fall back to shorter segments.
+ */
+export function resolvePath(encoded) {
+  // Strip leading dash
+  if (encoded.startsWith("-")) {
+    encoded = encoded.slice(1);
+  }
+
+  const parts = encoded.split("-");
+  let current = "/";
+  let i = 0;
+
+  while (i < parts.length) {
+    let found = false;
+    const remaining = parts.length - i;
+
+    // Greedy: try longest candidate first
+    for (let tryLen = remaining; tryLen >= 1; tryLen--) {
+      const candidate = parts.slice(i, i + tryLen).join("-");
+      const testPath = current + candidate;
+
+      if (existsSync(testPath)) {
+        current = testPath + "/";
+        i += tryLen;
+        found = true;
+        break;
+      }
+    }
+
+    if (!found) {
+      // No match — use single segment as path component
+      current += parts[i] + "/";
+      i++;
+    }
+  }
+
+  // Remove trailing slash
+  return current.replace(/\/+$/, "");
+}

package/src/scanner.js

@@ -0,0 +1,117 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { resolvePath } from "./resolver.js";
+import { extractSummary } from "./parser.js";
+
+const CLAUDE_DIR = join(homedir(), ".claude", "projects");
+
+/**
+ * Scan all Claude Code sessions across all projects.
+ * Returns an array of session objects sorted by modification time (newest first).
+ */
+export async function scanSessions({ keyword, project, limit } = {}) {
+  let projectDirs;
+  try {
+    projectDirs = readdirSync(CLAUDE_DIR, { withFileTypes: true }).filter(
+      (d) => d.isDirectory()
+    );
+  } catch {
+    return [];
+  }
+
+  const sessions = [];
+
+  for (const dir of projectDirs) {
+    const projectEncoded = dir.name;
+    const projectPath = join(CLAUDE_DIR, projectEncoded);
+
+    // List JSONL files directly under the project dir (skip subagents)
+    let files;
+    try {
+      files = readdirSync(projectPath)
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((f) => join(projectPath, f));
+    } catch {
+      continue;
+    }
+
+    // Also check one level deeper for session directories (session-id/session.jsonl pattern)
+    try {
+      const subdirs = readdirSync(projectPath, { withFileTypes: true }).filter(
+        (d) => d.isDirectory() && d.name !== "subagents"
+      );
+      for (const subdir of subdirs) {
+        try {
+          const subFiles = readdirSync(join(projectPath, subdir.name))
+            .filter((f) => f.endsWith(".jsonl"))
+            .map((f) => join(projectPath, subdir.name, f));
+          files.push(...subFiles);
+        } catch {
+          // skip
+        }
+      }
+    } catch {
+      // skip
+    }
+
+    const workDir = resolvePath(projectEncoded);
+
+    // Filter by project name if specified
+    if (project) {
+      const projectLower = project.toLowerCase();
+      if (
+        !projectEncoded.toLowerCase().includes(projectLower) &&
+        !workDir.toLowerCase().includes(projectLower)
+      ) {
+        continue;
+      }
+    }
+
+    for (const file of files) {
+      try {
+        const stat = statSync(file);
+        const sessionId = basename(file, ".jsonl");
+
+        // Skip subagent files
+        if (file.includes("/subagents/")) continue;
+
+        sessions.push({
+          sessionId,
+          projectEncoded,
+          workDir,
+          filePath: file,
+          modifiedAt: stat.mtime,
+        });
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  // Sort by modification time, newest first
+  sessions.sort((a, b) => b.modifiedAt - a.modifiedAt);
+
+  // Extract summaries (in parallel, batched)
+  const batch = limit ? sessions.slice(0, limit) : sessions;
+  await Promise.all(
+    batch.map(async (s) => {
+      s.summary = await extractSummary(s.filePath);
+    })
+  );
+
+  // Filter by keyword if specified
+  let result = batch;
+  if (keyword) {
+    const kw = keyword.toLowerCase();
+    result = batch.filter(
+      (s) =>
+        s.summary.toLowerCase().includes(kw) ||
+        s.workDir.toLowerCase().includes(kw) ||
+        s.projectEncoded.toLowerCase().includes(kw) ||
+        s.sessionId.toLowerCase().includes(kw)
+    );
+  }
+
+  return result;
+}