Interface: TerminalService

Defined in: packages/sdk/src/terminal-service.ts:89

Consumer API for the terminal domain, exposed as ExtensionContext.terminals. The terminal is a core feature — a built-in DockKind like the editor — so this mirrors EditorService: create opens a terminal tab in a workspace, and closeWorkspace reaps a workspace's terminals. WorkspaceService.delete calls closeWorkspace for you; the primitive remains available for surgical reaping without deleting the workspace. The tab itself is rendered by the core dock from the workspace's terminal records.

Tab chrome adornments (setIcon / setIndicator / …) take a terminal session id as the target — see TabAdornmentMethods.

Extends

• TabAdornmentMethods

Methods

setIcon()

setIcon(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:185

Parameters

targetId

string

adornment

TabIconAdornment

Returns

void

Inherited from

TabAdornmentMethods.setIcon

---

clearIcon()

clearIcon(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:186

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearIcon

---

bindIcon()

bindIcon(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:187

Parameters

binder

TabIconBinder

Returns

Disposable

Inherited from

TabAdornmentMethods.bindIcon

---

setIndicator()

setIndicator(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:189

Parameters

targetId

string

adornment

TabIndicatorAdornment

Returns

void

Inherited from

TabAdornmentMethods.setIndicator

---

clearIndicator()

clearIndicator(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:190

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearIndicator

---

flashIndicator()

flashIndicator(targetId, flash): void;

Defined in: packages/sdk/src/tab-adornment.ts:191

Parameters

targetId

string

flash

TabIndicatorFlash

Returns

void

Inherited from

TabAdornmentMethods.flashIndicator

---

bindIndicator()

bindIndicator(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:192

Parameters

binder

TabIndicatorBinder

Returns

Disposable

Inherited from

TabAdornmentMethods.bindIndicator

---

setActivity()

setActivity(targetId, adornment): void;

Defined in: packages/sdk/src/tab-adornment.ts:194

Parameters

targetId

string

adornment

TabActivityAdornment

Returns

void

Inherited from

TabAdornmentMethods.setActivity

---

clearActivity()

clearActivity(targetId, adornmentId): void;

Defined in: packages/sdk/src/tab-adornment.ts:195

Parameters

targetId

string

adornmentId

string

Returns

void

Inherited from

TabAdornmentMethods.clearActivity

---

flashActivity()

flashActivity(targetId, flash): void;

Defined in: packages/sdk/src/tab-adornment.ts:196

Parameters

targetId

string

flash

TabActivityFlash

Returns

void

Inherited from

TabAdornmentMethods.flashActivity

---

bindActivity()

bindActivity(binder): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:197

Parameters

binder

TabActivityBinder

Returns

Disposable

Inherited from

TabAdornmentMethods.bindActivity

---

getIcons()

getIcons(targetId): TabIconAdornment[];

Defined in: packages/sdk/src/tab-adornment.ts:200

All leading icons for targetId, in set/bind order.

Parameters

targetId

string

Returns

TabIconAdornment[]

Inherited from

TabAdornmentMethods.getIcons

---

getIndicators()

getIndicators(targetId): TabIndicatorAdornment[];

Defined in: packages/sdk/src/tab-adornment.ts:202

All trailing indicators for targetId, in set/bind/flash order.

Parameters

targetId

string

Returns

TabIndicatorAdornment[]

Inherited from

TabAdornmentMethods.getIndicators

---

getActivities()

getActivities(targetId): TabActivityAdornment[];

Defined in: packages/sdk/src/tab-adornment.ts:204

All trailing activities for targetId, in set/bind/flash order.

Parameters

targetId

string

Returns

TabActivityAdornment[]

Inherited from

TabAdornmentMethods.getActivities

---

invalidateTabAdornments()

invalidateTabAdornments(): void;

Defined in: packages/sdk/src/tab-adornment.ts:206

Signal that binder data changed — re-query provide and re-render.

Returns

void

Inherited from

TabAdornmentMethods.invalidateTabAdornments

---

subscribeTabAdornments()

subscribeTabAdornments(listener): Disposable;

Defined in: packages/sdk/src/tab-adornment.ts:207

Parameters

listener

() => void

Returns

Disposable

Inherited from

TabAdornmentMethods.subscribeTabAdornments

---

create()

create(input?): TerminalRecord | undefined;

Defined in: packages/sdk/src/terminal-service.ts:99

Open a new terminal in a workspace (defaults to the active one). Returns the created TerminalRecord; the PTY session spawns lazily when its tab mounts.

Returns undefined only when input.workspaceId is not given and there is no active workspace at the time of the call — in normal use this does not happen because activating any workspace happens before extensions run.

Parameters

input?

CreateTerminalInput

Returns

TerminalRecord | undefined

---

closeWorkspace()

closeWorkspace(workspaceId): void;

Defined in: packages/sdk/src/terminal-service.ts:105

Close and kill every terminal in a workspace. WorkspaceService.delete reaps terminals the same way automatically, so this is for reaping a workspace's terminals surgically, without deleting the workspace itself.

Parameters

workspaceId

string

Returns

void

---

sendText()

sendText(
   terminalId, 
   text, 
   addNewline?): void;

Defined in: packages/sdk/src/terminal-service.ts:126

Write text to a terminal's PTY as if the user typed it. By default a carriage return is appended so the line executes; pass addNewline: false to stage text without running it.

Works even if the terminal tab has never been shown: the PTY spawns lazily on first mount, and sendText force-spawns it on demand (a later mount then attaches to that same session). No-op for an unknown terminalId.

Parameters

terminalId

string

The TerminalRecord.id to write to.

text

string

The text to send.

addNewline?

boolean

Append a carriage return to execute. Defaults to true.

Returns

void

Example

const term = ctx.terminals.create({ cwd: workspaceFolder });
if (term) ctx.terminals.sendText(term.id, "npm run build");

---

close()

close(terminalId): void;

Defined in: packages/sdk/src/terminal-service.ts:133

Close one terminal tab and kill its PTY session. No-op if the id is unknown. To reap every terminal in a workspace at once use TerminalService.closeWorkspace.

Parameters

terminalId

string

Returns

void

---

rename()

rename(terminalId, name): void;

Defined in: packages/sdk/src/terminal-service.ts:141

Set a terminal's user-facing name (TerminalRecord.customName), shown on its tab and persisted across restarts. Passing an empty string clears the custom name, letting the PTY-derived title take over again. No-op for an unknown terminalId.

Parameters

terminalId

string

name

string

Returns

void

---

focus()

focus(terminalId): void;

Defined in: packages/sdk/src/terminal-service.ts:147

Switch to the workspace containing this terminal and activate its tab in the center dock. No-ops if the terminal id is unknown.

Parameters

terminalId

string

Returns

void

---

registerTabDecoration()

registerTabDecoration(provider): Disposable;

Defined in: packages/sdk/src/terminal-service.ts:153

Parameters

provider

TerminalTabDecorationProvider

Returns

Disposable

Deprecated

Prefer TerminalService.bindIndicator. Thin shim that registers a trailing-indicator binder for terminal tabs only.

---

getTabDecoration()

getTabDecoration(terminalId): 
  | TabIndicatorContribution
  | null;

Defined in: packages/sdk/src/terminal-service.ts:159

Parameters

terminalId

string

Returns

| TabIndicatorContribution | null

Deprecated

Prefer TerminalService.getIndicators. Returns the first trailing indicator for a terminal tab, or null.

---

invalidateTabDecorations()

invalidateTabDecorations(): void;

Defined in: packages/sdk/src/terminal-service.ts:164

Returns

void

Deprecated

Prefer TerminalService.invalidateTabAdornments.

---

subscribeTabDecorations()

subscribeTabDecorations(listener): Disposable;

Defined in: packages/sdk/src/terminal-service.ts:169

Parameters

listener

() => void

Returns

Disposable

Deprecated

Prefer TerminalService.subscribeTabAdornments.

---

subscribeOsc()

subscribeOsc(terminalId, handler): Disposable;

Defined in: packages/sdk/src/terminal-service.ts:199

Subscribe to raw OSC (Operating System Command) escape sequences emitted by the terminal identified by terminalId. The handler is called once per parsed sequence — regardless of whether the terminal's panel is currently visible — making it suitable for background status monitoring.

The subscription is keyed to the terminal record id (e.g. "term_…"), not the underlying PTY session id, so it survives terminal recreation within the same record.

Returns a Disposable that cancels the subscription.

Parameters

terminalId

string

handler

(event) => void

Returns

Disposable

Example

// Detect Claude Code busy/idle state from OSC 0 title sequences.
const BRAILLE_START = 0x2800;
const BRAILLE_END   = 0x28FF;
const IDLE_CHAR     = '\u2733'; // ✳

const sub = ctx.terminals.subscribeOsc(terminalId, ({ code, payload }) => {
  if (code !== 0) return;
  const first = payload.charCodeAt(0);
  if (first >= BRAILLE_START && first <= BRAILLE_END) setStatus('busy');
  else if (payload.startsWith(IDLE_CHAR))              setStatus('idle');
});
ctx.subscriptions.push(sub);

---

subscribeOutput()

subscribeOutput(terminalId, handler): Disposable;

Defined in: packages/sdk/src/terminal-service.ts:232

Subscribe to the raw PTY output stream of the terminal identified by terminalId. The handler is called with every chunk of bytes the PTY produces — including ANSI escape sequences, OSC sequences, and all other control characters — exactly as they arrive, with no parsing or filtering.

This fires even when the terminal's panel is not visible, so it is suitable for background monitoring (e.g. detecting output activity to confirm an agent is still running). Keep handlers lightweight: they execute synchronously on every PTY chunk, which can be multiple times per second while a program is active.

The subscription is keyed to the terminal record id (e.g. "term_…"), not the underlying PTY session id, so it survives terminal recreation within the same record.

Returns a Disposable that cancels the subscription.

Parameters

terminalId

string

handler

(data) => void

Returns

Disposable

Example

// Track the last time any output arrived to confirm agent activity.
let lastOutputAt = 0;
const sub = ctx.terminals.subscribeOutput(terminalId, () => {
  lastOutputAt = Date.now();
});
ctx.subscriptions.push(sub);

---

getActive()

getActive(): string | null;

Defined in: packages/sdk/src/terminal-service.ts:244

The record id of the terminal tab that is currently active in the active workspace's center dock, or null when an editor tab (or nothing) is active. "Active" is the dock's single active panel — the tab the user is looking at and typing into — so a terminal merely visible in a non-active split does not count.

Returns

string | null

---

subscribeActive()

subscribeActive(listener): Disposable;

Defined in: packages/sdk/src/terminal-service.ts:266

Subscribe to active-terminal changes. The listener receives the terminal record id whenever a terminal tab becomes the active center-dock panel, and null when activation moves elsewhere (an editor tab, or no panel — including transiently during a workspace switch, before the incoming workspace's active tab is published).

Fires on tab activation, group activation, and workspace switches. Returns a Disposable that cancels the subscription.

Parameters

listener

(terminalId) => void

Returns

Disposable

Example

// Clear a "needs attention" marker once the user views the terminal.
ctx.subscriptions.push(
  ctx.terminals.subscribeActive((terminalId) => {
    if (terminalId) attention.delete(terminalId);
  }),
);