Files, Editing, and Previews

The details panel's Files tab is rooted at the current working directory. Double-click Markdown, reStructuredText, HTML, SVG, or source code to open editable Source on the right. Images, PDFs, rich documents, diffs, Agent transcripts, and binary files remain read-only previews. Expand directories with an arrow or double-click. Context-menu actions include:

• Open: use the macOS default app, with another confirmation for executables or .app bundles.
• Open in Aster: Current Pane, New Tab, New Window, or Split Right/Left/Top/Bottom.
• New File… / New Folder…: create in a selected file's parent or inside a selected directory, without overwriting an existing name. New files open as editable Source.
• Rename… / Move to Trash: open Panes follow a renamed path; deleted items go to the recoverable system Trash.
• Copy Path / Copy Relative Path / Reveal in Finder: relative paths use the current Files root without ./.

A File Pane's toolbar has mode, Send to Chat, and sharing on the left; filename and a more menu centrally; and ✓ Saved, Edited, disk-conflict/error status, save, and close on the right. Markdown, reStructuredText, HTML, and SVG use code/eye controls to switch between editable Source and Preview; ordinary source uses code/lock to lock or unlock editing in place. Source follows the Pane size. … → Soft Wrap toggles line wrapping; with wrapping off, long lines can scroll horizontally. Switching preserves selection, scroll position, and undo. ⌘S saves atomically; there is no autosave. Closing unsaved content asks to save, discard, or cancel. External changes automatically reload an unedited Pane. With local edits, Modified on Disk appears; … → Reload from Disk explicitly discards local content.

Preview supports Markdown including GFM tables and task lists, reStructuredText, HTML, SVG, common images/GIF, PDF, diff, Office/media/font Quick Look, binary hex, and recognized Agent transcripts. HTML/SVG/Markdown previews disable JavaScript and network requests. Agent transcripts render by role with Markdown and collapsible tools, plus Resume or Fork. Hex draws only visible rows; large text and binary reads are bounded so one Pane cannot consume all memory. Remote SSH paths do not yet support File Panes.

For an ordinary UTF-8 file, the bubble Send to Chat action requires a non-symlink file no larger than 64 KiB. It removes control characters and masks common secrets first. Read/save failures show an explicit error and retain unsaved content.

Drag Finder files or directories to a Pane edge to create previews, file browsers, or new terminals inheriting the directory in the highlighted direction. Text dropped into a terminal uses the same dangerous-content confirmation as paste. HTTP/HTTPS URLs create Web Panes in that direction. At most 32 URLs are handled at once; symbolic links and special files are not read.

Open Files and Links in the Terminal

Hold ⌘ to underline all clickable targets in the viewport. Hover shows a hand cursor, including when you press Command with the pointer already over a target; releasing Command or moving away restores it. Clicking uses the system default app or the destination selected in Open In. Aster recognizes absolute paths, ~/, ./, relative paths based on current OSC 7 directory, existing bare filenames such as Makefile or site/README.md, path:line:column, URLs, mailto:, and explicit OSC 8 links. Remote relative paths are not treated as local files.

In Settings → Control → Link Protocols, Automatically Recognize Link Protocols → All recognizes valid protocols. Custom limits plain-text URLs to http, https, file, mailto, and configured schemes. Explicit OSC 8 links are not limited by that list but still undergo security checks. Show Link Preview controls the full target tooltip in the lower-left corner on Command-hover; disabling it leaves links clickable. Local relative paths expand against the current trusted directory. The fixed translucent rounded tooltip is white on black in light appearance and black on white in dark appearance, independent of terminal theme. Reset Security Prompts clears all remembered Always Allow choices.

Under Custom, choose Configure… to add, edit, or remove protocols line by line; valid changes save immediately. Enter codex or ssh, or SSH:// which normalizes to lowercase. Up to 64 protocols of at most 64 characters are allowed. Invalid input stays visible in red, and failed saves can be retried. Done or Esc closes after saving and returns to Configure. Switching to All preserves the custom list. Protocol changes immediately update open terminals' targets, underlines, and hand cursors. Reset success briefly shows a checkmark for about 1.6 seconds while retaining protocols and preview preferences.

