ChatShelf

A Cursor IDE extension that brings order to your agent chat conversations. Browse, organize, star, and archive your chats -- all from a dedicated sidebar.

Features

Five Organized Sections

Your chats are automatically organized into collapsible sections in the sidebar:

• CURRENT FILE -- Shows chats that reference the file you're currently editing. As you switch between files, this section updates in real time.
• RECENT -- Displays your most recent chats, sorted by timestamp. Right-click the section header to configure how many chats to show (1--10).
• BY BRANCH -- Groups chats by Git repository and branch. Quickly find conversations tied to a specific feature branch.
• BY FOLDER -- Organize chats into custom folders you create. Supports drag-and-drop to move chats between folders.
• ARCHIVED -- A collapsible section for chats you've archived. Keeps them out of the way without losing them.

Star / Favourite Chats

Mark important chats with a star so they always appear at the top of every section.

• Right-click a chat and select Star Chat to prioritize it
• Starred chats display a filled star icon, replacing the default chat icon
• Stars are reflected across all sections (CURRENT FILE, RECENT, BY BRANCH, BY FOLDER)
• Right-click again and select Unstar Chat to remove the star

Archive Chats

Move chats you no longer actively need into the ARCHIVED section.

• Right-click a chat and select Archive Chat to remove it from all active sections
• Archived chats appear in the dedicated ARCHIVED section at the bottom
• Right-click an archived chat and select Unarchive Chat to restore it
• Bulk unarchive: right-click a branch or folder and select Unarchive Chats to restore all archived chats in that group

Custom Folders with Drag-and-Drop

Create your own organizational structure for chats.

• Click the folder icon next to BY FOLDER to create a new folder
• Drag and drop chats between folders within the BY FOLDER section
• Right-click a folder to rename or delete it
• Move any chat to a folder via right-click > Move to Folder (with an option to create a new folder on the fly)
• Right-click a chat in a folder and select Remove from Folder to unfile it

Context Percentage

Each chat displays its context usage percentage next to the title, so you can see at a glance how much context window a conversation has consumed.

Smart Chat Counts

Branch and folder nodes show chat counts with an archived indicator:

• 3 chats -- when all chats are active
• 3/1 chats -- when there are 3 active and 1 archived chat

Live Updates

The extension watches Cursor's internal database for changes. New chats, title updates, and deletions are reflected automatically without manual refresh.

Click to Open

Click any chat in the sidebar to open it directly in Cursor's agent chat panel.

Installation

1. Download the .vsix file
2. In Cursor, open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
3. Run Extensions: Install from VSIX...
4. Select the downloaded .vsix file
5. Reload the window

The extension appears as a chat icon in the activity bar (left sidebar).

Commands

All commands are accessible via right-click context menus on the relevant items.

Requirements

• Cursor IDE (VS Code-based)
• macOS (reads from ~/Library/Application Support/Cursor/)
• Git (for branch detection)
• System sqlite3 CLI (pre-installed on macOS)

How It Works

The extension reads chat metadata from Cursor's internal workspace storage (state.vscdb) using the system sqlite3 CLI. It extracts chat titles, timestamps, context percentages, and referenced file paths. File system watchers on the database trigger automatic UI refreshes when chats change.

User preferences (folders, assignments, starred/archived state, recent count) are persisted in VS Code's globalState and survive across sessions.

License

MIT