detect-terminal

v3.0.0

Published

a month ago

Detect the terminal program currently being used, with support for iTerm, Terminal.app, Hyper, iTerm2, ConEmu, Cmde,r Alacritty, Xterm, Terminator, Termux, Kitty, and others. Detection is based on environment variables and process-level indicators to iden

detect-terminal

Detect the terminal program currently being used, with support for iTerm, Terminal.app, Hyper, iTerm2, ConEmu, Cmde,r Alacritty, Xterm, Terminator, Termux, Kitty, and others. Detection is based on environment variables and process-level indicators to identify the terminal in use. This can't be done reliably in all cases, but it's useful when available.

Install

Install with npm:

$ npm install --save detect-terminal

Usage

import detectTerminal from 'detect-terminal';
// or
import { detectTerminal, detectTerminalDetails } from 'detect-terminal';

console.log(detectTerminal()) //=> "iterm" (or whatever terminal you're using)

console.log(detectTerminalDetails());
//=> {
//=>   terminal: "iterm",
//=>   source: "env",
//=>   isTTY: true,
//=>   isSSH: false,
//=>   isAmbiguous: false,
//=>   supportsColor: true,
//=>   colorLevel: 3,
//=>   supports256Color: true,
//=>   supportsTrueColor: true,
//=>   term: "xterm-256color",
//=>   termProgram: "iTerm.app",
//=>   colorTerm: "truecolor",
//=>   generic: "xterm_256color"
//=> }

Options

import detectTerminal from 'detect-terminal';

// By default, multiplexers like tmux/screen are detected first
console.log(detectTerminal()); //=> "tmux" (if running inside tmux)

// With preferOuter: true, prefer the outermost terminal (GUI app)
console.log(detectTerminal({ preferOuter: true })); //=> "iterm" (the actual terminal app)

| Option | Type | Default | Description | | --- | --- | --- | --- | | preferOuter | boolean | false | When true, prefer the outermost terminal (GUI app) over multiplexers like tmux/screen | | resolveAmbiguousFromParent | boolean | false | When true, inspect parent processes if env-based detection is missing or ambiguous | | unpipe | boolean | false | When true, continue env-based detection even when stdout is not currently a TTY |

Additional options are available for tests and advanced integrations:

| Option | Type | Description | | --- | --- | --- | | env | NodeJS.ProcessEnv | Environment object to inspect instead of process.env | | stdout | { isTTY: boolean } | Stdout-like object used for TTY checks | | platform | NodeJS.Platform | Platform value to use instead of process.platform | | pid | number | Starting process id for parent-process detection | | processTitle | string | Process title to inspect instead of process.title | | execFileSync | typeof execFileSync | Command runner used by shell and parent-process detection |

Details API

Use detectTerminalDetails() when you need more than the terminal identifier:

import { detectTerminalDetails } from 'detect-terminal';

const details = detectTerminalDetails({ resolveAmbiguousFromParent: true });

console.log(details.terminal); //=> "iterm"
console.log(details.source); //=> "parent"
console.log(details.supportsTrueColor); //=> true

The details object includes:

| Property | Type | Description | | --- | --- | --- | | terminal | string | Normalized terminal identifier | | source | 'env' \\|'parent' \\|'shell' \\|'process_title' \\|'none' \\|'unknown' | Detection method that produced the result | | isTTY | boolean | Whether stdout is currently a TTY | | isSSH | boolean | Whether SSH_CONNECTION is present | | isAmbiguous | boolean | Whether env-based detection produced an ambiguous terminal | | supportsColor | boolean | Whether any color support is available | | colorLevel | 0 \\|1 \\|2 \\|3 | Color capability level: none, basic, 256-color, or truecolor | | supports256Color | boolean | Whether TERM or COLORTERM indicates 256-color support | | supportsTrueColor | boolean | Whether COLORTERM indicates truecolor support | | term | string \\|undefined | Raw TERM value | | termProgram | string \\|undefined | Raw TERM_PROGRAM value | | colorTerm | string \\|undefined | Raw COLORTERM value | | generic | string | Normalized generic terminal value, usually derived from TERM | | appName | string \\|undefined | Parent process command name, when parent detection is used | | pid | number \\|undefined | Parent process id, when parent detection is used |

Helper APIs

The package also exports lower-level helpers for callers that want to inspect one detection layer at a time:

import {
  detectFromEnv,
  detectFromParentProcess,
  detectFromProcessTitle,
  detectFromShell,
  getColorLevel,
  getColorSupport
} from 'detect-terminal';

| Helper | Description | | --- | --- | | detectFromEnv() | Detects from terminal-related environment variables | | detectFromParentProcess() | Walks parent processes to identify the terminal app | | detectFromProcessTitle() | Detects from process.title | | detectFromShell() | Detects from shell-specific checks, including Windows COMSPEC and WT_SESSION | | getColorSupport() | Reports 256-color and truecolor support from TERM and COLORTERM | | getColorLevel() | Returns color level 0, 1, 2, or 3 |