Settings → Control → Open In separately chooses destinations for links, files, and folders. Local ordinary files/folders can open in Aster Editor / File Browser Panes or in system apps/Finder. HTTP/HTTPS pages can open in a Web Pane restricted to web navigation, without access to local files or custom protocols. The default Git client and custom apps are stored by bundle ID so macOS can find them after moving or upgrading.

The first open of an external website, nonstandard scheme such as codex://, executable, or .app asks to open once, always allow, or cancel. Reset clears these exceptions. Executable authorization follows the current file identity, so replacing or modifying it asks again. Settings import does not import another machine's security permissions. FIFOs, sockets, and device files are always rejected to avoid blocking or accessing system devices.

Copy and Paste

• Use ⌘C, Edit → Copy, or the terminal context menu to copy a selection, and ⌘V to paste. Copy on Select, Trim Trailing Whitespace When Copying, and Clear Selection After Copying are all off by default. Copy on Select keeps highlighting for selection extension and ignores clear-after-copy.
• Paste protection is on by default. Multiline content, a trailing newline, sudo/su, or invisible control characters show a bounded preview with Paste Anyway or cancel. Full-screen TUIs or trusted bracketed paste may skip ordinary multiline warnings, but invisible controls always require confirmation. Embedded bracketed-paste end markers become visible text and cannot prematurely execute following commands.
• Edit → Paste As retains bracketed paste and Paste and Continue in Composer. Selection paste, Base64 file, and Shell-argument escaping actions that depend on the old engine's private input state are currently disabled.
• Paste and Continue in Composer hands clipboard text to Agent Composer when available; otherwise its context-menu entry is disabled.
• Edit → Prompt Queue… works in the current terminal regardless of Claude Code/Codex detection. It opens an input strip at the Pane bottom; Return or the upward arrow adds an item to the list. With installed lifecycle hooks, idle Claude Code/Codex receives the first queued prompt immediately; processing queues it until the turn ends, one at a time. Awaiting permission/input never sends automatically: Return at a permission selector would approve a tool call. Ordinary CLIs without hooks remain fully manual.
• Click an item's left ↳ to send immediately, or its trash icon to remove an unsent item. Closing the input strip does not cancel the queue. Expand for multiline input. Read-only and terminal input-mode restrictions still apply.
• Edit → Send to Chat… and context-menu Send Selection to Chat open a confirmation panel. Choose the current selection and/or terminal transcript, then a running Claude Code/Codex Pane from the current workspace. Send prefills the Comment and cleaned, masked context as ordinary typing; it does not press Return.
• In a remote managed terminal, ⌘V with a PNG/TIFF clipboard image uploads it to a remote temporary directory and pastes only the remote path without a newline. Failure, cancellation, a changed terminal, or lost lease pastes nothing and leaves no partial remote file. The limit is 20 MiB per image. Image content does not enter diagnostic logs.

Programs can request clipboard access via OSC 52. Settings → Control → Copy & Paste separately offers Allow / Ask Every Time / Deny; writing defaults to Allow and reading to Ask Every Time. Each prompt authorizes only that request, followed by a 5-second cooldown for repeated requests. Config import cannot silently change read permission to Allow. Rejected or oversized requests do not read the clipboard.

Select Terminal Text

• Drag for characters, double-click for words, and triple-click for a line. Shift-click extends from an existing anchor; Option-drag selects rectangular columns.
• Vi / Mark Mode supports keyboard movement and selection extension. Ghostty handles mouse and Option-rectangle selections.
• When programs such as vim or tmux enable mouse reporting, Ghostty and the foreground program determine whether Shift stays available for local selection.
• Copy on Select, clear-on-input, clear-after-copy, and trailing-space treatment under Control → Selection apply immediately. Old-engine Shift-arrow and Backspace deletion switches do not currently apply.

Scroll Terminal History

