VS Code extension

When a Claude Code session runs in VS Code’s integrated terminal, Hoku can bring VS Code forward, but on its own it can’t tell VS Code which window and terminal tab hold the session. The optional Hoku extension for VS Code fills that gap. With it installed, Go to terminal brings that exact window to the front and shows the session’s terminal.

It’s optional. Without it, Go to terminal still brings VS Code forward and you pick the tab, as before.

What it does

• Each VS Code window tells Hoku the process numbers of its open terminals.
• When you click Go to terminal, Hoku asks the window that holds the session to show its terminal and come forward, and waits for the window to confirm it did.
• Hoku says Switched to this session’s terminal in VS Code only when that window confirms, for that click, that it showed the terminal and came forward on your current desktop. Otherwise it brings VS Code forward and tells you it couldn’t select the window and terminal. See When it can’t.

It works in every window and project once installed. There’s no setup per project.

Install

The extension comes inside Hoku. It isn’t on the VS Code Marketplace or Open VSX, and installing it doesn’t download anything.

1. The first time you click Go to terminal for a live Claude Code session in VS Code without setup, Hoku offers the extension before switching apps. You can choose Continue to VS Code to skip setup. The same sheet is always available from Integrations → VS Code extension → Set up.
2. Click Install in VS Code (or Install in VS Code Insiders). Hoku runs VS Code’s own code --install-extension with the copy bundled in Hoku.
3. If VS Code was already open, reload its windows (Developer: Reload Window in the Command Palette, or quit and reopen VS Code). The sheet shows Connected to N windows once they report in.
4. Click Allow link in VS Code. While Hoku says Waiting for approval, go to your VS Code window, choose Open in its prompt, then return to Hoku.

To install by hand instead, run Extensions: Install from VSIX… in VS Code and pick Hoku.app/Contents/Resources/vscode/hoku-vscode.vsix (in Finder, right-click Hoku.app → Show Package Contents).

VS Code installs extensions per profile. If you use several VS Code profiles, install it in each profile whose terminals you want Hoku to reach.

When a Hoku update ships a newer extension, the sheet says Update available and the button reads Update.

The one-time VS Code prompt

The first time Hoku asks VS Code to show a terminal, VS Code asks:

Allow ‘Hoku’ extension to open this URI?

Choose Open, and tick Do not ask me again so it doesn’t ask on every click. This is VS Code’s own question, and it’s asked once per profile. Hoku never changes VS Code’s settings to skip it.

Allow link in VS Code in the setup sheet brings VS Code forward and asks this question in the front window. Hoku tells you to check VS Code while it waits. When it says Connected, you can return to Hoku and open the session. Hoku can’t tell whether you ticked Do not ask me again, so if VS Code asks again later, tick it then. If you skip that step, Hoku offers Finish VS Code setup after an unconfirmed attempt.

What it shares, and what it never reads

The extension and Hoku talk only through a private folder on your Mac:

~/Library/Application Support/com.hoku.app/vscode-bridge/

It’s readable only by you (folders 0700, files 0600), and holds:

• one small file per VS Code window, with the process numbers of its open terminals, the VS Code window number, the VS Code and extension versions and timestamps. It’s removed when the window closes.
• one request per click, written by Hoku, and one reply, written by the extension, with status words like shown and timestamps. They live a few seconds and Hoku deletes them. Anything older than a minute is cleaned up the next time Hoku goes to a VS Code terminal, checks the extension, or runs the setup step.

Never read or shared: terminal contents or output, terminal names, file names, workspace or folder paths, working directories, your VS Code settings. The extension never types into a terminal and never runs commands.

Nothing from this folder goes into Hoku’s index, and nothing leaves your Mac: neither Hoku nor the extension makes network requests. See How Hoku handles your data.

What’s supported

• Supported: VS Code and VS Code Insiders on macOS, in local windows, for Claude Code sessions running in an integrated terminal. That includes claude agents dashboards and claude attach tabs in a VS Code terminal.
• Not supported:
  • Remote windows: SSH, dev containers, WSL and Codespaces. Their terminals run on another machine.
  • VS Code forks: Cursor, VSCodium, Windsurf and others.
  • Sessions in the Claude Code extension’s panel, rather than in a terminal. Go to terminal brings VS Code forward, as before.
  • tmux inside a VS Code terminal. Hoku still can’t switch to tmux.
  • Two copies of VS Code of the same kind running at once, for example one started with a custom --user-data-dir. Hoku can’t tell which copy to ask, so it doesn’t guess.
• Known limit: if macOS is set not to switch desktops when you switch apps, Hoku can only check that some VS Code window is on the current desktop, not the session’s own window.

When it can’t

Go to terminal always brings VS Code forward. When it can’t select the session’s window and terminal, it says so instead of claiming it did:

Hoku says…	What to do
Switched to this session’s terminal in VS Code	Nothing: you’re there.
Switched to VS Code, where this session is running. Hoku couldn’t select its window and terminal.	The extension isn’t installed, or no VS Code window is reporting. Install it, or reload VS Code’s windows.
Switched to VS Code, but it didn’t confirm the session’s window. VS Code may be asking whether to allow the Hoku extension to open a link: choose Open, then click Go to terminal again.	Look for VS Code’s question, choose Open and tick Do not ask me again, then click again. Finish VS Code setup asks it in the front window.
Switched to VS Code, but it didn’t confirm the session’s window and terminal. Pick it there.	VS Code didn’t answer in time. It may still be asking whether to allow the link: Finish VS Code setup checks. Otherwise pick the terminal yourself, and if it keeps happening, reload that VS Code window.
Switched to VS Code, but Hoku couldn’t send the request to select the session’s window and terminal. Pick it there.	Hoku couldn’t write its request or open VS Code’s link. Pick the terminal yourself.
Selected the session’s terminal in VS Code, but couldn’t confirm its window came forward.	The terminal is selected, but the window may be behind another one. Bring it forward yourself.
The session is in VS Code on another desktop	The window is on another desktop (Space). See Another desktop.
Switched to VS Code, but the session’s window didn’t have its terminal any more. Pick it there.	The terminal or window closed or reloaded since Hoku last heard from it. Pick it in VS Code.
Switched to VS Code, but the request reached the window too late. …	VS Code was busy. Click Go to terminal again, or pick the terminal yourself.
Switched to VS Code, but a different window answered than the one holding the session. …	The window was reloaded or replaced. Pick the terminal yourself.
Switched to VS Code. The session’s window is a remote window, where Hoku can’t select terminals. …	Remote windows aren’t supported. Pick the terminal yourself.
A newer Go to terminal click took over this VS Code window.	You clicked again before VS Code answered. The newer click decides where you land.
Switched to VS Code. This session’s window isn’t reporting to Hoku (reload it, or check the Hoku extension is installed in that VS Code profile).	The window uses a profile without the extension, is a remote window, or hasn’t been reloaded since you installed it.
Switched to VS Code. Hoku couldn’t tell which window holds this session, so it didn’t pick one.	Two copies of VS Code are running, or more than one window claims the terminal. Pick it there.

In VS Code Insiders, the messages say VS Code Insiders.

To stop Hoku suggesting the extension, click Don’t suggest this again in the setup sheet.

Uninstall

1. In VS Code, open the Extensions view, find Hoku, and choose Uninstall. Repeat in each profile where you installed it.
2. Each window removes its file when the extension stops, and Hoku cleans up anything left behind. To remove the folder anyway, quit Hoku and delete ~/Library/Application Support/com.hoku.app/vscode-bridge.

Go to terminal then goes back to bringing VS Code forward without picking the terminal.