Settings and troubleshooting.

Window settings.

Open VS Code Settings and search for porthole. Every setting in this table begins with porthole.

Window and preview defaults

Setting	Default	Purpose
sizes	420×640, 480×720, 640×900	Opening size and cycle sequence.
position	null	Opening coordinates; otherwise center on the current window.
compact	true	Hide tabs, breadcrumbs, and the status bar.
alwaysOnTop	true	Open pinned above other windows.
markdown.colorScheme	auto	Follow VS Code’s theme, or choose light or dark.
keepToOneTab	move	Handle editors opened by other extensions; also accepts ask or off.
askToKeepCompact	true	Offer VS Code’s one-tab configuration at first pop-out in a session.
useInternalCommand	true	Use the internal command for exact preset sizing.

Outside-link permissions.

These names begin with porthole.outsideLinks. They control links sent from a terminal, a script, or an agent.

Outside-link defaults

Setting	Default	Effect
enabled	true	Accept outside links at all.
actions.open	true	Allow links to open pages.
actions.installSkill	true	Allow skill-installation links, with permission remembered for the receiving VS Code workspace.
allowWorkspaceFolders	true	Allow files in the receiving window’s workspace folders without asking.
allowedFolders	[]	Additional folders, by absolute path, whose files may open without asking.
allowLocalFiles	false	Allow other local files without asking.

Folder checks resolve .. and symbolic links before comparing paths. Comparisons ignore letter case on macOS and Windows.

Turn porthole.outsideLinks.enabled off to disable the whole interface. The action settings let you control page opening and skill installation separately.

Review what changed.

Porthole: Review and Reset Settings… lists user settings set by or for Porthole. Select the entries you want to remove. Porthole also announces each change it makes to a setting, with a button to open it.

The size is wrong, or cycling does nothing.

Exact sizing relies on _workbench.openWith, an internal VS Code command rather than a documented API. VS Code can change or remove it without notice.

If the call fails or Porthole detects no new window, it tries opening the page through separate commands. This fallback does not apply your requested size. Check the Porthole output channel if no window appears.

Set porthole.useInternalCommand to false to skip _workbench.openWith and use this fallback for new windows. Size presets then do not apply.

An outside link does nothing.

1. Keep VS Code running and check that Porthole is installed. Outside links require 0.3.0 or later; skill installation requires 0.4.0.
2. Check that the local file exists and that its extension is supported.
3. Check the receiving VS Code window. A relative path is resolved only inside that window’s workspace folders.
4. Read the Porthole output channel. Refusals explain disabled settings, missing files, and ambiguous relative paths.

If a permission question is waiting, answer it before sending the link again. Terminal and agents covers parameters, encoding, and repeat opens.

A Markdown checkbox will not tick.

This is VS Code’s read-only Markdown preview. Use an HTML checklist when the page needs to respond to clicks or other input.

Paste or text shortcuts do not work.

On macOS, Cmd+V does not paste into a page while the floating window has focus. Use right-click → Paste.

Ctrl+A and Ctrl+E also do not move to the start and end of a line in integrated-browser text fields. These limits were traced to VS Code.

Report a problem.

Include your VS Code version and the Porthole output in a bug report. If you use an older VS Code release, first try the latest version.

Porthole has been run on macOS, with VS Code 1.134.0 and 1.141.0. Windows and Linux remain untested. The version-floor record distinguishes source inspection from hands-on checks.