• The wheel or trackpad browses the normal buffer. With smooth scrolling, trackpad movement follows pixels and aligns to character rows after the gesture and inertia end; the mouse wheel remains row-based. Input returns to the latest content. New output follows only when already at the bottom; a running command or TUI does not pull you away from history you scrolled up to read.
• Scrolling or hovering at the right edge reveals a fading scrollbar when content exceeds the Pane height. Drag its thumb to locate any position; click above/below it to move by one screen.
• Shift+Page Up / Page Down pages; Shift+Home / End goes to the earliest/latest content. Command+Page Up / Page Down navigates Shell commands. These are also in View → Terminal Scroll.
• Settings → Control → Scroll can disable smooth scrolling and choose whether the last content line, cursor line, or first content line stops at the viewport top, center, or bottom when scrolling beyond the end/start. Full-screen TUI alternate screens never allow out-of-bounds blank space.

Rendering and Continuous Output

Aster uses Ghostty's Metal renderer. The same engine manages PTY reads, VT state, scrollback, and drawing; Aster responds to the resulting render requests. Continuous output no longer uses the old AppKit byte-batch and Core Graphics grid path.

Input and Secure Keyboard Entry

• Ghostty encodes keyboard, IME, modifier, and Kitty keyboard-protocol input. Aster no longer guesses ordinary Shell line-editing sequences separately.
• Edit → Insert selects one or more file/folder paths or starts a system interactive screenshot. Safely escaped paths are prefilled into the current foreground input, including Codex/Claude TUIs, without execution. Edit → Insert from iPhone offers nearby iPhone/iPad camera or scanning actions and inserts the private temporary path through the same flow. Phone imports accept common images or PDFs, up to 32 MiB per item.
• Edit → Composer (⇧⌘E) opens an input area at the current Pane's bottom for typing, sending, or adding to Prompt Queue; it is not a file picker. Open local files through File, the file tree, or a path. Prompt Queue… (⇧⌘M) and Send to Chat… open the current terminal's queue strip and confirmation panel respectively.
• New installs default Option as Meta to off, preserving accented/special-character entry. For Emacs/Vim-style Esc prefixes, choose both, left-only, or right-only Option under Control → Keyboard. VT100 keypad mode defaults to allowed; when off, the keypad keeps entering numbers even if a program requests DECKPAM.
• Control → Mouse configures right-click as menu, copy, paste, selection-dependent, or ignored; Control + right-click always opens the menu. It also configures the bypass modifier for TUI mouse reporting, hiding the pointer while typing, hover-to-focus, and click-to-move-cursor on a reliable Shell prompt line.
• Automatic Secure Input is on by default. A focused terminal entering canonical hidden input, such as a password prompt, activates macOS Secure Event Input on output arrival and before the first key is sent. Raw-mode TUIs such as Vim/less do not claim it. Echo restoration, focus loss, process exit, or switching apps releases it. Edit → Secure Keyboard Entry toggles it manually. A blue SECURE INPUT capsule appears in the workspace title bar only after system protection is active. Manual state pauses when Aster is inactive and resumes on return.
• Codex, Claude, and ordinary Shell inputs retain Ctrl+A, Ctrl+E, Ctrl+K, Ctrl+U, Ctrl+W, and other line-editing keys. Aster's native ⌘← or ⌥← menu shortcuts do not take them over.

Font Size and Full Screen

• View offers increase/decrease/reset font size, also ⌘=, ⌘-, and ⌘0. The range is 9–32 pt, reset is 13 pt, and changes apply to all open terminals.
• View → Enter Full Screen or Fn+F toggles the workspace window; the menu becomes Exit Full Screen afterward.

Interface Text Size and Stronger Text

• The font size above affects terminals only. Sidebar, details panel, popovers, and Settings text use Settings → Appearance → Interface Text → Interface Text Size, with five steps: Small, Default, Large, Larger, Largest.
• Settings shows the new size immediately so you can preview it. The sidebar and panels change after Aster restarts; Aster asks whether to restart now or later.
• If descriptions or unselected tabs look too faint, turn on Stronger Interface Text in the same group. It darkens secondary text immediately, with no restart. It turns on automatically when macOS Accessibility → Display → Increase Contrast is enabled.
• Neither option changes font size or colors inside terminals.

