Files, output, and images#

Automexia helps you inspect text, files, and visual results without losing the context of the current task. Its presentation features make output easier to scan and images easier to preview, while the script or tool still controls the actual bytes and behavior.

This page explains what is merely visual, what is interactive, and which image approach to use.

If you need one task now, go to link and path hints, command-output styling, or the three image approaches. For ordinary text search, use the workspace search guide.

The basic rule: presentation must not change command output#

Automexia can add:

• prompt/context rows;
• icon-aware interactive listings where shell integration supports them;
• semantic highlighting for common tool states;
• terminal graphics rendered from supported escape protocols;
• local image quick-look overlays;
• selection/search/footer UI.

Links and path hints are another way to act on visible output. They are not shell commands, and opening one is an explicit user choice.

These features are not supposed to rewrite the bytes that scripts consume. When an application emits its own ANSI styling, that styling remains authoritative over presentation enhancements.

Prompt context and path#

In integrated shells, Automexia owns a semantic context spacer and complete path row while the shell's line editor owns the editable command line. This separation is why resizing can reflow the prompt context without Automexia pretending to be the shell editor.

Use the prompt context for orientation, but use shell commands/environment/tooling when you need machine-readable state. Renderer labels are a view, not a scripting API.

Icon-aware listings#

Interactive ls/ll presentation can add file/folder icons and stable category colors where the shell integration supports it. Long-listing variants can present structured columns while preserving native/script behavior boundaries.

Important practical rules:

• Use the enhanced aliases/wrappers for interactive browsing.
• Use native commands/explicit script forms when exact automation semantics matter.
• In CMD, built-in dir is deliberately not replaced.
• A user-defined EZA_COLORS is not overwritten by Automexia.

If icons are missing, first check Troubleshooting rather than installing unrelated shell/profile modifications.

The interactive listing wrapper is for readability, not for changing ls in scripts. Use command ls to bypass it in a Bash/Zsh session, or set AUTOMEXIA_PLAIN_LS=1 before shell integration loads when you prefer plain interactive listings. This is a listing wrapper, not a replacement for SSH.

Open links and paths#

Terminal output can include an application-provided hyperlink, a printed URL, or a local-looking path. The current source implements keyboard review; native browser-handler and screen-reader behavior still needs platform checks. In the Linux development defaults, press Ctrl+Alt+O to display hints in the selected pane's visible output, including scrolled history. Use Tab/Shift+Tab or Up/Down to focus a link. A displayed letter/number selects it; press Enter separately to act. Left/Right lets you inspect a long destination, Ctrl+Shift+C copies the exact target, and Escape cancels without shell input. The default Open action hands the target to the operating system's handler; it does not execute the terminal line as a shell command. Use this to open a documentation URL from test output or a local path printed by a tool.

Before opening, read the actual URI in the destination card, especially when it came from remote output, a log, or a page you did not create. A link label may not describe its actual destination. An external browser or application may handle the result. A mouse-reporting terminal application can own clicks, so use the hint action when a click belongs to that application.

You can configure hint rules and choose actions such as Copy instead of Open. The configuration reference shows a copy-only URL rule and the available actions. Treat matched text as untrusted: do not turn a broad rule into an automatic shell command. Link hints and image quick look are different: a URL can be opened by a platform handler, while quick look only decodes a supported local raster file.

The default opener rejects control or bidirectional-formatting characters, credential-bearing URLs, unknown schemes, and nonlocal file:// destinations; rejected hints remain copy-only. Remote file links are not silently downloaded or treated as local. If output changes, the pane changes, or the view moves, the review closes rather than reusing a label for a different target. A configured custom handler has its own authority—review it before applying it to untrusted output.

Semantic output#

Automexia recognizes common Kubernetes, Docker, Terraform, build, test, and structured-log states and may give warnings/errors a restrained presentation treatment.

This is visual only:

• copied text remains terminal text;
• explicit application ANSI colors win;
• selection and search highlights take higher priority;
• semantic recognition does not execute or alter commands.

Completed commands with proven shell boundaries also group their actual output inside a restrained tinted band. A gap, end rule, and known success/failure plus duration badge separate that result from the next command. This applies to any output-producing command, including ordinary output, errors, pipelines, native programs, and listings; it is not an ls-specific effect. A new live result lightens once for 540 milliseconds and then keeps its persistent grouping. Commands without output keep their truthful compact completion rule/status but do not receive an empty output surface or borrow the preceding command's state. The full grouping is available in integrated PowerShell, Bash, Zsh, and Fish sessions. Integrated CMD also groups output, but uses neutral styling because stock cmd.exe cannot provide a generic truthful exit status or duration.

