cursor-helper

Stop losing your Cursor chat history. This CLI fixes the things Cursor doesn't expose in the UI.

The Problem

When you rename or move a project folder, Cursor loses all your chat history. Weeks of conversations, context, and problem-solving — gone.

The Solution

cursor-helper rename /old/project /new/project

Your chat history, workspace settings, and MCP cache stay intact.

Installation

# From crates.io (recommended)
cargo install cursor-helper

# Or from source
git clone https://github.com/lucifer1004/cursor-helper
cd cursor-helper
cargo install --path .

Requires Rust 1.70+. Works on macOS, Linux, and Windows.

Pre-built binaries for major platforms are available on the Releases page.

Key Commands

rename — Move Projects Without Losing History

# Move/rename a project
cursor-helper rename /path/to/old-project /path/to/new-project

# Copy instead of move
cursor-helper rename --copy /path/to/project /path/to/project-copy

# Copy with full composer index rebuild (force re-index of chat sidebar)
cursor-helper rename --copy --force-index /path/to/project /path/to/project-copy

# Preview changes first
cursor-helper rename -n /path/to/old /path/to/new

For --copy, the command now:

• copies the full workspaceStorage/<hash>/ directory instead of only state.vscdb
• updates folderUri / workspace mappings in storage.json and globalStorage/state.vscdb
• rewrites composer.composerData in the target workspace database (including normalized paths and hashes)
• clears stale cache folders:
  • <Cursor config>/CachedData/
  • <Cursor config>/GPUCache/
  • <new workspace hash>/anysphere.cursor-retrieval/

Suggested validation cases:

1. same filesystem rename cursor-helper rename /tmp/proj /tmp/proj-renamed and verify chat count matches before/after in list.

2. cross-filesystem copy Copy a project from one mount to another and run cursor-helper rename --copy /mnt/source/proj /mnt/other/proj-copy; confirm list shows full history in Cursor.

3. UI refresh path Open Cursor after copy and confirm:

   • sidebar shows full chat list
   • individual sessions load correctly
   • no duplicate or missing workspace prompts

export-chat — Export Everything Cursor Hides

Cursor's built-in export omits thinking blocks and tool calls. This doesn't.

# Full export with thinking, tools, and token counts
cursor-helper export-chat /path/to/project -v

# Just the conversations
cursor-helper export-chat /path/to/project

# Export to JSON
cursor-helper export-chat /path/to/project --format json -o export.json

# Split into separate files per session
cursor-helper export-chat /path/to/project --split --output ./chats/

# Exclude empty sessions
cursor-helper export-chat /path/to/project --exclude-blank

# Remote sessions (SSH, tunnels, WSL, dev containers)
cursor-helper export-chat /home/user/project        # By remote path
cursor-helper export-chat --workspace-id abc123def  # By workspace ID (from 'list')

list — See All Your Projects

# List all projects (most recent first)
cursor-helper list

# Show workspace IDs (for use with export-chat --workspace-id)
cursor-helper list --with-id

# Sort by chat count
cursor-helper list --sort chats --limit 10

# Filter by type
cursor-helper list --filter remote   # SSH/tunnel projects
cursor-helper list --filter local    # Local projects

clean — Reclaim Disk Space

Remove workspace data for deleted projects.

cursor-helper clean --dry-run  # Preview
cursor-helper clean --yes      # Delete without confirmation

Other Commands

How It Works

Cursor stores metadata in platform-specific locations:

Each project has a unique ID derived from its path. When you rename a folder, the ID changes and Cursor can't find the old data. This tool updates the necessary references.

Note: Linux support is experimental. Workspace hash computation depends on filesystem birthtime support, which varies by filesystem and kernel version.

Disclaimer

This tool is not affiliated with or endorsed by Anysphere, Inc. (Cursor).

It reads your local data files for personal backup and portability. It does not access Cursor's servers, APIs, or source code. See DISCLAIMER.md for details.

License

MIT — see LICENSE.

Related

• cursor-chat-export
• cursor-view