Read-Only Mode

• Aster Vi / Mark / Hint Mode uses stable coordinates in Ghostty's retained buffer. Output or reflow invalidating an old anchor safely exits the mode.
• Shell → Read-Only Mode, or the command palette (⇧⌘P), toggles read-only per Pane. Keyboard, IME, paste, and TUI mouse reports no longer reach the program; output, scrolling, selection, copying, and find remain. Editor Panes stop accepting edits too. This temporary lock is not restored after closing and reopening the workspace.

Collapse Live View

• Visible Panes redraw for each frame of continuous Agent output, including unfocused splits and Aster windows beside other apps. Collapse a Pane's live view when you do not need to watch it, to avoid that drawing work.
• Hover at a terminal Pane's top edge and click the eye icon that fades in at the top right. You can also use terminal context-menu Collapse Live View, View → Collapse Live View (⇧⌘B, current focused Pane), or search Collapse or Restore Live View in the command palette. When an Agent such as Claude Code captures the mouse, an ordinary right-click does not open the menu; use the eye icon, ⇧⌘B, or Control + right-click instead.
• A small card replaces the view. With an Agent it shows the Agent name and processing, awaiting confirmation/input, idle, or completed status; waiting is highlighted. Otherwise it shows the Pane title. It shows only the collapse time, such as 14:03, without a running timer.
• The process, Agent, and terminal contents continue, and terminal size stays the same. Completion/wait notifications still work. Aster neither restores the view automatically nor steals focus.
• Click Restore Live View, choose the same menu again, or press Return/Space while the card is focused to show the latest view immediately.
• Keys are not sent while collapsed, avoiding unseen input. Tab/app switches do not restore it. Collapse state is not saved; restored workspaces show live views.
• Panes in system or interactive Picture in Picture cannot collapse; that action is disabled. Opening Picture in Picture for a collapsed Pane first restores its view.

Autocomplete and Inline Suggestions

Choose keys under Settings → Control → Autocomplete:

• Accept Candidate: Tab, Tab + Right Arrow (either accepts), Control + Space, or Off (no key accepts the gray suggestion). macOS defaults Control+Space to input-source switching; change/disable that in System Settings → Keyboard → Keyboard Shortcuts → Input Sources before choosing it here.
• Candidate Panel: Auto opens while typing, Esc to Open uses Esc, Option + Esc to Open uses Option+Esc or F5, and Off never shows it.

With the panel visible, Tab can accept its first item. Return accepts an explicitly selected candidate; otherwise it goes to the Shell. Explicit failure corrections are definite suggestions and may take inline priority over history candidates.

The panel shows up to 8 rows, with arrow-key scrolling and full descriptions in its right sidebar. It does not automatically open on an empty prompt; it opens after the first character and hides if you delete everything. Esc can still open it manually. Continued typing narrows results without closing it. Auto-opening does not treat the first item as your selection: arrows select, and Return or Tab accepts. One Esc dismisses it for this prompt; another reopens it. Disabling both inline suggestion and the candidate panel fully disables this feature, including querying the built-in specifications.

Autocomplete uses Ghostty's raw PTY observer. Inline suggestions appear only for a single candidate or an explicitly selected one; changing selection updates preview and description together.

Clipboard Suggestions

Copy a command from a browser, document, or chat, then return to Aster. At an empty prompt it appears in gray with a paste hint. Return inserts it into the input line without executing it; review it and press Return again to run. Start typing or press Esc to ignore it. The same clipboard contents are not suggested twice.

Suggestions require a single line of at most 128 characters, without control characters or Chinese text, and not a URL. Options, pipes, redirection, &&, environment assignments, or path syntax identify commands even if the tool is not installed. Ambiguous plain words require a recognized first command (built-in spec, alias, history, or executable in PATH). Prose, URLs, and logs do not trigger suggestions. A short guard delay before Return can accept prevents accidental paste from repeated empty-prompt Return presses.

