A TUI wrapper for applying rules to live terminal screens.
twrap launches an interactive terminal application as a child process and wraps its screen with extra behavior from the outside.
It is designed for practical live-screen automation such as highlighting matches, masking sensitive text, taking screenshots, and remapping keys without modifying the target TUI itself.
cargo install twrap
This demo wraps both vim and less with the same live screen rules.
twrap highlights ERROR lines and rewrites user=... to user=hidden on screen, so the sensitive value is hidden in the TUI while the original file content stays unchanged.
This demo wraps htop with live masking and a custom screenshot key.
twrap masking blacknon to * on screen, remaps s to the screenshot action, and saves the captured SVG under ./tmp/twrap-artifacts/ with the configured htop-demo-... prefix.
Use twrap by placing its options before the target TUI command.
You can still add -- when you want to make the command boundary explicit.
You can combine highlighting, screenshots, masking, replacement, and key remapping in a single run.
twrap [options] <command> [args...]$ twrap --help
Wrap an existing TUI and add highlights plus screenshots
Usage: twrap [OPTIONS] <COMMAND>...
Arguments:
<COMMAND>...
Options:
-e, --highlight <HIGHLIGHT>
-H, --highlight-color <HIGHLIGHT_COLOR> [default: #fff59d]
-x, --highlight-command <HIGHLIGHT_COMMAND>
-S, --highlight-capture-tui-screenshot
-o, --screenshot-dir <SCREENSHOT_DIR> [default: tmp/twrap-artifacts]
-p, --screenshot-prefix <SCREENSHOT_PREFIX>
-k, --screenshot-key <SCREENSHOT_KEY> [default: ctrl-g]
-b, --bind <BIND>
-R, --replace <PATTERN> <TEXT>
-M, --mask <MASK>
-c, --mask-char <MASK_CHAR> [default: *]
-C, --startup-capture-ms <STARTUP_CAPTURE_MS> [default: 0]
-h, --help Print help
-V, --version Print version
Remap keys before they reach the wrapped TUI with --bind FROM=TO.
This is useful for shortcut aliases or assigning actions such as screenshots.
TO supports screenshot, key names like up, down, enter, f1, ctrl-c, or text:....
Example:
twrap -b j=down -b k=up -b ctrl-p=screenshot lazygitSave screenshots from the wrapped screen with --screenshot-key, --screenshot-dir, and --screenshot-prefix.
Enable -S if you also want screenshots captured when a highlight command matches.
Screenshots are saved as SVG files.
Prefix templates support {key}, {backend}, {capture_kind}, {ext}, {timestamp}, and {env:NAME}.
Example:
twrap -p 'nightly-{capture_kind}-{timestamp}-' -k ctrl-t btopHighlight matching text with --highlight PATTERN.
Add --highlight-command '...' to run a command when a match appears, and add -S to save a screenshot at the same time.
The command receives event data through environment variables such as TWRAP_HIGHLIGHT_KEY, TWRAP_HIGHLIGHT_PATTERN, TWRAP_HIGHLIGHT_MATCHES_JSON, and TWRAP_HIGHLIGHT_EVENT_JSON.
You can also interpolate {backend}, {key}, {pattern}, {matches_json}, {event_json}, and {capture_path} anywhere in the command arguments.
When -S is enabled, TWRAP_HIGHLIGHT_CAPTURE_PATH is also set to the saved screenshot path.
Example:
twrap -e '(?i)error' -x 'notify-send "twrap: {key}" "{matches_json}"' -S htopHide sensitive text on screen with --mask PATTERN.
Each matched character is replaced with the configured mask character.
--mask-char changes the masking character.
Example:
twrap -M 'token=[^ ]+' htopRewrite matched text on screen with --replace PATTERN TEXT.
This is useful when you want a stable visible label instead of the original text.
Replacement is fitted to the matched display width, truncating or padding with spaces when needed.
Example:
twrap -R 'user=[^ ]+' 'user=hidden' htop- baeru: an earlier TUI wrapper project based on the same core idea.
MIT. See LICENSE.