Terminal Basics

Purpose and Scope

The integrated terminal is the place where VS Code lets a workspace and a shell meet without forcing the user to leave the editor. From a user perspective, it can be opened from the Terminal menu, Command Palette, Explorer context menu, or keyboard shortcuts, and it normally starts at the workspace root. From a repository perspective, the source evidence for this page focuses on one important part of that experience: terminal command assistance for the public code, code-insiders, code-tunnel, and code-tunnel-insiders commands. These completion specs are how terminal input becomes discoverable instead of relying entirely on memorized flags.

Sources: extensions/terminal-suggest/src/completions/code.ts, extensions/terminal-suggest/src/completions/code-insiders.ts, extensions/terminal-suggest/src/completions/code-tunnel.ts, extensions/terminal-suggest/src/completions/code-tunnel-insiders.ts

This page should be read as a practical orientation to terminal basics, with the source mapping centered on the bundled terminal-suggest extension. The official terminal documentation describes creating terminals, managing terminal tabs, shell profiles, terminal editors, split terminals, and shell integration. The files cited here show the complementary implementation surface that makes command entry richer once a shell is active: named completion specs, reusable option groups, file and folder argument templates, tunnel-specific command metadata, and shell-state objects used by the autocomplete layer.

Relevant Source Files

extensions/terminal-suggest/src/completions/code-insiders.ts - Defines the Fig completion spec for the code-insiders command by reusing the main code spec and replacing the command name, description, and option groups for Insiders.
extensions/terminal-suggest/src/completions/code-tunnel-insiders.ts - Defines the Insiders tunnel completion spec, combining shared tunnel subcommands, extension-management options, troubleshooting options, global tunnel options, and tunnel-specific options.
extensions/terminal-suggest/src/completions/code-tunnel.ts - Defines tunnel CLI completion behavior for code-tunnel, including CLI data directory, log, telemetry, verbosity, help, and service-oriented options.
extensions/terminal-suggest/src/completions/code.ts - Defines shared completion data for the desktop code command, including file input, diff, merge, workspace window behavior, locale, user-data directory, and profile-oriented options.
extensions/terminal-suggest/src/fig/api-bindings/types.ts - Declares shell context types exposed to terminal autocomplete logic, including process identity, working directory, session ID, shell path, environment variables, aliases, terminal, host, and integration version.
extensions/terminal-suggest/src/fig/autocomplete/fig/hooks.ts - Defines the FigState shape used by completion hooks, including the current buffer, cursor location, current working directory, active process, SSH context, aliases, environment variables, and optional shell context.

User Workflow: Opening, Running, and Managing Terminals

A terminal starts as a shell process attached to a VS Code workspace. Users can create one from Terminal > New Terminal, toggle the panel with the terminal shortcut, open a terminal from a folder in the Explorer, or choose a profile from the terminal dropdown. The official behavior also notes an important trust boundary: opening a terminal is blocked in Restricted Mode because shells can automatically execute workspace-controlled startup code. Once created, terminal instances are represented in the terminal tabs UI, where each terminal can have a name, icon, color, and grouping decoration.

Although the supplied source paths do not implement the terminal panel itself, they show how VS Code treats terminal input as a structured interaction. In code.ts, the completion spec for the code command declares common options such as reading from stdin with -, opening diffs with -d or --diff, performing a three-way merge with -m or --merge, adding folders to the last active window with -a or --add, removing folders with --remove, and navigating directly to file:line[:character] with -g or --goto. That is terminal basics at the command-entry layer: input is not just text, but a known command shape with file and folder arguments.

Sources: extensions/terminal-suggest/src/completions/code.ts

Terminal tabs, split terminals, and terminal editors all help users decide where a shell should live. A terminal tab is an entry in the terminal view; a split terminal shares visible space with another terminal; a terminal editor places a terminal in the editor area so it can participate more like an editor tab. The completion sources are independent of those layout choices. The same code completion data remains useful whether the shell is in the panel, split next to another shell, or moved into an editor, because the completion context is derived from shell state and current input rather than from a specific workbench container.

Terminal Input Assistance and Shell Context

The terminal-suggest extension needs more than a command name to offer useful suggestions. It needs to know what the user has typed, where the cursor is, which process owns the prompt, what directory the command is running in, and which aliases or environment variables might affect interpretation. FigState captures those runtime facts with fields such as buffer, cursorLocation, cwd, processUserIsIn, sshContextString, aliases, environmentVariables, and an optional shellContext. This creates a clean boundary between the terminal UI and the autocomplete engine: the engine receives a state snapshot and can compute suggestions from it.

Sources: extensions/terminal-suggest/src/fig/autocomplete/fig/hooks.ts, extensions/terminal-suggest/src/fig/api-bindings/types.ts