Clipboard contents marked concealed by password managers such as 1Password/Keychain are never suggested, nor are any suggestions shown during secure input. They appear only in the active input Pane. Disable Clipboard suggestion in Control → Autocomplete to turn them off. The gray text reveals clipboard contents on screen, so take care when recording or presenting. It uses the terminal font and input baseline without covering the prompt or echoed command. Candidate acceptance, privacy filters, local learning, and directory-context rules still apply.

An empty prompt recommends the current directory's frequent commands, pinned commands, and README commands, not the entire specification library. After a recognized failure, a correction takes priority at the next prompt; typing ignores it. If the Shell's own gray suggestion occupies the line end, Aster hides its inline suggestion but keeps the panel. Narrow Panes show fewer rows to avoid covering input.

After a complete command name but before a space, such as docker, candidates include that command's subcommands/options as well as other names sharing the prefix. Tab or another configured acceptance key accepts an already visible suggestion, including one drawn by zsh-autosuggestions. Aster sends only the suffix rather than invoking zsh's “list all possibilities” question. A single candidate stays inline; an open panel narrows to one and closes. With multiple candidates and no visible suggestion, the acceptance key opens the panel. Native Shell completion receives the key only when neither a suggestion nor candidates exist.

Context-sensitive completion: cd lists directories, including directory symlinks; cd .. becomes ../ and cd ~ becomes ~/. Previously visited directories that no longer exist are not recommended (this check is not made for remote sessions). Subcommand slots do not include unrelated project files. Names containing spaces or quotes preserve your existing quoting/escaping style. Options support --option=value; used nonrepeatable options are excluded and arguments after -- are positional. Historical arguments learn per directory and argument position, so a frequent branch can still be suggested after adding --force. Disabling local learning disables historical argument suggestions too.

Dynamic candidates: when a built-in spec requires live data, such as git checkout <branch>, brew install <formula>, npm run <script>, or make <target>, Aster reads existing .git/refs, .git/packed-refs, .git/config, package.json, Makefiles, and Homebrew Formula//Cellar/ directories. It does not run the tool being completed: brew install completion does not trigger brew update, and git checkout completion does not execute git. Recent branches rank higher using .git/logs/HEAD. Data requiring tool execution, such as a git status --short staging list, falls back to file completion.

Homebrew 4.x uses its JSON API by default. Without a homebrew-core tap or API name cache, brew install can suggest only installed packages and third-party tap formulae, because completion does not fetch data or trigger brew update.

Scripts in package.json, Makefiles, or justfiles are not suggested as top-level commands; those files are read only when a specification requests that argument slot. To pin a project command, install the CLI in Settings → Shell → Aster CLI, then run in that directory:

aster learn 'npm run deploy'

When the argument is a bare binary name on PATH, aster learn instead runs its --help in a sandbox without network or file writes and parses subcommands/options into the local library:

aster learn ripgrep

These local specs are stored separately and survive built-in-spec Update Now. Repeating aster learn for a command increases its ranking weight. aster ignore reverses the three kinds of learning:

aster ignore ./old-project      # Stop tracking this frequent directory
aster ignore 'npm run deploy'   # Unpin this command
aster ignore ripgrep            # Remove this tool's locally learned help spec

Unpinning preserves ordinary execution history if you actually ran the command, but removes its pinned priority. Built-in CLI specs were not learned by you and are not removed by aster ignore.

Local Learning is on by default. It stores masked commands, directories, and counts, not output. Values for --password, --token, --api-key, and similar flags are removed. Only executed commands are learned; exit codes 126/127, explicit command-not-found output, clearly invalid long options, and History Ignore Patterns are excluded. Incomplete built-in structures may be probed with fixed --help, -h, or help arguments in a sandbox with no network/file writes, capped at 2.5 seconds and 128 KiB. Completeness considers options and arguments, not only subcommands: docker has 58 upstream subcommands but no top-level options. Probing chooses the deepest incomplete level, such as docker compose --help for the upstream compose placeholder. Results merge subcommands/options with the built-in fields instead of erasing its nested structure. Remote sessions do not read local project files or run local help probes. Disabling local learning disables history, pinned commands, README suggestions, corrections, and help probing; built-in specs and file completion remain.

