keep-ncurses-output

keep-ncurses-output runs an interactive terminal application and leaves its last meaningful alternate-screen frame visible after the application exits. It is intended for ncurses-style applications such as mc, htop, and vim.

Requirements

• Linux or another POSIX system with a pseudoterminal (pty)
• Python 3
• pyte

Install pyte with either:

python3 -m pip install pyte

or, on Debian-derived systems:

sudo apt install python3-pyte

Usage

Run a command after -- (the separator is optional unless an argument could be mistaken for an option):

keep-ncurses-output -- mc
keep-ncurses-output -- htop
keep-ncurses-output -- vim README.md

The wrapper requires both standard input and standard output to be terminals. It forwards keyboard input, window-size changes, and common termination signals to the child application.

When an application leaves its alternate screen, the wrapper replays the last non-empty alternate-screen stream on the normal screen. This means an application such as mc, which clears its display just before exit, retains its useful final frame. Replaying the original terminal stream also preserves the application's SGR color sequences instead of approximating colors through a separate palette.

Vim sends terminal capability and color queries. The wrapper removes those queries during final replay, preventing their replies from being inserted at your shell prompt.

For developers: raw logs and diagnostics

Use --keep to retain the raw child-output log:

keep-ncurses-output --keep -- htop

The path is printed to standard error after the command exits. Inspect the distinct SGR sequences in a retained log with:

tools/inspect-sgr /tmp/keep-ncurses-output-XXXXXX.raw

Without --keep, the temporary raw log is removed automatically.

License

This project is (c) 2026 Faster IT GmbH and licensed under the 0BSD License.

Run keep-ncurses-output --license for the complete license text.