ShellContext gives that state snapshot durable shell metadata. It can include the shell process ID, terminal device, process name, current working directory, terminal session ID, integration version, parent terminal name, hostname, shell path, exported environment variables, and raw alias output. These fields are especially important for basic terminal behavior because a command like code . depends on the current working directory, while a remote or SSH terminal may need different context from a local one. The model also explains why terminal completion is a shell-integration feature rather than a static list of strings.

Command Completion Reference

The desktop completion specs share a common contract: a Fig completion spec has a command name, a human-readable description, optional subcommands, and an options list. code-insiders.ts demonstrates reuse by spreading the base code spec and overriding the command name to code-insiders, then composing commonOptions, extensionManagementOptions('code-insiders'), and troubleshootingOptions('code-insiders'). This keeps Insiders behavior aligned with Stable while still allowing command-specific labels and option generation. The result is a small wrapper around a shared public CLI vocabulary, not a duplicated command definition.

Sources: extensions/terminal-suggest/src/completions/code-insiders.ts, extensions/terminal-suggest/src/completions/code.ts

Command surface	Source-backed entries	What users get in the terminal
`code`	`-`, `--diff`, `--merge`, `--add`, `--remove`, `--goto`, `--new-window`, `--reuse-window`, `--wait`, `--locale`, `--user-data-dir`, `--profile`	Suggestions for opening files, folders, workspaces, merge flows, localized launches, and isolated user-data/profile sessions.
`code-insiders`	Base `code` spec plus Insiders-specific command name and option composition	The same completion model for the Insiders build.
`code-tunnel`	Tunnel subcommands, extension-management options, troubleshooting options, global tunnel options, tunnel options	Suggestions for the tunnel CLI entrypoint and its remote-access-oriented flags.
`code-tunnel-insiders`	Tunnel Insiders command name plus shared tunnel subcommands and options	The same tunnel completion model for Insiders.

The tunnel completion files add a second terminal basics scenario: using the terminal to connect VS Code workflows beyond the local desktop process. code-tunnel.ts exports codeTunnelSpecOptions with options such as --cli-data-dir, --log-to-file, --log, --telemetry-level, --verbose, --disable-telemetry, and --help. The completion spec then combines the base code data with tunnel subcommands and option groups. code-tunnel-insiders.ts mirrors this structure for Insiders and includes the extension tunnel subcommand, which keeps tunnel behavior discoverable for both release channels.

Sources: extensions/terminal-suggest/src/completions/code-tunnel.ts, extensions/terminal-suggest/src/completions/code-tunnel-insiders.ts

Persistence, Profiles, and Workspace Boundaries

Terminal persistence means users can keep command history, scrollback, and terminal identity across common workbench transitions when the product supports it. Profiles define which shell executable, arguments, and customizations a new terminal uses. The official terminal docs describe profile detection and default-profile selection, including platform-specific defaults and user-defined settings. The supplied repository sources do not include the profile resolver, but the completion layer still reflects profile-adjacent workflows: code.ts includes --user-data-dir for opening distinct Code instances and --profile for opening a folder or workspace with a named profile association.

Sources: extensions/terminal-suggest/src/completions/code.ts

This distinction matters for contributors. Terminal creation, tabs, split terminals, and persistence are workbench responsibilities; command suggestions are extension responsibilities. When a user opens two split terminals and runs code --goto src/file.ts:10, the workbench owns where terminals are shown, while the completion spec owns how the command is suggested and how its argument shape is described. Keeping those concerns separate allows improvements to terminal layout and terminal autocomplete to evolve independently while still feeling like one integrated terminal experience.

Testing Signals and Contributor Next Steps

For this source slice, the best testing signal is structural: completion specs are plain TypeScript data composed from shared option arrays and exported as default specs. That makes them straightforward to validate through extension tests or smoke flows that exercise terminal suggestions, but the supplied evidence does not include those test files. When changing these files, contributors should check that command names match the actual CLI entrypoints, option descriptions match the public command behavior, file and folder arguments use the correct templates, and Insiders variants continue to reuse shared Stable definitions unless behavior intentionally diverges.

Next, read Terminal Profiles and Shell Integration for shell selection, profile settings, and shell-integration behavior, or Command Line Interface for the broader code command beyond terminal completions. If you are modifying autocomplete behavior, start with extensions/terminal-suggest/src/fig/autocomplete/fig/hooks.ts to understand the runtime state passed to suggestion hooks, then inspect the command-specific completion file you are changing. If you are modifying terminal layout, persistence, split terminals, or terminal editors, use this page only as the command-assistance map and follow the workbench terminal implementation sources in the broader repository.

Ask a question...