# Open a page from a terminal.

Write the page to disk. Send its local path to VS Code with a vscode:// link.

## Open a local file.

Keep VS Code running with your project open. On macOS, replace the example path with an existing local HTML file, then run:

```
open 'vscode://jlumbroso.porthole/v1/open?file=/absolute/path/tasks.html&width=420&height=640'
```

Keep the quotes: the shell must leave the `&` characters alone. The page must be a local HTML or Markdown file. Web addresses and localhost URLs are not supported.

## What the link means.

Parameters for `/v1/open`

| Parameter | Meaning |
| --- | --- |
| `file` | Required. An absolute local path, or a path relative to a workspace folder in the receiving VS Code window. |
| `width`, `height` | Both or neither; positive whole pixels. Without them, the window uses the first size preset. VS Code raises dimensions below 400 × 270. |
| `repo` | A workspace folder’s name, used to disambiguate a relative path. It is not a repository URL. |

The VS Code window used most recently receives the link. Relative paths are looked up only in its workspace folders. Use an absolute path if the person may be working in another project. An ambiguous relative path is refused.

## Encode the path once.

Preserve the separating slashes. In JavaScript:

```
path.split('/').map(encodeURIComponent).join('/')
```

Spaces become `%20`, `+` becomes `%2B`, and `#` becomes `%23`. Do not use `encodeURI`, which leaves some query-significant characters alone.

One current limit: a filename containing `&` followed by letters and `=` cannot be sent through this interface, even encoded. Rename that file before using the link.

## What the person sees.

Disabled outside links or page-opening actions are refused. When both are enabled, files in permitted locations open without another Porthole prompt. For other files, Porthole offers **Open Once**, **Allow This Folder**, and **Cancel**. VS Code also has its own first-use permission prompt.

> **Opening a window moves keyboard focus.** On macOS, a new floating window takes focus. Avoid opening a page while the person is typing in another application: their keystrokes can go into the page.

Do not change these permission settings without the person’s approval. See [outside-link settings](https://jlumbroso.github.io/porthole-docs/settings-and-troubleshooting.html#settings-and-troubleshooting-outside-links) for the individual controls.

## Update the page, then check the result.

Save changes to HTML files; Markdown previews update as you edit. Sending the same link again without dimensions brings the existing window forward, where the person put it. Sending it with dimensions requests reopening at that size.

Sending a link does not prove that a page became visible. Read the **Porthole** output channel for receipt, opening, or refusal messages. When reporting the result, distinguish those messages from observing the rendered window.

## Install the Porthole skill.

Run **Porthole: Install the Skill for Models in This Project**, or send:

```
open 'vscode://jlumbroso.porthole/v1/install-skill'
```

Porthole writes `.claude/skills/porthole/SKILL.md` in a workspace folder. If the receiving window has several folders, add `?repo=<folder name>`. The first installation link asks permission for that VS Code workspace; approval also covers its other folders. Replacing an edited copy asks again.

Claude Code discovers the installed skill. Other agents can read the same file explicitly.

Outside links currently open pages and install the skill. Listing, closing, docking, pinning, and independently resizing windows through this interface are not implemented.

## Chapter notes

**Experimental**

Outside links have been run on macOS in VS Code. Their shape may change; check the changelog when upgrading.

**Version requirements**

Opening from an outside link requires Porthole 0.3.0 or later. Installing the model skill through the extension requires 0.4.0 or later.

**One receiving window**

The VS Code window used most recently receives the link. A repo parameter selects a workspace folder within that window; it does not route the link to another window.

For Porthole 0.4.0. Updated 19 October 2026. [Online chapter](https://jlumbroso.github.io/porthole-docs/terminal-and-agents.html). [Source reference](https://github.com/jlumbroso/porthole/blob/v0.4.0/.claude/skills/porthole/SKILL.md).