Use it as a scanning aid, not as a replacement for the tool's own exit code or structured output.

Three ways to work with images#

1. Inline terminal graphics#

Implemented in current source; verify your build. Programs can explicitly send supported image escape sequences. The terminal recognizes these protocol families:

• Kitty Graphics;
• iTerm2 OSC 1337 inline images;
• Sixel.

This is the right approach for image-aware programs such as terminal image viewers/file managers because the program controls placement, scrolling, sizing, and lifecycle as terminal content.

Examples from their respective ecosystems include kitten icat, imgcat, and wezterm imgcat. Automexia does not change TERM_PROGRAM to impersonate another terminal; if a third-party tool has not learned the Automexia brand, configure that tool's explicit Kitty/iTerm2/Sixel adapter rather than lying about terminal identity.

Terminal multiplexers also need to pass the chosen graphics protocol through.

2. Local quick look#

Implemented in current source; verify your build. Quick look is for a local raster path that is already visible in terminal output. It is an emulator-owned overlay, not bytes sent into the PTY.

For example, when a build prints ./screenshots/result.png, hover that path to check the image without leaving the task. Click to pin the preview. If the mouse is busy, select the complete path and press Ctrl+Alt+I; the command palette offers the same action by name. Nothing is sent to the shell or uploaded by this preview.

Mouse workflow#

1. Move the pointer over a supported filename/path.
2. Hold it stable briefly; Automexia waits about 100 ms before decoding so fast pointer movement does not trigger constant file work.
3. The temporary preview appears if the path passes validation.
4. Click the path to pin the preview.
5. Click elsewhere or press Esc to dismiss.

Keyboard workflow#

1. Select the image path as terminal text.
2. Press Ctrl+Alt+I on Windows/Linux/BSD or Cmd+Alt+I on macOS.
3. While pinned, use Down/Right for the next visible image path and Up/Left for the previous one.
4. Press Esc to close.

Command-palette workflow#

Open the palette and run Preview Selected Image. With no selection, the action can use the supported path under the pointer.

Which path forms work?#

Quick look is designed for ordinary local output, including:

• bare filenames from listings;
• quoted names containing spaces;
• rooted paths;
• explicit relative paths;
• Unicode filenames;
• known WSL paths that can be validated/translated for the owning Windows-hosted WSL session.

Relative paths resolve using validated working-directory metadata rather than arbitrary terminal text alone.

Supported raster formats#

Quick look supports BMP, GIF, ICO, JPEG, PNG/PNM, TIFF, and WebP raster files. Animated formats receive a static quick-look frame.

It intentionally does not open SVG, PDF, URLs, remote hosts, directories, symlinks, named pipes, or device files. Use an explicit trusted application for those cases.

3. Use an external application when quick look is the wrong abstraction#

Choose an external application when:

• you need to edit the image;
• you need animation/full metadata/color-management behavior beyond a quick preview;
• the file is PDF/SVG or another unsupported format;
• the resource is remote and should be fetched under an explicit network/tool policy;
• the path is security-sensitive or does not pass Automexia's local regular-file checks.

Quick look is intentionally bounded; it is not a universal file opener.

Image security boundaries users will notice#

Quick look rejects unsafe/unbounded cases rather than trying to be clever. The canonical contract includes:

• no URL-scheme fetching;
• no arbitrary Windows UNC path opening;
• no symlink/device/named-pipe reads;
• a 20 MiB source-file limit;
• supported raster magic only;
• bounded dimensions/decoded pixels/allocation;
• background decode work rather than file decoding on UI/renderer/PTY threads;
• stale/replaced file checks before a decoded result is reused.

If a preview does not appear, the correct response is to verify the path/format/limits or use an explicit external tool—not to disable the safety boundary.

Selection and copied text#

Automexia's visual enhancements do not become hidden clipboard transformations. Selection belongs to terminal cells/text; quick-look overlays and semantic backgrounds are presentation layers.

For normal selection:

• drag with the mouse, or use Shift+Arrow;
• use Ctrl+C when a selection exists on Windows/Linux/BSD;
• use Cmd+C on macOS;
• use search when you are locating text in scrollback rather than selecting blindly.

The pane footer is status, not a toolbar#

When there is enough pane height, the footer can show information such as UTF-8, LF/CRLF, effective columns/rows, local time, pane/local-tab position, selection state, or scrollback offset.

It is intentionally read-only. Clicking it focuses the pane; it is not a collection of invisible action buttons. Use keyboard bindings, scrollbar, or the command palette for actions.

For the detailed image limits, layout behavior, icon taxonomy, and semantic rendering contract, see Terminal experience.