Terminal launchers
A terminal launcher puts a button on every folder's New terminal row that starts an installed program, such as a coding agent, in a new terminal. The launcher only says where the program is; Terminay does the rest. Added in API 3.3.
Manifest contribution
"api": "^3.3.0",
"permissions": ["agent-launch"],
"contributes": {
"terminalLaunchers": [{
"id": "com.example.agent/launch",
"displayName": "Example Agent",
"icon": "terminal",
"platforms": ["darwin", "linux"],
"harness": { "source": "com.example.agent/sessions", "harness": "example-agent" }
}]
}| Field | Meaning |
|---|---|
id | Required. Namespaced by the extension ID. |
displayName | Required. The program's name, used as the button's accessible name and tooltip. |
icon | Required. An id from Terminay's icon allowlist, EXTENSION_ICONS: terminal, server, cloud, key, folder, network, database, warning, info, agent-claude-code, or agent-codex. Extensions never supply artwork. |
platforms | Optional OS restriction. |
harness | Optional { source, harness } naming a harness of a session source the same package declares. While the user has that harness switched off, the launcher is not offered and not called. |
Requires the agent-launch permission. A manifest may declare up to 8.
Runtime contract
TypeScript context.subscriptions.add(
context.terminals.registerLauncher('com.example.agent/launch', {
async resolve(signal) {
const executable = await which('example-agent', signal);
return executable
? { available: true, executable }
: { available: false, reason: 'not_installed', detail: 'npm install -g example-agent' };
},
}),
);
resolve(signal) returns { available: true, executable } with the absolute path
of the program, or { available: false, reason, detail? } with reason not_installed or unsupported_platform. A launcher that becomes available or
unavailable appears or disappears on every New terminal row without a reload.
What Terminay does
Terminay creates the terminal in the folder the user chose, with the default shell profile and
working directory, and types the quoted path into the shell. It adds no arguments, environment, or
input of the launcher's, apart from the flags of a matching
terminal command default. When the program
exits the user is back at the shell. A launcher cannot read or write the terminal.
Test with registeredLauncherIds() and resolveLauncher(id) on the
agent extension harness.