Portaterm docs

Everything you need after installing Portaterm: shortcuts, settings, what session restore keeps on disk, and how to export terminal output.

On this page

Install
Quickstart
Shortcuts
Settings
Session restore
Export terminal output
Cursor Agent CLI
Requirements

Install

VS Code: search Portaterm in the Extensions view (Marketplace), or run:

ext install mhd.portaterm

Cursor, Windsurf, Antigravity, VSCodium, and other VS Code-compatible editors: search Portaterm in the Extensions view. It is published to Open VSX.

Portaterm uses its own extension ID (mhd.portaterm) and settings namespace (portaterm.*), so it can be installed alongside the upstream AnyWhere Terminal.

Quickstart

Click the Portaterm icon in the Activity Bar — a session starts automatically.
Drag the view to any sidebar, panel, or editor group. See how to move the terminal.
Use the title bar to add tabs or split panes. Right-click for context actions.
Open the AI Vault from the panel header (or Portaterm: Open AI Vault) to browse and continue your AI-CLI sessions. See how to resume sessions.

Run Cmd+Shift+P and type Portaterm: for the full command list.

Shortcuts

Replace Cmd with Ctrl on Windows and Linux.

Shortcut	Action
`Cmd`+`C` / `Cmd`+`V`	Copy / paste. Selection-aware, with `Ctrl`+`C` fallback.
`Cmd`+`K`	Clear the terminal (also clears its saved scrollback).
`Cmd`+`F`	Find in the terminal. `Enter` / `Shift`+`Enter` (or `Cmd`+`G` / `Shift`+`Cmd`+`G`; `F3` / `Shift`+`F3` on Windows and Linux) step through matches, `Escape` closes.
`Cmd`+`Backspace`	Kill the input line.
`Shift`+`Enter`	Insert a newline.
`Cmd`+`Shift`+`Enter`	Zoom or unzoom the focused split pane.
`Cmd`+`W` (Windows/Linux: `Ctrl`+`Shift`+`W`)	Close the active tab, while a Portaterm view has focus.

Rename a tab by double-clicking its label, choosing Rename Tab… from its context menu, or running Portaterm: Rename Tab…. Renaming a tab that runs an agent session also renames that session in the AI Vault. Right-click a tab for Change Tab Color… and Change Tab Icon…, and a split pane for Broadcast Input to All Panes.

Settings

Key settings under portaterm.*. The Settings UI lists them all; the gear next to the AI Vault search opens it filtered to Portaterm.

Setting	Default	Description
`shell.macOS` / `shell.linux` / `shell.windows`	`""`	Custom shell path per platform. Empty = auto-detect.
`shell.args`	`[]`	Custom shell arguments. Empty = sensible defaults.
`scrollback`	`10000`	Scrollback buffer lines.
`fontSize`	`0`	`0` = inherit from the editor.
`fontFamily`	`""`	Empty = inherit from the editor.
`cursorBlink`	`true`	Cursor blink.
`defaultCwd`	`""`	Empty = workspace root or `$HOME`.
`sessionRestore.enabled`	`true`	Restore terminal scrollback and metadata across restarts.
`sessionRestore.resumeClaude`	`all`	Which restored tabs resume the Claude conversation they were running: `all`, `pinned`, or `off`.
`agentNotifications.enabled`	`false`	Notify when an agent you cannot see is waiting for your approval or answer.
`agentNotifications.onTurnEnd`	`true`	Also notify when an agent you cannot see finishes its turn.
`cursorAgent.hooks.enabled`	`false`	Machine-scoped, fail-open Cursor Agent activity and approval observation.
`hoverPreview.enabled`	`true`	Hover previews for file paths and pasted images. Clicking a link still opens the file when off.
`hoverPreview.delay`	`300`	Delay in ms before the file preview loads, 100–2000.
`hoverPreview.blockSensitive`	`true`	Block auto-preview for dotfiles and sensitive folders (`Cmd`/`Ctrl` overrides).
`fileTree.autoReveal`	`true`	Reveal the active editor file in the file tree (`"focusNoScroll"` to skip scrolling).

Shell auto-detect. With an empty shell.<platform>, Portaterm uses the editor's resolved default shell (which honors terminal.integrated.defaultProfile and the remote host), then falls back per platform: macOS $SHELL → /bin/zsh → /bin/bash → /bin/sh, Linux $SHELL → /bin/bash → /bin/sh, Windows %ComSpec% → cmd.exe.

Session restore

Shells stay alive across window reloads, including long-running processes such as npm run dev. After a full restart a fresh shell starts, and each tab comes back with its scrollback, name, location, working directory, and layout; a dim divider marks where the restored output ends. A tab that was running Claude Code types claude --resume <id> into its new shell, so the conversation continues; set sessionRestore.resumeClaude to pinned or off to limit this.

Snapshots are scoped to the workspace and capped at 20 per workspace, 1 MB each, and 7 days of age. With no folder open, nothing is saved.
Scrollback is stored in plain text in the editor's extension storage. Anything shown in the terminal — including a secret you echoed or pasted — is written to disk until it ages out. Cmd+K also clears the saved buffer; set sessionRestore.enabled to false to store nothing and delete existing snapshots.

Export terminal output

Command	What it writes
Portaterm: Export Buffer to File…	The full scrollback of the focused terminal. Always available.
Portaterm: Export Last Command Output…	The most recent command with its exit code, cwd, and output. Needs shell integration.
Portaterm: Export Command…	Pick any tracked command, then save it. Needs shell integration.

Save as Text (ANSI stripped), readable in any editor, or Raw (ANSI preserved), which replays with colors in cat or less -R. Exports include everything that was on screen, so review them before sharing.

Shell integration is injected automatically for bash, zsh, and fish on macOS and Linux, pwsh on all three platforms, and Git Bash on Windows. It uses the same OSC 633 sequences as the editor's built-in terminal. Other shells, or shells started with --noprofile --norc / -NoProfile, can still export the full buffer.

Cursor Agent CLI

The AI Vault previews history from both Cursor Agent CLI and Cursor IDE Composer. Portaterm launches only a Cursor Agent CLI you installed yourself, following Cursor's installation guide; it never bundles Cursor's executable.

Validated CLI chats can be resumed as agent --resume <chat-id> (or the cursor-agent alias). Cursor IDE entries are preview-only.
Set cursorAgent.hooks.enabled to true to show working, approval, and idle states on tabs running Cursor Agent. Portaterm only adds and removes its own entries in ~/.cursor/hooks.json.
Run agent status to check authentication and agent --help to check the CLI's capabilities.

Requirements

VS Code 1.105+ or Cursor 3.2.21+
macOS, Linux, or Windows

Found a bug or missing something? Open an issue on GitHub.

Last updated October 29, 2026 · Source: the Portaterm README.