detect-terminal/README.md

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 [![NPM version](https://img.shields.io/npm/v/detect-terminal.svg?style=flat)](https://www.npmjs.com/package/detect-terminal) [![NPM downloads](https://img.shields.io/npm/dm/detect-terminal.svg?style=flat)](https://npmjs.org/package/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](https://www.npmjs.com/):

```sh
$ npm install --save detect-terminal
```

## Usage

```js
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

```js
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:

```js
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:

```js
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:

```js
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](https://github.com/alacritty/alacritty) | `ALACRITTY_SOCKET`, `ALACRITTY_LOG`, `TERM=alacritty`, or `TERM_PROGRAM=alacritty` | Cross-platform, GPU-accelerated terminal emulator |
| [Apple Terminal](https://support.apple.com/guide/terminal/welcome/mac) | `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](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmd) | `process.title=cmd` or `COMSPEC=cmd.exe` | Windows Command Prompt |
| [Eterm](http://www.eterm.org/) | `TERM_PROGRAM=Eterm` | Enlightened Terminal Emulator |
| [Foot](https://codeberg.org/dnkl/foot) | `TERM=foot*` or `process.title=foot` | Fast, lightweight Wayland terminal emulator |
| [Ghostty](https://ghostty.org/) | `GHOSTTY_RESOURCES_DIR` or `TERM=ghostty` | GPU-accelerated terminal emulator |
| [Gnome Terminal](https://help.gnome.org/users/gnome-terminal/stable/) | `TERM_PROGRAM=gnome-terminal`, `TERM_PROGRAM=gnome-terminal-server`, `VTE_VERSION >= 3803`, `TERM=gnome*`, `TERM=guake`, or `TERM=terminator` | GNOME terminal emulator |
| [Hyper](https://hyper.is/) | `TERM_PROGRAM=Hyper` | JS/HTML/CSS terminal emulator |
| [iTerm2](https://iterm2.com/) | `TERM_PROGRAM=iTerm.app` or `iTerm` or `iTerm2` | Advanced terminal for macOS |
| [Kitty](https://sw.kovidgoyal.net/kitty/) | `KITTY_PID`, `TERM_PROGRAM=kitty`, or `TERM=kitty` | GPU-accelerated terminal emulator |
| [Konsole](https://konsole.kde.org/) | `TERM_PROGRAM=konsole` or environment variables containing "konsole" | KDE terminal emulator |
| [MATE Terminal](https://mate-desktop.org/) | `TERM_PROGRAM=mate-terminal` | MATE terminal emulator |
| mrxvt | `TERM=mrxvt` or parent process name | Multi-tabbed rxvt-based terminal emulator |
| [PowerShell](https://github.com/PowerShell/PowerShell) | `TERM_PROGRAM=powershell`, `process.title=powershell`, `process.title=pwsh`, or `COMSPEC=powershell.exe` | Powerful Windows/macOS/Linux shell |
| [PuTTY](https://www.putty.org/) | `TERM_PROGRAM=putty` | Popular SSH/Telnet client for Windows |
| [QTerminal](https://github.com/lxqt/qterminal) | `TERM_PROGRAM=qterminal` | Lightweight terminal for LXQt |
| [Rio](https://raphamorim.io/rio/) | `TERM_PROGRAM=rio` or `TERM=rio*` | GPU-accelerated terminal built in Rust |
| [rxvt/rxvt-unicode](http://rxvt.sourceforge.net/) | `TERM=rxvt*` or `TERM_PROGRAM=rxvt` | Lightweight terminal emulator and its Unicode variant |
| [screen](https://www.gnu.org/software/screen/) | `TERM=screen*` | Terminal multiplexer |
| [Terminator](https://gnometerminator.blogspot.com/p/introduction.html) | `TERM_PROGRAM=terminator` | Multiple terminals per window |
| Terminology | `TERM=terminology` or parent process name | Enlightenment terminal emulator |
| [Termux](https://termux.com/) | `TERM_PROGRAM=termux` or `TERMUX_VERSION` on Android | Android terminal emulator |
| Tilda | `TERM=tilda` or parent process name | Drop-down terminal emulator |
| [tmux](https://github.com/tmux/tmux) | `TERM=tmux*` | Terminal multiplexer |
| [VS Code](https://code.visualstudio.com/) | `TERM_PROGRAM=vscode`, `VSCODE_PID`, or `TERM_PROGRAM_VERSION` contains `vscode` | Visual Studio Code integrated terminal |
| [Warp](https://www.warp.dev/) | `TERM_PROGRAM=warp` | Modern Rust-based terminal |
| [WezTerm](https://wezfurlong.org/wezterm/) | `TERM_PROGRAM=wezterm` | GPU-accelerated terminal emulator |
| [Windows Terminal](https://github.com/microsoft/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](https://docs.xfce.org/apps/terminal/start) | `TERM_PROGRAM=xfce4-terminal` | Xfce terminal emulator |
| [Xterm](https://invisible-island.net/xterm/) | `TERM=xterm`, `TERM=xterm-256color`, or truecolor xterm env values | X Window System terminal emulator |
| [VT100/VT220](https://en.wikipedia.org/wiki/VT220) | `TERM=vt100` or `TERM=vt220` | DEC VT100 and VT220 (and compatible emulators) |
| [Linux Console](https://en.wikipedia.org/wiki/Linux_console) | `TERM=linux` | Native Linux virtual console |
| [Dopamine](https://github.com/aspect-build/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

## Related

You might also be interested in:

* [cross-capture](https://www.npmjs.com/package/cross-capture): Capture screenshots programmatically. Cross-platform, with support for MacOS (Darwin), Windows, and Linux. | [homepage](https://github.com/jonschlinkert/cross-capture "Capture screenshots programmatically. Cross-platform, with support for MacOS (Darwin), Windows, and Linux.")
* [emit-keypress](https://www.npmjs.com/package/emit-keypress): Drop-dead simple keypress event emitter for Node.js. Create powerful CLI applications and experiences with ease. | [homepage](https://github.com/enquirer/emit-keypress "Drop-dead simple keypress event emitter for Node.js. Create powerful CLI applications and experiences with ease.")
* [enquirer](https://www.npmjs.com/package/enquirer): Stylish, intuitive and user-friendly prompt system. Fast and lightweight enough for small projects, powerful and… [more](https://github.com/enquirer/enquirer) | [homepage](https://github.com/enquirer/enquirer "Stylish, intuitive and user-friendly prompt system. Fast and lightweight enough for small projects, powerful and extensible enough for the most advanced use cases.")
* [open-file-manager-dialog](https://www.npmjs.com/package/open-file-manager-dialog): Cross-platform library for opening a file manager dialog window programmatically on MacOS, Windows, or Linux. | [homepage](https://github.com/jonschlinkert/open-file-manager-dialog "Cross-platform library for opening a file manager dialog window programmatically on MacOS, Windows, or Linux.")
* [open-file-manager](https://www.npmjs.com/package/open-file-manager): Cross-platform utility to open a file or directory in the system's default file manager (Finder… [more](https://github.com/jonschlinkert/open-file-manager) | [homepage](https://github.com/jonschlinkert/open-file-manager "Cross-platform utility to open a file or directory in the system's default file manager (Finder, Explorer, Nautilus, etc.)")
* [open-finder-dialog](https://www.npmjs.com/package/open-finder-dialog): Open a finder dialog window (finder prompt) programmatically. Only works on MacOS. | [homepage](https://github.com/jonschlinkert/open-finder-dialog "Open a finder dialog window (finder prompt) programmatically. Only works on MacOS.")
* [open-linux-file-dialog](https://www.npmjs.com/package/open-linux-file-dialog): Open a file dialog window programmatically to allow the user to select one or more… [more](https://github.com/jonschlinkert/open-linux-file-dialog) | [homepage](https://github.com/jonschlinkert/open-linux-file-dialog "Open a file dialog window programmatically to allow the user to select one or more files. Only works on Linux. No dependencies. Supports zenity (GNOME), kdialog (KDE), yad (Yet Another Dialog), qarma (Qt-based), matedialog (MATE), rofi (window switcher wi")
* [open-windows-file-dialog](https://www.npmjs.com/package/open-windows-file-dialog): Programmatically open a file dialog window (explorer) for picking files. Only works on Windows. Also… [more](https://github.com/jonschlinkert/open-windows-file-dialog) | [homepage](https://github.com/jonschlinkert/open-windows-file-dialog "Programmatically open a file dialog window (explorer) for picking files. Only works on Windows. Also see: open-finder-dialog, open-linux-file-dialog, and open-file-manager-dialog for other platforms.")

## About

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

### Building docs

_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_

To generate the readme and API documentation with [verb](https://github.com/verbose/verb):

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

### Running tests

Install dev dependencies:

```sh
$ npm install -d && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

### License

Copyright © 2026, [Jon Schlinkert](https://github.com/jonschlinkert).
MIT

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.1.31, on May 12, 2026._