Result-oriented variants are also exported for integrations that need source metadata:

import {
  detectFromEnvResult,
  detectFromParentProcessResult,
  detectFromProcessTitleResult,
  detectFromShellResult
} from 'detect-terminal';

Supported Terminals

The following terminals are supported. Detection is based on environment variables and process-level indicators to identify the terminal in use.

alacritty
aterm
atomic_terminal
bash
cmd
conhost
csh
dash
dopamine
dumb
eterm
fish
foot
ghostty
gnome_terminal
guake
hyper
iterm
kitty
konsole
ksh
kuake
linux_console
mate_terminal
mrxvt
node
nu
none
powershell
putty
qterminal
rio
rxvt
screen
sh
tcsh
terminal
terminal_app
terminator
terminology
termux
tilda
tmux
truecolor_terminal
vscode
vt100
warp
wezterm
windows_cmd
windows_terminal
wterm
xfce4_terminal
xterm
xterm_256color
xterm_truecolor
unknown
zsh

Note:

Some items are shell names (like cmd, sh (Bourne Shell), bash, zsh, fish, etc.) because the code's process-title detection maps those as possible values, and the code wasn't able to find a better terminal identifier.
The names are as returned by the detection methods (i.e., terminal_app, gnome_terminal, etc.) and not the terminal program's real executable names. This approach was taken to avoid confusion with the actual executable names, which can vary across platforms and installations.
Fallback/auto-generated names (using sanitized env values) are also possible in the code but are not explicitly named in the code.

Terminal Detection

| Terminal | Detection (ENV / Process) | Description | | --- | --- | --- | | Alacritty | ALACRITTY_SOCKET, ALACRITTY_LOG, TERM=alacritty, or TERM_PROGRAM=alacritty | Cross-platform, GPU-accelerated terminal emulator | | Apple Terminal | TERM_PROGRAM=Apple_Terminal | macOS default terminal emulator | | aterm | TERM=aterm or parent process name | AfterStep terminal emulator | | Atomic Terminal | TERM=atomic-terminal or parent process name | Atomic terminal emulator | | Cmd.exe | process.title=cmd or COMSPEC=cmd.exe | Windows Command Prompt | | Eterm | TERM_PROGRAM=Eterm | Enlightened Terminal Emulator | | Foot | TERM=foot* or process.title=foot | Fast, lightweight Wayland terminal emulator | | Ghostty | GHOSTTY_RESOURCES_DIR or TERM=ghostty | GPU-accelerated terminal emulator | | Gnome Terminal | TERM_PROGRAM=gnome-terminal, TERM_PROGRAM=gnome-terminal-server, VTE_VERSION >= 3803, TERM=gnome*, TERM=guake, or TERM=terminator | GNOME terminal emulator | | Hyper | TERM_PROGRAM=Hyper | JS/HTML/CSS terminal emulator | | iTerm2 | TERM_PROGRAM=iTerm.app or iTerm or iTerm2 | Advanced terminal for macOS | | Kitty | KITTY_PID, TERM_PROGRAM=kitty, or TERM=kitty | GPU-accelerated terminal emulator | | Konsole | TERM_PROGRAM=konsole or environment variables containing "konsole" | KDE terminal emulator | | MATE Terminal | TERM_PROGRAM=mate-terminal | MATE terminal emulator | | mrxvt | TERM=mrxvt or parent process name | Multi-tabbed rxvt-based terminal emulator | | PowerShell | TERM_PROGRAM=powershell, process.title=powershell, process.title=pwsh, or COMSPEC=powershell.exe | Powerful Windows/macOS/Linux shell | | PuTTY | TERM_PROGRAM=putty | Popular SSH/Telnet client for Windows | | QTerminal | TERM_PROGRAM=qterminal | Lightweight terminal for LXQt | | Rio | TERM_PROGRAM=rio or TERM=rio* | GPU-accelerated terminal built in Rust | | rxvt/rxvt-unicode | TERM=rxvt* or TERM_PROGRAM=rxvt | Lightweight terminal emulator and its Unicode variant | | screen | TERM=screen* | Terminal multiplexer | | Terminator | TERM_PROGRAM=terminator | Multiple terminals per window | | Terminology | TERM=terminology or parent process name | Enlightenment terminal emulator | | Termux | TERM_PROGRAM=termux or TERMUX_VERSION on Android | Android terminal emulator | | Tilda | TERM=tilda or parent process name | Drop-down terminal emulator | | tmux | TERM=tmux* | Terminal multiplexer | | VS Code | TERM_PROGRAM=vscode, VSCODE_PID, or TERM_PROGRAM_VERSION contains vscode | Visual Studio Code integrated terminal | | Warp | TERM_PROGRAM=warp | Modern Rust-based terminal | | WezTerm | TERM_PROGRAM=wezterm | GPU-accelerated terminal emulator | | Windows Terminal | WT_SESSION present or COMSPEC=wt.exe | Modern tabbed terminal for Windows 10+ | | wterm | TERM=wterm or parent process name | Wterm terminal emulator | | Xfce4 Terminal | TERM_PROGRAM=xfce4-terminal | Xfce terminal emulator | | Xterm | TERM=xterm, TERM=xterm-256color, or truecolor xterm env values | X Window System terminal emulator | | VT100/VT220 | TERM=vt100 or TERM=vt220 | DEC VT100 and VT220 (and compatible emulators) | | Linux Console | TERM=linux | Native Linux virtual console | | Dopamine | TERM=dopamine | Modern terminal emulator |

