cursor-history

A fast CLI for exporting and searching Cursor conversation history, built with TypeScript + oclif.

Installation — TL;DR

# with npm
npm install -g @johnlindquist/cursor-history

# with pnpm ≥ 10 (read the next section!)
PNPM_ENABLE_PREBUILDS=true pnpm add -g @johnlindquist/cursor-history

Why two commands? cursor‑history depends on better‑sqlite3, a native add‑on. npm will download a ready‑made binary for your platform; pnpm won't unless you flip an opt‑in flag. Details below.
When the binary is missing you'll get the famous Could not locate the bindings file stack‑trace at runtime.

Basic usage

# Export the latest conversation to a Markdown file + clipboard
chi

# Extract *all* conversations to ./conversations/<timestamp>/*
chi --extract

# Fuzzy‑search by title and copy the chosen conversation to clipboard
chi --search

# Interactively browse any workspace and pick a conversation
chi --browse

# Manage old exports (delete older than 30 d)
chi --manage --older-than 30d

See chi --help for the full command list.

Troubleshooting checklist

1. node -p "process.versions.modules" returns 115 on Node 20; match that to the folder name in better-sqlite3/lib/binding. (github.com)
2. Make sure you're actually running the pnpm‑installed binary: which chi.
3. Delete stale global installs (pnpm uninstall -g, npm uninstall -g) before switching package managers.

Troubleshooting: Native Module Version Mismatch (better-sqlite3)

If you see errors like this when running the CLI globally:

The module 'better_sqlite3.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 127. This version of Node.js requires NODE_MODULE_VERSION 115. Please try re-compiling or re-installing the module (for instance, using `npm rebuild` or `npm install`).

Solution for pnpm global installs

Run this command:

cd $(pnpm root -g)/better-sqlite3 && npm rebuild better-sqlite3

This will rebuild the native binary for your current Node.js version and architecture. After running this, your CLI should work globally.

Why is this needed?

• pnpm's global store does not always trigger a native rebuild for dependencies like better-sqlite3 when installing a tarball or linking.
• The native binary may be left in an old or missing state after a Node.js upgrade or a global install.
• Manually running npm rebuild in the global store directory ensures the binary is rebuilt for your current environment.

If you still have issues

• Make sure you are using the same Node.js version for both the install and when running the CLI.
• You may need to remove and reinstall the global package if the error persists.

Using pnpm with native modules

What's happening under the hood?

| Step | npm | pnpm ≤ 10 default | |------|-----|-------------------| | Install better‑sqlite3 | Downloads pre‑built better_sqlite3.node that matches your Node ABI (node‑v115‑darwin‑arm64, etc.) | Skips the prebuild and blocks the post‑install compile script unless the package is in the allow‑list | | Runtime | require('better-sqlite3') finds the binary and works | Throws Could not locate the bindings file |

The pnpm behaviour is intentional: it prevents unreviewed packages from running arbitrary build scripts on your machine. You have three ways to opt‑in:

1. Turn on the prebuild switch (the quickest fix) 🟢

   PNPM_ENABLE_PREBUILDS=true pnpm add -g @johnlindquist/cursor-history

   The env‑var (or the matching .npmrc key enable-prebuilt-binary=true) tells pnpm to download official prebuilt binaries for all packages that ship them, including better‑sqlite3. No compilation needed. (github.com, github.com)

2. Manually approve the build scripts 🟡

   If you forgot the flag and saw

   Ignored build scripts: better-sqlite3, sqlite3.
   Run "pnpm approve-builds -g" to pick which dependencies should be allowed to run scripts.

   just do it:

   pnpm approve-builds -g   # interactive prompt ‑ pick better‑sqlite3 & sqlite3

   This whitelists the packages globally and re‑runs their install/postinstall scripts, compiling the native addon from source. Docs: pnpm approve-builds was added in v10.1 and gained the ‑g flag in v10.4. (pnpm.io, github.com)

3. Force a rebuild 🔧

   # prerequisite tool‑chain once per machine
   xcode-select --install      # macOS — installs clang & make
   pnpm install -g node-gyp    # wrapper around gyp
   
   # then, inside the global store path
   cd "$(pnpm root -g)/.pnpm/better-sqlite3@*/node_modules/better-sqlite3"
   pnpm rebuild                # runs node-gyp from source

   Use this when you need a from‑source build (e.g. bleeding‑edge Node version without prebuilds). (github.com, github.com)

FAQ

• Do I have to do this every time?
  No. Set the flag once in your user npmrc:
  pnpm config set enable-prebuilt-binary true or export the env variable from your shell profile.
• What if I see arm64e vs arm64 errors?
  You're probably mixing Rosetta and native Node builds. Re‑install Node with the same architecture as your terminal session. (github.com)
• Is there a prebuild‑only fork?
  Yes, better-sqlite3-with-prebuilds publishes the binary directly in the tarball, avoiding the download step altogether. Feel free to swap it in your own projects. cite turn1search9

Contributing

PRs and issues are welcome! If you have ideas for smoothing out the native‑module install story (post‑install hook, binary‑safe fork, Docker build, etc.) open a discussion.

© 2025 John Lindquist — MIT