Chat Shelf for Claude Code

Working name. Easy to change before the first public release.

Keep every Claude Code chat in your project in one sidebar. You can sort chats into colored folders, see at a glance which ones are open, working, or waiting for you, search everything that was said, and keep chats safe from Claude Code's 30-day cleanup. Click a chat to reopen it in the normal Claude Code tab.

Status: v0.3 test build. See docs/PROPOSAL.md for the roadmap.

Features

• Every chat, automatically. Lists all Claude Code chats for the open folder, whether you started them in the VS Code panel, the terminal, or Claude Desktop.

• See what's open.

  • 🟢 open in a tab or terminal
  • ⟳ Working (Claude is busy)
  • 🟠 Needs you (Claude is waiting for your input or a permission)
  • ○ closed

  The Open and Needs you filters show just those chats.

• Folders that stay out of your way.

  • Creating: click + New folder at the end of the list and type the name right there.
  • Colors: every folder gets a color, shown by its folder icon, a tinted header and a line beside its chats. Click the folder icon to change it: pick one of 8 theme-aware presets or any custom color (system color picker or hex). After the presets are used up, new folders get distinct generated colors.
  • Sticky headers: while you scroll through a long folder, its header stays at the top.
  • Moving:
    • Drag chats (or whole folders) onto a folder.
    • Or hover a chat → 📂 → pick a folder, or create a new one in the same menu.
  • Subfolders: right-click a folder → New Subfolder.

• One click to reopen. Opens the chat in the official Claude Code tab, or focuses it if it's already open. There's no "Allow extension to open this URI?" prompt.

• New chat in a folder. The + on a folder starts a chat and files it there.

• ✨ Organize with Claude. Click ✨ (or Organize on the Unsorted section) and Claude sorts your chats into your folders, creating new ones where it makes sense. You get a plan to review, can untick anything, then Apply, and Undo is available afterwards. If you want, new chats can also be sorted in the background. Chat Shelf asks first, because it uses a little of your Claude usage.

  • Uses your own Claude. Runs through your existing Claude Code login, so there's no API key and nothing to set up. Chat Shelf calls the claude CLI in its one-off mode: no tools, nothing saved to your chat history, your hooks switched off.
  • What Claude sees: only titles, first and last messages, and branch names. Never your code.

• Keep forever. Claude Code deletes chats after 30 days by default.

  • What's kept: Chat Shelf keeps a safe copy of every chat you file in a folder, plus any chat you pin (📌).
  • After Claude deletes one: kept chats stay in the list as Saved copy, and clicking one restores it so Claude can resume it.
  • Warning: chats about to be deleted show ⚠ Deletes in 3d.

• Full-text search. The search box matches titles instantly, then searches inside every conversation and shows the matching snippet.

• Rename chats and folders: double-click or F2. Archive chats you don't need to see; they move to the 🗄 filter and are never deleted.

• Badge when Claude needs you: the Chat Shelf icon shows how many chats are waiting for your input.

• Close idle tabs: one click closes the Claude tabs of chats that aren't doing anything. Use it for everything (title bar, or the Open filter) or for one folder (right-click). Chats that are working or waiting for you are never closed, and closed chats stay in the sidebar, one click from reopening.

• Go to Chat… (Cmd+Alt+K / Ctrl+Alt+K): type a few letters of any chat and press Enter. No mouse needed; the 🖥 button opens it in a terminal instead.

• Pin to top: 📌 keeps a chat at the top of its folder.

• Multi-select with Ctrl/Cmd-click or Shift-click, then move, pin or archive them all at once.

• Right-click menus for everything (open in terminal, copy session ID, reveal transcript…).

• Keyboard: ↑/↓ move between rows, Enter opens a chat, ←/→ collapse and expand folders, F2 renames, Delete archives.

Install the test build