Notes:

Detection uses the TERM and TERM_PROGRAM environment variables, as well as process-level indicators such as process.title on some platforms, to identify the running terminal.
Terminal-specific environment variables (like KITTY_PID, GHOSTTY_RESOURCES_DIR, ALACRITTY_SOCKET) are checked first as they provide the most reliable detection.
Variable values are normalized to provide a consistent terminal identifier, regardless of differences in capitalization or formatting.
detectTerminalDetails() returns metadata about the detection source, TTY/SSH status, color support, raw terminal env values, and parent process info when available.
When stdout is not a TTY, detection returns none unless unpipe: true is used.
Some Windows terminals are detected using Windows-specific variables such as COMSPEC or WT_SESSION.
Terminal multiplexers such as tmux and GNU Screen are identified through the TERM variable when active. Use preferOuter: true to skip multiplexer detection and continue toward the outer terminal.
When resolveAmbiguousFromParent: true is used, ambiguous env results such as xterm, vt100, truecolor terminals, linux console, or skipped multiplexers can be resolved by walking parent processes.
When running inside Visual Studio Code's integrated terminal, detection relies on specific environment variables set by VS Code.
Distinctions are maintained between terminal emulators (e.g., iTerm2, Konsole) and shells (e.g., bash, zsh), with shells excluded from the main detection table.
In the absence of a recognized terminal, a fallback sanitizer produces a normalized identifier or unknown as a last resort.
The detection logic is designed to cover terminals across UNIX-like systems (Linux, macOS) and Windows, providing broad compatibility for diverse development environments.

History

v3.0.0

Added detectTerminalDetails() to return terminal metadata, detection source, TTY/SSH status, color support, raw env values, and parent process info
Added resolveAmbiguousFromParent option to resolve ambiguous env results by walking parent processes
Added unpipe option to continue detection when stdout is not currently a TTY
Added parent-process detection for outer terminal apps, with multiplexer handling that respects preferOuter
Added color capability reporting with supportsColor, colorLevel, supports256Color, and supportsTrueColor
Added none terminal result for non-TTY output when unpipe is not enabled
Added documentation for lower-level env, shell, parent-process, process-title, and color helper APIs
Added support for additional terminal identifiers including aterm, atomic_terminal, mrxvt, terminology, tilda, and wterm
Added test and integration options for custom env, stdout, platform, pid, process title, and command execution

v2.0.0

Added preferOuter option to prefer outermost terminal (GUI app) over multiplexers like tmux/screen
Added Ghostty terminal detection via GHOSTTY_RESOURCES_DIR environment variable
Added Foot terminal detection (Wayland terminal emulator)
Added Rio terminal detection (Rust-based GPU-accelerated terminal)
Improved Alacritty detection with ALACRITTY_SOCKET and ALACRITTY_LOG environment variables
Improved Kitty detection with KITTY_PID environment variable (most reliable method)
Added Linux Console detection via TERM=linux
Added Dopamine terminal detection
Reordered detection priority: terminal-specific env vars are now checked before TERM_PROGRAM

v1.1.0

Improved terminal detection accuracy with more advanced detection methods
Added VTE_VERSION detection to properly identify GNOME Terminal when it masquerades as xterm
Implemented environment variable scanning to detect Konsole terminals that advertise as xterm
Enhanced COLORTERM precedence handling for better terminal identification
Added macOS path parsing to extract application names from full paths
Improved Android/Termux detection with TERMUX_VERSION checks
Enhanced Windows Terminal detection with WT_SESSION prioritization and pwsh support
Added better error handling with timeouts for shell execution
Refined process title matching with more precise regex patterns

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

License

This file was generated by verb-generate-readme, v0.1.31, on May 12, 2026.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

detect-terminal

Install

Usage

Options

Details API

Helper APIs

Supported Terminals

Terminal Detection

History

v3.0.0

v2.0.0

v1.1.0

Related

About

Contributing

Building docs

Running tests

Author

License