Porthole

Pop the HTML page you are looking at into a floating window in VS Code: only the rendered page, pinned above your other windows.

If it is an HTML file and you want it in view while you work (for instance, a page of task instructions, a checklist, a design mock-up or a local report), porthole puts it in a window of its own instead of an editor tab that disappears behind whatever you open next.

Status: version 0.1.0, the first public release. Its author has used it daily since 2026-10-12, on macOS with VS Code 1.141.0 and 1.134.0. Windows and Linux are untested (the unit tests run on Linux in CI against a mocked VS Code, which says nothing about how the windows behave there). It leans on an internal VS Code command; see what could break.

See it

The first real use, on 2026-10-12: a page of step-by-step instructions (for replacing the publishing tokens of another project) kept in view while the person following it works in other windows. Nothing was staged.

The window alone: just the rendered page.

Beside the place the instructions came from.

Beside a different application: the steps stay in front while the person works in a web form.

And on to the next tool, without the page ever being moved.

What it does

1. Pops a page out. One gesture turns an HTML file into a floating window showing only the rendered page: no tabs, breadcrumbs or status bar.
2. Keeps it on top. The window stays pinned above your other windows. Toggle that off and on whenever you like.
3. Puts it back. The same shortcut docks the page into your main window again.
4. Resizes by preset. Step through your own list of sizes (three by default).
5. Stays live. The page reloads when the file changes (VS Code's own auto-reload), and its checkboxes, buttons and stored state keep working.

Using it

Right-click an HTML file in the Explorer.

Settings live under porthole.*: the size presets (porthole.sizes; the first preset is the size a new window opens at), where the window opens (porthole.position), and whether it opens compact and always on top (porthole.compact, porthole.alwaysOnTop).

Install

From the Marketplace: search for "Porthole" in VS Code's Extensions view, or run

code --install-extension jlumbroso.porthole

From Open VSX, for VS Code-compatible editors that use it (open-vsx.org/extension/jlumbroso/porthole). It is published there, but porthole has only been run in VS Code itself, and the internal command it relies on is VS Code's.

From a release file: each GitHub release carries the exact .vsix that was published. Install it with code --install-extension porthole-<version>.vsix.

From source: clone this repository, then run just install-local and reload the VS Code window. (That builds the extension, packages it, installs the exact file, and prints what to do next. It needs just and Node 22.)

Requirements

• VS Code desktop 1.134.0 or later. That is the first release whose integrated browser opens local HTML files, as read in VS Code's source. porthole has been run on 1.134.0 and on 1.141.0; the versions in between were read in VS Code's source but not run (details).
• Local HTML files (.html, .htm). Remote and virtual workspaces are out of scope.

Support. The latest VS Code release is the one officially supported. If you report a problem on an older version, the first answer will be "can you update to the latest version?".

How it works, and what could break

porthole renders nothing itself. VS Code already has an integrated browser, floating windows, a compact mode with no tabs or status bar, and always-on-top. What was missing is a single gesture that combines them at a chosen size.

That gesture is an internal VS Code command, not a documented API. porthole calls _workbench.openWith, which opens a file in the integrated browser, in a new floating window, already sized, compact and pinned. VS Code can change or remove it in any update, without notice.

If that call throws or opens no window, porthole falls back to public commands that do the same thing: the window still opens, compact and pinned, but at VS Code's own default size rather than your first preset. The output channel "Porthole" says when the fallback ran. The setting porthole.useInternalCommand turns the internal call off if you would rather never use it.

What has been checked, so you can weigh it:

• The internal call was traced through VS Code's source, checked independently against that source, and then run: on VS Code 1.141.0 it opened the window in five runs out of five (ADR-0003), and in the 15 pop-outs of its first hands-on test it never needed the fallback (ADR-0010).
• Each new VS Code release is a release question. The check to re-run is kept in spike/; until it is re-run on a version, that version is not claimed.

One thing to expect: the floating window keeps its title bar and the integrated browser's own toolbar. "Only the rendered page" means no tabs, breadcrumbs or status bar.

Known limits, both VS Code's rather than porthole's (traced in VS Code's source, ADR-0010, QST-PASTE):

• Cmd+V does not paste into a page in the floating window on macOS: VS Code disables its Edit menu while a floating window has focus. Right-click → Paste works.
• Ctrl+A and Ctrl+E (start and end of line) do nothing in a page's text field, in any integrated-browser tab.

Not here yet

• Popping out a page that is already open in a browser tab (today it starts from the file).
• A trigger from outside VS Code, for example a coding agent opening the task page it has just written.

Try the idea today, with no extension

1. Open an HTML file in the integrated browser.
2. Right-click its tab and choose Move into New Window.
3. In the new window's title bar, click the compact icon and the pin icon.

This gives you the experience porthole aims for, minus the one-gesture part and the exact size.

The name

A porthole is a small, fixed window you look through; nothing lives in it. That is the object this builds: the floating window is the porthole. The pages it shows are often served on localhost ports, which makes the pun honest.

Changes, reports and contributing

• What changed in each version: CHANGELOG.md, also the notes of each GitHub release.
• A bug or an idea: open an issue. The bug form asks for your VS Code version and the "Porthole" output channel, which are the two facts that matter most here.
• Working on it: npm ci, then npm run check (typecheck, tests, bundle, and a check that the package ships exactly its six allowed files); just gate runs that plus the repository's own checks. Press F5 and choose Run Porthole to try a change in a second VS Code window.

How this is built

This project is built by a human and AI collaborators working through written records, so decisions survive from one session to the next. The whole record is in the repository: the decisions in docs/adr/, the briefs the collaborators sent each other in docs/inbox/, the screenshots from the first test under docs/adr/attachments/.

• CLAUDE.md holds the working agreements and the current focus.
• docs/inbox/ONBOARDING.md is where a new collaborator starts.
• The research that started it is docs/INITIAL-DESIGN-BRIEF.md.

Credits and lineage

• Research brief: Claude Opus 5.5, from a prompt by Jérémie Lumbroso. The outside-VS-Code trigger was that session's own idea; the prompt did not ask for it.
• Built by Jérémie Lumbroso with Glazier 5.5 (Claude Opus 5.5); claims checked against VS Code's source by Surveyor 5.1 (Claude Fable 5.1); the release prepared by Purser 5.5 (Claude Sonnet 5.5). The full roster is in docs/inbox/agent-sessions.json.
• The repo's structure comes from the ADRs4AI human-AI collaboration template. What was unclear while adopting it is recorded in docs/TEMPLATE-FEEDBACK.md.

License

MIT.