WSL-Windows Config

Cursor cannot edit Windows (D:\) and WSL (/home/ta/) source trees in one reliable multi-root workspace. Use two workspace files in two Cursor windows (same app — not mixed UNC paths).

Quick reference

I want to…	Do this
Edit KB or backup scripts	Windows workspace
Edit monorepo / Linux projects	WSL workspace
Use Claude Code in a workspace project + see its files	Right-click on Workspace root, in Cursor’s Explorer left sidebar → Open in Integrated Terminal → `claude`
Move CC terminal to a second monitor	Move Terminal into Editor Area → Move into New Window → drag to monitor 2; `Ctrl+J` hides panel on main display
Run bash/git against `D:\FSS`	WSL terminal inside Windows workspace; paths `/mnt/d/FSS/...`
Open a single Linux repo only	`cd ~/projects/monorepo && cursor .` (still WSL remote)

IDE Setup

Architecture

Window	Workspace file	Filesystem	Status bar
Windows	`D:\FSS\fss-windows.code-workspace`	Native `D:\`	No WSL badge
Linux	`/home/ta/linux-wsl.code-workspace`	Native WSL ext4	WSL: Ubuntu-24.04

Do not open WSL folders via \\wsl$\Ubuntu-24.04\... in a Windows workspace. That triggers the slow/broken UNC bridge and the startup warning dialog.

WSL extension does not auto-connect. It is installed, but remote mode starts only when you open a workspace from WSL (or run WSL: Connect to WSL). There is no setting to connect WSL automatically while editing D:\FSS.

Hybrid that already works: In the Windows window, the integrated terminal defaults to WSL (Ubuntu-Cursor (WSL)). You can run Linux commands against Windows files via /mnt/d/FSS/... without putting WSL projects on UNC paths.

Workspace contents

Windows — fss-windows.code-workspace

KB — Tasks (KB/Core/_WorkingOn)
KB — MBR
KB — Core
KB — Root
Backup Util (Software/Utils/PythonUtils/my_backup)

WSL — linux-wsl.code-workspace (lives in /home/ta/, not on D:\)

Monorepo
MBR (Linux)
Asset History
Utils — AI, Shell, System, Web

Open each workspace

Windows workspace — from PowerShell, Run dialog, or double-click D:\FSS\open-windows-workspace.bat:

cursor D:\FSS\fss-windows.code-workspace

WSL workspace — from Windows (desktop shortcut or batch file; opens WSL remote directly):

cursor -n --remote wsl+Ubuntu-24.04 /home/ta/linux-wsl.code-workspace

Or double-click D:\FSS\open-linux-workspace.bat / Cursor - WSL (Linux) on the desktop.

Do not use wsl.exe ... cursor ~/linux-wsl.code-workspace from a Windows shortcut — that opens the Windows welcome screen and leaves you to pick the workspace from Recents manually.

From Ubuntu terminal (inside WSL, this path is correct):

cursor ~/linux-wsl.code-workspace

Fallback from an already-open Windows Cursor window:

Ctrl+Shift+P → WSL: Connect to WSL (or WSL: Connect to WSL using Distro… → Ubuntu-24.04)
File → Open Workspace from File… → /home/ta/linux-wsl.code-workspace

Confirm bottom-left shows WSL: Ubuntu-24.04 before doing Linux project work.

Change or edit a workspace

Add/remove Windows folders

Open D:\FSS\fss-windows.code-workspace in Cursor (Windows window).
File → Add Folder to Workspace… or right-click a root in Explorer → Remove.
File → Save Workspace As… (overwrite fss-windows.code-workspace) — or edit the JSON directly. Use paths relative to D:\FSS (e.g. KB/Core) or absolute D:\... paths.

Add/remove WSL folders

Open WSL workspace from Ubuntu: cursor ~/linux-wsl.code-workspace.
Add/remove folders the same way; save workspace.
Edit JSON with paths relative to /home/ta/ (e.g. projects/monorepo). Never use \\wsl$\... in this file.

Switch workspace in current window

File → Open Workspace from File… and pick the other .code-workspace file.
Prefer File → New Window first (window.openFoldersInNewWindow: on) so you keep both contexts open.

Cursor user settings (recommended)

In File → Preferences → Settings → Open Settings (JSON):

"window.restoreWindows": "all",
"window.openFoldersInNewWindow": "on"

"all" — reopen both Windows and WSL windows after restart (if both were open when you quit).
"on" — opening the second workspace does not replace the first.

Session restore expectations

With window.restoreWindows: "all", a normal quit (File → Exit, or close the last window) should restore each window that was still open when you quit:

Workspace folders (multi-root roots in each .code-workspace)
Open editor tabs and cursor position in those files

Both windows must be open when you quit for both to come back. If you close only the WSL window and leave the Windows window running, only the Windows session is saved for next time.

Window	Restore on restart?
Windows (`fss-windows`)	Usually reliable
WSL (`linux-wsl`)	Less reliable — WSL remote must reconnect; use the desktop shortcut or `open-linux-workspace.bat` if it does not return

Normal quit vs. abnormal exit: force-kill or a crash may lose unsaved work and give partial or no restore.

Two windows, one app: restore brings back separate windows (Windows vs WSL context), not two independent Cursor installs.

Checklist to switch over

Close any workspace still using dev.code-workspace or \\wsl$\... paths.
Open Windows workspace: cursor D:\FSS\fss-windows.code-workspace (or run open-windows-workspace.bat).
In Ubuntu: cursor ~/linux-wsl.code-workspace.
Verify WSL window status bar: WSL: Ubuntu-24.04.
Verify Windows window status bar: no WSL badge.
Add window.restoreWindows and window.openFoldersInNewWindow to user settings (above).
Stop using deleted dev.code-workspace (mixed OS — removed).
Desktop shortcuts: Cursor - Windows (FSS).lnk, Cursor - WSL (Linux).lnk (see Launcher files).

Verify WSL CLI

From Ubuntu:

which cursor

If missing: in Windows Cursor, Ctrl+Shift+P → Shell Command: Install ‘cursor’ command in PATH (install in WSL if offered), then retry.

Default distro (if needed):

wsl --set-default Ubuntu-24.04

Other notes for reliability

Daily routine

Start Windows workspace (often auto-restores).
Start WSL window: desktop shortcut Cursor - WSL (Linux) or open-linux-workspace.bat (uses --remote wsl+...).
Use Alt+Tab between two Cursor windows — same process, correct remote context per window.

Claude Code + Explorer sync (WSL window)

Goal: Claude Code in the terminal and the Explorer sidebar show the same project.

Why tmux broke this: Auto-tmux in .bashrc hijacked every Cursor terminal into the shared work session with pre-set cd paths — independent of which workspace root you clicked in Explorer.

Fix (in place):

Cursor integrated terminals skip auto-tmux (TERM_PROGRAM=vscode check in .bashrc).
Each workspace root has .vscode/settings.json with terminal.integrated.cwd: "${workspaceFolder}".

Do not use ${fileWorkspaceFolder} at workspace level — it requires a file open in the editor and errors with “Variable ${fileWorkspaceFolder} can not be resolved” when only Explorer is focused.

Workflow — switch CC project and see matching files:

Method A (fastest — no file needs to be open):

In Explorer, right-click the workspace root (e.g. Utils — AI).
Open in Integrated Terminal.
Run claude — terminal cwd and Explorer tree both match that root.

Method B (keyboard-first):

Open any file from the target root (e.g. pyproject.toml under Utils — AI).
Terminal → New Terminal (Ctrl+Shift+`` ) — cwd follows the open file’s workspace root.
Run claude.

Method C (no file open, keyboard only):

Terminal → New Terminal (Ctrl+Shift+`` ).
Pick the project from the “Select current working directory” picker (multi-root default).
Run claude.

Switch projects: repeat with a new terminal tab (or kill the old CC session first).

tmux still available in Windows Terminal and other external shells (not inside Cursor).

KB / Windows-path CC work (e.g. /mnt/d/FSS/KB/...): use the Windows workspace window with a WSL bash terminal (not PowerShell). Right-click workspace root → Open in Integrated Terminal should open Ubuntu-Cursor (WSL) at /mnt/d/FSS/KB/... → claude.

Second monitor for Claude Code terminal

Goal: Main display = Explorer (left) + open files (center) + Agents (right). Second display = CC terminal only.

Detach integrated terminal to another monitor:

Right-click the wsl terminal tab (bottom panel) → Move Terminal into Editor Area
(or Ctrl+Shift+P → Terminal: Move Terminal into Editor Area).
Right-click the terminal tab in the editor area → Move into New Window
(or drag the tab off the Cursor window onto the second monitor).
Maximize/resize on monitor 2. On the main window, hide the bottom panel: Ctrl+J.

Optional setting (new terminals start as editor tabs — easier to detach):

"terminal.integrated.defaultLocation": "editor"

Alternative: Run CC in Windows Terminal on monitor 2 (wsl -d Ubuntu-24.04, cd to project, claude). Same WSL environment; Explorer sync is manual.

Detached terminal windows may not restore on restart — repeat detach or leave the second window open when quitting (window.restoreWindows: all).

Avoid

One multi-root workspace mixing D:\ and \\wsl$\....
Opening linux-wsl.code-workspace by browsing \\wsl$\ in Windows Explorer.
Maintaining the same repo in both D:\FSS\KB\MBR and ~/projects/mbr without a deliberate sync strategy.

Cross-boundary paths

Windows path	WSL equivalent
`D:\FSS`	`/mnt/d/FSS`
`D:\FSS\KB`	`/mnt/d/FSS/KB`

Troubleshooting

Symptom	Fix
WSL warning on startup	A folder is still on `\\wsl$\...`; use split workspaces only.
Slow save / watch / git in Linux project	Not in WSL remote — reconnect via `cursor ~/linux-wsl.code-workspace`.
Wrong Python/node version	Check status bar context; extensions run in the window’s remote (Windows vs WSL).
`cursor` not found in WSL	Install shell command from Cursor command palette (see above).
Terminal opens pwsh instead of bash for KB	Default profile missing — use Ubuntu-Cursor (WSL) from terminal dropdown; profile is defined in user `settings.json`.
Ubuntu-24.04 (WSL) fails (`bash.exe -d` exit code 2)	Auto-detected profile is broken — pick Ubuntu-Cursor (WSL) instead (uses `wsl.exe -d Ubuntu-24.04`). Reload window after settings change.

Launcher files

Windows: D:\FSS\open-windows-workspace.bat
WSL (from Windows): D:\FSS\open-linux-workspace.bat
WSL (from Ubuntu): ~/open-linux-workspace.sh (optional alias in ~/.bashrc)
Desktop shortcuts: C:\Users\Admin\Desktop\Cursor - Windows (FSS).lnk, Cursor - WSL (Linux).lnk

alias cursor-win='cursor.exe D:/FSS/fss-windows.code-workspace'
alias cursor-linux='cursor ~/linux-wsl.code-workspace'