Shape the window.

Focus the window first.

Click the floating window, then choose the action from the Command Palette.

Commands for the focused floating window

To do this	Use
Step through size presets	Porthole: Cycle Window Size
Unpin or re-pin	Porthole: Toggle Always on Top
Return to the main window	Porthole: Dock Back into Main Window, or Ctrl+Alt+M (⌃⌥M on macOS)

Pick your sizes.

porthole.sizes defines the cycle. A new window opens at the first preset. These are the defaults:

"porthole.sizes": [
  { "name": "S", "width": 420, "height": 640 },
  { "name": "M", "width": 480, "height": 720 },
  { "name": "L", "width": 640, "height": 900 }
]

Dimensions are pixels. VS Code will not make a window smaller than 400 × 270. Cycling size reopens the page at the next preset.

If a page was opened through an outside link with an explicit size, the next cycle starts at your first preset.

Choose where it opens.

porthole.position defaults to null, which lets VS Code center the window on the current window. To choose screen coordinates:

"porthole.position": { "x": 40, "y": 80 }

porthole.compact and porthole.alwaysOnTop both default to true. They choose how a window opens. The pin command changes the focused window.

Keep one tab in view.

Choosing Keep Compact at the first-use prompt lets Porthole configure VS Code’s workbench.editor.autoLockGroups setting. It writes only the integrated-browser and Markdown-preview entries, and tells you when it changes a setting.

Some extensions open editors by column number, which can still place a second tab in a floating window. porthole.keepToOneTab decides what happens:

• move — move the editor to the main window, keeping its cursor. The default.
• ask — ask each time.
• off — leave it in the floating window.

An editor with unsaved changes is always left where it is.

If the preset does not apply.

Exact sizing relies on an internal VS Code command. If that call fails or Porthole detects no new window, it tries opening the page through separate commands, without applying your requested size. Check the Porthole output channel if no window appears.

Set porthole.useInternalCommand to false to skip the internal sizing command and use this fallback for new windows. Size presets then do not apply. See Settings and troubleshooting for the available controls and known limits.