A utility to repair corrupted chat session indices in VS Code workspace storage databases (state.vscdb).

Problem: VS Code chat sessions become invisible due to index corruption in state.vscdb, even though session data files remain intact on disk. Solution: vscdb-fix scans session files and rebuilds the database index to restore visibility of all chat sessions.

---

🚧 Project Status

This project is no longer actively developed. It works as-is for its current feature set, but I'm no longer using GitHub Copilot or VS Code Chat. Without daily use, I can't reliably test new scenarios or reproduce regressions.

If you need this project to stay active, consider sponsoring. Funding is the only path that would get me back into active development — I have several other projects competing for my time right now. Sponsorship would fund:

• Investigating and fixing upstream VS Code issues (like #15 — session repairs reverted on shutdown)
• Packaging as a VS Code extension for in-editor use
• Adding --watch mode for proactive corruption detection
• Supporting empty-window sessions (globalStorageHome/emptyWindowChatSessions/)

Want to help without sponsoring? Open an issue describing your use case. If enough users signal need, that's signal too.

---

⚠️ Known Limitations

VS Code 25-session cap (Issue #15)

VS Code's ChatSessionStore hard-caps the index at 25 persisted sessions (maxPersistedSessions = 25). On shutdown, it trims any entries beyond 25. This means:

• Restoring 33 sessions works immediately, but VS Code deletes 8 on next shutdown
• The in-memory cache is never invalidated from external writes — our fixes get overwritten
• This is upstream VS Code behavior, not a vscdb-fix bug

Workaround: The tool is effective for recovery after crashes (where the index desyncs from files) but does not persist more than 25 sessions across VS Code restarts.

Multi-window race condition

If two VS Code windows are open on the same workspace, each maintains its own in-memory index cache. The last window to shut down wins, potentially overwriting the other's index.

---

🚀 Quick Start

Install as a CLI tool:

pip install .
vscdb-fix              # preview (dry-run by default)
vscdb-fix --apply      # actually fix (close VS Code first!)
vscdb-fix --apply --yes

Or run directly without installing:

python3 vscdb_fix.py

---

📋 Usage — all commands

# List workspaces that need repair
vscdb-fix --list

# List all workspaces (including healthy)
vscdb-fix --list --show-all

# Fix a specific workspace
vscdb-fix --apply <workspace_id>

# Recover orphaned sessions from other workspaces
vscdb-fix --apply --recover-orphans

# Remove orphaned index entries
vscdb-fix --apply --remove-orphans

# Remove empty (no-request) sessions
vscdb-fix --apply --remove-empty

# Merge duplicate workspace folders (machine migration)
vscdb-fix --apply --merge

# Combine flags
vscdb-fix --apply --recover-orphans --yes
vscdb-fix --apply --merge --insiders --yes

🔍 Cross-Workspace Orphan Detection

When the tool detects orphaned sessions (entries in the index but no file on disk), it automatically checks all other workspaces to see if the session file exists elsewhere.

Project Folder Matching: The tool intelligently detects if an orphaned session belongs to the same project by comparing folder names.

# Orphan from a different project:
🗑️  Orphaned in index: 2
   💡 Session abc12345... found in workspace a1b2c3d4 (/home/user/other-project)

# Orphan from the SAME project (highlighted):
🗑️  Orphaned in index: 2
   💡 Session def67890... found in workspace e5f6g7h8 (file:///home/user/workspace/my-app)
      ⭐ Same project folder: 'my-app' - likely belongs here!

Recover automatically: vscdb-fix --recover-orphans

Or manually:

cp ~/.config/Code/User/workspaceStorage/<source>/chatSessions/<session-id>.json \
   ~/.config/Code/User/workspaceStorage/<target>/chatSessions/
vscdb-fix <target>

⚙️ Technical Overview

Storage Architecture

~/.config/Code/User/workspaceStorage/<workspace-id>/
├── state.vscdb                    # SQLite database
│   ├── chat.ChatSessionStore.index  # Index of all sessions
│   ├── agentSessions.model.cache    # Agent panel session list
│   └── agentSessions.state.cache    # Agent panel read/archive state
└── chatSessions/
    ├── session-1.json             # Legacy full JSON format
    ├── session-2.jsonl            # Newer JSONL mutation log format
    └── session-3.json

• .json — Legacy format: full conversation as a single JSON object
• .jsonl — Newer format: mutation log with kind:0 (initial state), kind:1 (set mutation), kind:2 (array splice/push)

Root Cause

The index in state.vscdb can become corrupted or out of sync with actual session files. Example: 13 session files on disk, 1 index entry, 1 visible session.

Repair Process

1. Scans chatSessions/ directory for all session JSON/JSONL files
2. Extracts metadata from each session file
3. Rebuilds chat.ChatSessionStore.index in state.vscdb
4. Creates timestamped backup before modifications

🔄 Machine Migration

When transferring VS Code workspace storage between machines, VS Code may create new workspace storage folders with different hashes — even for the same workspace URI.

# Preview what would be merged
vscdb-fix --merge --dry-run

# Apply the merge (close VS Code first!)
vscdb-fix --merge --yes

This will:

1. Find workspace URIs with multiple storage folders
2. Identify the active (newest) folder for each
3. Copy missing session files from old folders into the active one
4. Update all three database keys

🛠️ Troubleshooting

No workspaces found

• Verify VS Code Chat has been used previously
• Confirm ~/.config/Code/User/workspaceStorage/ exists (Linux/macOS) or %APPDATA%\Code\User\workspaceStorage\ (Windows)

Sessions not restored after repair

• Confirm VS Code was completely closed before running the script
• Reload VS Code window: Ctrl+Shift+P -> "Reload Window"
• If migrated from another machine, try --merge first
• If sessions disappear after restart, see Issue #15

Rollback

cp state.vscdb.backup.<timestamp> state.vscdb

---

❓ FAQ

Can sessions be transferred between workspaces?

Yes. Session files are standard JSON or JSONL. Copy files between workspace chatSessions/ directories, then run the repair script to update the index.

Does this work with VS Code Insiders?

Yes. Add the --insiders flag to any command, e.g., vscdb-fix --insiders --dry-run.

Does this tool delete any data?

No. Only the database index is modified. Session data files are read-only operations.

What are orphaned index entries?

Index references to non-existent session files. Retained by default for safety. Use --remove-orphans to clean up.

Why do my restored sessions disappear after restarting VS Code?

See Issue #15. VS Code caps the index at 25 sessions and overwrites external fixes with its stale in-memory cache on shutdown.

---

🔝 Upstream Issue

This is a VS Code core bug, not a GitHub Copilot extension issue. The Copilot extension manages only specialized sessions — regular chat session restoration is handled by VS Code's core chat service.

• File issues: https://github.com/microsoft/vscode/issues

🤝 Contributing

Bug reports and improvements welcome via issues or pull requests.

If you'd like to see active development on this project, consider sponsoring — it's the most direct way to fund the time needed for upstream investigation and VS Code extension development.

📄 License

MIT