Claude Conductor
Orchestrate multiple Claude Code sessions across different projects as editor tabs in a single VS Code window.
Why
Running Claude Code against several projects at once is painful in a plain terminal. This extension turns each session into a first-class editor tab with a persistent sidebar, quick-pick launcher, and idle notifications — so you can work across multiple codebases without losing track of which session needs your attention.
Features
A dedicated "Claude Conductor" panel with three sections:
- Active Sessions — currently running Claude terminals. Sessions are grouped by project root; click a project row to expand it and see its sessions. Click a session leaf to focus it. A green terminal icon means the session is working; an orange bell means it's waiting for your input.
- Favorites — a curated list of project roots you've pinned for quick access. Sits between Active Sessions and Recent Projects.
- Recent Projects — your VS Code recently opened folders plus any configured extras, grouped by project root. Click a project row to expand it and see its worktrees. Click a folder leaf to launch a new session.
Favorites
A curated list of project roots you've pinned for quick access. Sits between Active Sessions and Recent Projects.
- Add a favorite: hover a project row in Recent Projects or right-click and choose Add to Favorites. The row shows a filled star icon when favorited.
- Remove a favorite: hover a favorited row and click the filled star, or right-click → Remove from Favorites.
- Relocate a favorite: if a favorited folder is missing on disk, the row dims and shows
(missing). Click the row, press Enter, or right-click → Locate Folder... to point the favorite at the folder's new location.
- Capacity: soft cap of 25 favorites. Adding a 26th is rejected with a toast. If storage drift produces more than 25 entries, the panel shows a banner above the tree and renders all entries (no silent truncation).
- Persistence: per-machine via VS Code's
globalState. Favorites do not sync between machines (intentional — see Known Limits).
Recent Projects renders as a two-level tree: project roots are collapsed by default (showing a child count), with their .worktrees/<branch> subdirectories nested underneath. When a worktree's parent project root is not present in Recent Projects, the group row is shown with a dimmed folder icon and a "(not in recents)" label so you can tell at a glance that the root itself isn't tracked. Favorites, by contrast, renders as a flat, single-level list — each favorited project root is its own row with no nested children, since only project roots (not worktrees) can be favorited.
Quick-Pick Launcher
Press Ctrl+Shift+Alt+C (Mac: Cmd+Shift+Alt+C) to bring up a searchable list of projects. Active sessions appear first — selecting one focuses the tab. Selecting a folder launches a new session there.
Terminal-as-Editor-Tab
Each Claude session opens in the editor area (not the bottom terminal panel), so you can tile them, pin them, and glance at multiple sessions at once like you would with code files.
Idle Notifications
When Claude finishes work and is waiting for your next prompt, you get:
- A bell icon next to the session in the sidebar
- A VS Code notification with a "Focus" button that jumps to that session's tab
If multiple sessions are waiting simultaneously, you get a single consolidated notification that opens a quick-pick to choose which to focus.
Powered by Claude Code hooks — the extension offers to install the hooks on first activation.
Open in New Window (Deep Work)
Each active session has an "Open in New Window" button that launches a dedicated VS Code window scoped to that project, with Claude auto-starting. Good for focused deep-work sessions when you want the rest of VS Code out of the way.
If the session's folder is already the current workspace, clicking the button will show a brief notification and focus the existing session tab instead of opening a redundant window.
Terminal Link Provider
File paths in Claude's terminal output are clickable — open them directly in the editor without copy-pasting.
Keyboard Navigation
Ctrl+Alt+] — focus the next Claude sessionCtrl+Alt+[ — focus the previous Claude session
Cycles through Claude tabs only, not every terminal or editor tab.
Getting Started
- Install the extension
- Make sure the
claude CLI is on your PATH — see Claude Code installation
- When prompted, click Allow to install notification hooks (adds entries to
~/.claude/settings.json)
- Press
Ctrl+Shift+Alt+C and pick a folder to launch your first session
Configuration
| Setting |
Default |
Description |
claudeConductor.claudeCommand |
"claude" |
CLI command to run in the terminal |
claudeConductor.reuseExistingTerminal |
true |
Focus an existing session tab instead of opening a duplicate |
claudeConductor.enableNotifications |
true |
Show notifications when a session is waiting for input |
claudeConductor.extraFolders |
[] |
Additional folder paths to show in the launcher |
claudeConductor.debugLogging |
false |
Enable verbose diagnostic logging for session lifecycle (see Debug logging below) |
Debug logging
Set claudeConductor.debugLogging to true to enable verbose diagnostic output for session lifecycle events including close-detection. All output appears in the "Claude Conductor" output channel (open it via View → Output, then select "Claude Conductor" from the dropdown).
When enabled, the extension logs structured key=value lines for every terminal-open, terminal-close (including which of the three fallback tiers matched), reconcile poll tick, and PID index write/delete. This is useful for diagnosing missed editor-tab close events (tracked in #68).
This setting is off by default and has no effect on normal operation. Disable it after capturing the logs you need.
Commands
Available from the command palette (Ctrl+Shift+P):
Claude Conductor: Launch SessionClaude Conductor: Add FolderClaude Conductor: Next Session / Previous SessionClaude Conductor: Setup Notification HooksClaude Conductor: Remove Notification Hooks
How Idle Detection Works
When you allow notification hooks, the extension adds three entries to your ~/.claude/settings.json:
| Hook |
Fires when |
Effect |
Notification + idle_prompt |
Claude has been waiting for input ~60s |
Marks session idle, shows notification, bell icon |
UserPromptSubmit |
You submit a prompt |
Marks session active, clears notification |
Stop |
Session ends |
Cleans up state file |
The hooks write state files to ~/.claude/session-state/ which the extension watches. Only your VS Code extension reads these files — no data leaves your machine.
After an extension update, VS Code installs the new version to a different directory, which would normally leave the hook commands pointing at the old path. Claude Conductor detects this automatically on activation and silently updates the paths in ~/.claude/settings.json — no user action required.
To remove the hooks at any time: run Claude Conductor: Remove Notification Hooks from the command palette.
Requirements
Known Limitations
- Session tracking only works within a single VS Code window (sessions in other windows aren't visible in the sidebar)
- The idle notification fires after Claude Code's built-in ~60-second idle threshold — not tunable from the extension
- VS Code terminal tabs cannot change color or flash after creation, so "attention" is communicated via sidebar bell icons and notifications rather than tab-level indicators
Known Limits — Favorites
- Favorites paths are tracked as you typed them. Two distinct path strings that resolve to the same folder via symlinks or junctions produce duplicate entries.
- UNC shares (
\\server\share): these render as present in the panel until you actually launch a session. If the share is offline, the launch will fail and the row will dim afterward. The next successful launch flips it back to present.
- Multi-window writes: if you mutate Favorites in two VS Code windows simultaneously, the last write wins. The normal cap is 25 entries, but storage drift can exceed it, and mutation rate is low, so collisions are unlikely in practice. Settings Sync is intentionally not enabled.
Contributing / Development
Testing
The project uses Vitest for unit tests. Tests run against a minimal vscode module mock so no VS Code instance is required.
npm install # install dependencies
npm test # run tests once (CI mode)
npm run test:watch # run tests in watch mode during development
CI runs lint, typecheck, tests, and compile automatically on every pull request and push to main via GitHub Actions.
Current scope is unit tests only. Integration tests via @vscode/test-electron are deferred to a future milestone.
Specs — behaviour changes are spec-driven: a written spec lands and is reviewed before implementation. See CLAUDE.md for when a spec is required and docs/sdd-workflow.md for the document templates.
Releases — this extension follows the VS Code marketplace odd/even minor convention for stable vs pre-release channels. See docs/release-strategy.md.
Source
github.com/cbeaulieu-gt/vscode-claude-conductor
License
MIT
