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

Activity Bar Sidebar

A dedicated "Claude Conductor" panel with four 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.
• Workspace Folders — shown only when a multi-root VS Code workspace is open (more than one root folder), with one row per native workspace folder. Active sessions use the same working/waiting icons as Active Sessions; click a row to launch or focus its session.

Right-click an Active Sessions or Recent Projects folder row and choose Rename... (claudeConductor.renameFolder) to assign a display alias. The alias is shown in the sidebar and quick-pick immediately and in new terminal tab titles when sessions are launched. For folders added through claudeConductor.extraFolders, choose Remove from Recent Projects (claudeConductor.removeFolder) to remove them. Active Sessions and Recent Projects also support multi-select for closing sessions or removing configured folders in bulk.

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 session
• Ctrl+Alt+[ — focus the previous Claude session

Cycles through Claude tabs only, not every terminal or editor tab.

Getting Started

1. Install the extension
2. Make sure the claude CLI is on your PATH — see Claude Code installation
3. When prompted, click Allow to install notification hooks (adds entries to ~/.claude/settings.json)
4. 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.folderAliases	{}	Display-name aliases for folders, keyed by canonical folder path
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 Session
• Claude Conductor: Launch Session in Workspace Folder...
• Claude Conductor: Add Folder
• Claude Conductor: Next Session / Previous Session
• Claude Conductor: Setup Notification Hooks
• Claude 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 checks both the recorded version path and whether the recorded hook script still exists, then safely updates stale paths on activation or the next time the window regains focus. If the running extension host itself points at a removed version, Claude Conductor asks you to reload the window before updating the hooks.

To remove the hooks at any time: run Claude Conductor: Remove Notification Hooks from the command palette.

Requirements

• VS Code 1.93 or newer
• Claude Code CLI installed and on PATH

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.

Known Limits — Recent Projects

• Configured-folder dedup: when the same path appears in both VS Code's recent folders and claudeConductor.extraFolders, Recent Projects keeps the VS Code recent-folder source during deduplication. The row therefore hides Remove from Recent Projects, even though the path also remains in extraFolders; remove it through Settings instead.

Known Limits — Rename

• Open terminal titles: renaming a folder's alias does not update terminal tabs that are already open because VS Code's Terminal.name property is read-only. The new alias appears in terminal titles the next time that folder's session is launched; existing tabs keep their old title until closed and relaunched.

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