Ranking follows usage: frequently used commands, subcommands, options, and arguments are remembered across directories. In a new directory, cl can still favor claude, and git ch your usual subcommand. Commands absent from built-in specs, such as claude/codex, and frequent argument values such as SSH hosts can complete anywhere. The previous successful command also informs ranking: frequent git add → git commit sequences favor commit after add. Failed preceding commands do not inform it. These rules adjust order, never execute commands, and reset with learning data.

Fig specifications do not update in the background. Control displays the count/version; use Update Now to refresh without replacing local help specs. Clearing history, pinned commands, and directory-frequency data does not delete built-in, manually updated, or help specs.

Unicode, Bidirectional Text, and Terminal Images

• Aster supports combining characters, double-width CJK, emoji ZWJ/skin-tone/flag sequences, text/emoji variation selectors, 24-bit truecolor, 256 colors, and full SGR styling. Enclosed alphanumerics default to two columns; Advanced allows changing the East-Asian-Ambiguous blocks to widen. Width policy affects new tabs and subsequently written characters.
• Appearance → Text offers off, standard, or discretionary ligatures plus bold, italic, and blink rendering. Blink is steady by default and animates only when selected.
• Bidirectional text is on by default. Hebrew, Arabic, and mixed-direction lines display in reading order; copy, find, and paste use the program's logical order. Arrows and mouse hits follow visual positions. Disable it for full-screen TUIs that lay out RTL themselves. ECMA-48 mode 8 automatically suspends implicit reordering.
• Programs can display iTerm2, Kitty, and Sixel images. Input, chunks, decompression, pixel dimensions, and cache are bounded. Damaged, canceled, or oversized images are discarded without disrupting later output.
• The app bundles JetBrains Mono, Office Code Pro, and Symbols Nerd Font Mono as used by Otty 1.3.1, alongside Aster Nerd Symbols fallback. No separate installation is needed. BMP and supplementary-plane symbols remain available even when the base font lacks Powerline/Nerd icons.

Progress, Badges, and Notifications

Programs can report percent, indeterminate progress, error, or completion via OSC 9;4. With Shell Integration, commands listed under Advanced → Automatic Progress Commands also show running state. Matching uses whitespace-separated prefixes: git push matches git push origin main, not git pushd. Empty the list to disable matching.

Tabs show running, just-completed, unread completion, error, and awaiting-input status beside their names. Agent processing/confirmation/resumption/completion changes update the icon without rebuilding terminals or interrupting input. Without lifecycle hooks, Claude Code/Codex spinners stop after about 5 seconds without input/output and restart when activity returns. With hooks, precise lifecycle state remains authoritative during quiet reasoning. Password, [y/n], yes/no, or Press Enter prompts must remain for about 1.5 seconds before awaiting-input appears; any input clears it, including unread Agent-completion dots. Appearance can enable Dock animation. Red-on-error defaults to on; clicking the red Dock icon focuses the failed tab and acknowledges it. Acknowledged errors do not turn it red again; later app switching returns to your last tab.

With the CLI installed, wrap a one-off task or set the current tab's badge:

aster watch make deploy
aster watch -q cargo test
aster tab badge --kind awaiting-input
aster tab badge --clear

watch preserves the wrapped exit code. -q suppresses only this completion notification, not progress/badges.

OSC 9, OSC 777, and OSC 99 can send macOS notifications. OSC 99 supports separate title/body, urgency, base64, chunks, and replacement by ID. Shell settings independently control success/error/watch notifications, Shell Controlled behavior, foreground policy (always, unfocused tabs only, or off), Dock bounce, error-exit beep, BEL, and sounds for error/completion/app notifications. The permission row shows macOS's current state and opens system settings.

Title permissions are under Advanced: Shell Controlled allows OSC 0/1/2 title changes; title reporting allows programs to read titles and defaults to off. OSC 52 permissions and Secure Keyboard Entry remain under Control.