1. Download the latest chat-shelf-<version>.vsix.
2. In VS Code (or Cursor/Windsurf): Cmd/Ctrl+Shift+P → Extensions: Install from VSIX… → pick the file. This replaces the previous version and keeps your folders.
3. Click the Chat Shelf icon in the Activity Bar (a folder shaped like a speech bubble).

Requirements: VS Code 1.94+, and the official Claude Code extension for opening chats in the chat tab. Without it, chats open in a terminal (needs the claude CLI).

Testing checklist (v0.3)

If organizing fails, the card says why (e.g. "Claude Code isn't signed in"). Copy that message into your bug report.

Testing checklist (v0.2)

Report bugs with: what you did, what happened, and your editor and OS. For errors, open Help → Toggle Developer Tools → Console and look for lines with Chat Shelf.

Settings

How it works

• Reading chats. Claude Code saves every chat as ~/.claude/projects/<project>/<session-id>.jsonl. Chat Shelf only reads these files (start and end only, cached).
• Open / working / needs you. Two sources are combined:
  • Claude Code's own status records in ~/.claude/sessions/*.json (busy, waiting, idle…).
  • The Claude tabs open in this window. Tabs that Chat Shelf opened are matched to their chat exactly; other tabs are matched by title.
• Opening chats. Calls the Claude Code extension's claude-vscode.editor.open command (the same thing its vscode://anthropic.claude-code/open link does, minus the pop-up). It falls back to the link if the command isn't available.
• Keeping chats. Copies go to ~/.claude-chats/projects/<project>/kept/. A copy is refreshed at most every 2 minutes while a chat is active. Restoring copies the file back so Claude can resume it, and gives it a fresh retention period.
• Your folders. Saved in ~/.claude-chats/projects/<project>/state.json. They aren't stored in your repo and they don't modify Claude's files. Several VS Code windows on the same project stay in sync.

Good to know

• "New chat in folder" (Claude tab mode) files the next new chat that appears in the project within 15 minutes. In terminal mode it's exact.
• Tabs Chat Shelf didn't open are recognized by their title. If you rename a chat in Claude Code itself, that tab may not show as open until you reopen it from the sidebar.
• The transcript format is internal to Claude Code and may change. Chat Shelf ignores anything it doesn't recognize.

Development

npm install
npm run check      # typecheck + unit tests + build + UI tests (headless Chromium)
npm run package    # → dist/chat-shelf.vsix

Press F5 in VS Code to launch an Extension Development Host with the extension loaded.

src/core/        Pure Node logic, no VS Code dependency
  organize.ts      Builds the request to Claude and validates its answer into a plan
  claudeCli.ts     Finds and runs the user's own Claude Code CLI (no API key)
  transcripts.ts   Reads chat metadata from JSONL transcripts
  chatIndex.ts     Finds a project's chats; reads Claude's live session status
  store.ts         Folders / titles / archive / keep state
  keep.ts          Kept copies (vault), Claude's retention period
  search.ts        Full-text search
  model.ts         Builds what the sidebar shows (status, expiry…)
src/extension/   VS Code glue: sidebar host, commands, Claude bridge, organizer, file watching
src/webview/     The sidebar UI (Preact + VS Code theme variables + codicons)
src/shared/      Message types shared by the extension and the sidebar
test/            Vitest tests (core + extension against a fake VS Code API)
test/ui/         Drives the real sidebar UI in headless Chromium, takes screenshots

Privacy & security

• No telemetry, no servers. Chat Shelf itself never connects to the internet.
• AI features use your own Claude Code. ✨ Organize and background sorting send only chat titles, the first and last message, and the branch name, through your Claude login. Background sorting is off until you say yes, and Chat Shelf asks you once.
• Your data stays local and private. Everything Chat Shelf stores is in ~/.claude-chats, readable only by your user.
• Projects can't change which program Chat Shelf runs (see SECURITY.md).

Found a security problem? Please report it privately (see SECURITY.md).

Chat Shelf is an independent open-source project. It isn't made by, affiliated with, or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

License

MIT