VS Orchestrator
See every open VS Code window, remember the repositories you use, and jump to the right workspace without hunting through the taskbar.
What it does
- Lists live VS Code windows in the Secondary Side Bar.
- Saves repositories as favourites, so a closed workspace is one click away.
- Focuses an already-open workspace or opens a saved one in a new window.
- Uses colour dots and optional matching title-bar colours to make windows easy to distinguish.
- Provides a dashboard editor tab for layouts where the side bar is unavailable.
- Exposes Copilot agent-mode tools to list, open, colour, and show workspaces.
Everything runs locally. The extension has no runtime dependencies and does not download anything.
Install
Install from VS Code Market place
Alternatively, run Developer: Install Extension from Location... from the Command Palette and select this folder. For development, open the project in VS Code and press F5 to start an Extension Development Host.
Use
- Select the VS Orchestrator icon in the Activity Bar.
- In Open Windows, select another workspace to focus it without creating a chat. Select the current window to reuse an empty chat editor, or open a new one if none is empty. Use the pin action to save a workspace.
- In Saved Repos, select an open repo to focus it or a closed repo to open it in a new window.
- Dots follow each open window's configured
titleBar.activeBackground, including theme-specific colour customizations. Otherwise they use the colour chosen through Orchestrator, or white. Use the colour action to choose a palette or custom hex colour; Default clears that choice without overriding existing repository settings.
Use VS Orchestrator: Open Orchestration Mode, its view-title button, or Ctrl+Alt+O to restore orchestration mode: the side bars in the current profile's preferred position and optionally the integrated terminal in the bottom panel. First entry initializes Copilot Chat in Agent mode as an editor (or reuses an existing chat editor). Repeating the command preserves chats, including leaving a deliberately closed chat closed. If the editor-based Chat command is unavailable, initial setup falls back to normal Copilot Chat.
With VS Code 1.95 or later and Copilot Chat available, agents can use:
| Reference |
Action |
#orchestratorList |
List open windows and saved repos. |
#orchestratorOpen |
Focus an existing workspace or open a saved one. |
#orchestratorColour |
Set a palette/custom colour or restore the default. |
#orchestratorPanel |
Reveal the VS Orchestrator panel/dashboard. |
Settings
| Setting |
Default |
Description |
vsOrchestrator.colorizeTitleBar |
true |
Apply the selected workspace colour to its title bar. |
vsOrchestrator.autoRevealOnFocus |
true |
Reveal VS Orchestrator after focusing or opening a workspace from the extension. |
vsOrchestrator.openInOrchestrationMode |
true |
Open every window in orchestration mode. When off, activate it with the button, command, or hotkey. Panel-opened windows always use orchestration mode. |
vsOrchestrator.openTerminalInOrchestrationMode |
true |
Open the integrated terminal panel when entering orchestration mode. Off leaves its current visibility unchanged. |
The settings button opens the extension's settings editor, which also provides Export and Import actions for saved repositories. Imports merge by normalized repository path and do not remove existing entries. Chat placement follows the active VS Code profile's workbench.sideBar.location setting.
How it works
VS Code does not provide an API for one extension instance to inspect every other window. VS Orchestrator solves this locally: each open window writes a small heartbeat record to VS Code's shared extension storage. Other windows read those records to build the panel, and stale records are cleaned up automatically.
Chat-log events are processed within a 200 ms refresh window, and incoming window records within 100 ms, without continuous activity postponing either refresh. A one-second poll in every window recovers missed file events, including newly started chats. Log replay reads only appended bytes after the initial scan; unchanged panel data does not trigger a redraw. These timings start when VS Code writes its data, not when an action occurs in Chat.
Session status describes the latest prompt, not the lifetime of the conversation:
| Status |
Meaning |
| Running |
Recent transcript activity with no recorded prompt outcome. This is inferred, not proof that no native approval is pending. |
| Needs input |
An explicitly unresolved persisted question, confirmation, elicitation, or plan review. An unfinished tool alone is not an input request. |
| Complete |
The agent completed the latest prompt with a recorded non-error result. Another prompt can continue the conversation. |
| Errored |
A request-level error was recorded. A failed individual tool that the agent can recover from does not mark the whole prompt as errored. |
| Cancelled |
An explicit cancellation flag or cancellation result was recorded. This is not successful completion. |
| Unknown |
A running prompt has no response progress for two minutes, the log is damaged, or the status is unsupported. The agent may be working, waiting, or interrupted. Silence never becomes completion or a confirmed input request. |
Completions observed while the window is inactive have a separate unread marker. Focusing that window clears the marker, not the Complete outcome. A new prompt resets the previous prompt's outcome. Input requests, errors, and unknown states take priority over completed history. Restore size limits do not change the prompt outcome.
Saved repos and colour choices are stored per user in VS Code extension storage. No administrator permissions, native modules, or external services are required.
Optional Local hook probe
The probe is off by default and diagnostic only. It does not drive the status display, grant permissions, block tools, or inject prompts. Enable it through VS Orchestrator: Enable Local Session Hook Probe (This Profile), run a new prompt with the Local session target, and inspect VS Orchestrator: Open Session Hook Probe Log. Disable it with VS Orchestrator: Disable Local Session Hook Probe (This Profile).
It adds only its own entry to the active profile's chat.hookFilesLocations, preserving other hook locations. It requires a trusted local desktop workspace, Local hook support, and chat.useHooks; it never changes trust or enables hooks against existing policy. Remote windows and other agent harnesses are not supported by this probe. It uses VS Code's bundled Node runtime, with PowerShell on Windows, and copies its recorder into extension storage when enabled. Re-enable after an extension update to refresh that copy.
The recorder stores only supported event names, timestamps, session IDs, tool names/call IDs, subagent IDs, and stop-hook continuation flags. It omits prompts, tool arguments/results, working directories, and transcript contents/paths. Input is capped at 1 MiB; recording stops when the diagnostic log reaches approximately 5 MiB. Disabling keeps existing records; disable the probe before deleting the log to reset it. Events without a session ID cannot establish session correlation.
Live verification must cover submission, a long tool, a question and its answer, an approval and its resolution, natural completion, a request error, cancellation, and reload. Local Stop is a pre-stop event that another hook can block; it is not authoritative completion. Local hooks do not expose all approval/error events. Copilot CLI/Agent Host hook coverage requires separate validation before integrating it. See the Local hook reference.
Limitations
- Window discovery refreshes on a short heartbeat, so a closed window can appear for up to about 15 seconds.
- If the same folder is open in multiple windows, VS Code decides which matching window receives focus.
- Empty windows are listed but cannot be focused by folder path.
- Chat status still depends on VS Code flushing its private session log; unsaved native approvals and arbitrary terminal input cannot be detected exactly. A question written only in prose has no structured input signal. Synthetic persisted
modelState cancellation is deliberately ignored because VS Code can write it for a still-running prompt. Abrupt crashes without an explicit outcome remain unknown, not successful. Window heartbeat liveness is separate from prompt outcome. Reload all windows after installing an updated extension so they all publish the new status behavior; legacy done/stalled values display as unknown.
- Title-bar colours are written to workspace settings and depend on VS Code using a custom title bar. A repository that already has
.vscode/settings.json is left unchanged and its settings take precedence.
- Each window publishes its configured title-bar colour to the other windows. After updating the extension, reload all open windows to enable this. Detection supports
#RGB and #RRGGBB in workbench.colorCustomizations; colours defined only inside theme files are not detected.
Tests
Run node --test for the color, window-navigation, session-parser, status-presentation, refresh-timing, and hook-probe regression tests. No npm dependencies or running VS Code instance are required. Windows probe-command tests also use the built-in Windows PowerShell executable. Tests exercise hook input and command wiring, not live Copilot event delivery.
