configuration.md

Configuration

Settings live in the registry under HKCU\Software\agliteterm; most of them are also on File ▸ Properties. Built-in action bindings are Key_* registry values there too, set in the Keyboard dialog. %LOCALAPPDATA%\agliteterm\keymap.conf holds custom commands, the leader, and extra map chords for commands or built-in actions (see commands and agent integration); a map line adds a chord and leaves the registry binding in place. Shell profiles live in %LOCALAPPDATA%\agliteterm\profiles.json.

Settings over the control API

config list reports supported keys and current values; config get KEY reads one; config set KEY VALUE saves only that registry value under HKCU\Software\agliteterm and applies it to this instance. Other running instances are not changed; future launches read the saved values. Unknown keys and invalid values refuse without changing settings. Writes also refuse while a modal dialog is open or queued, protecting its unsaved edits. A timed-out request already executing reports an unknown outcome: read back before retrying.

Keys	Values
theme	auto, dark, light, classic (lite's UI modes, not the full app's theme catalog)
custom-colors, dos-palette, show-sidebar, show-toolbar, show-status, flag-view	true/false (also on/off or 1/0)
right-click-paste, copy-on-ctrl-c, copy-on-select	true/false (also on/off or 1/0)
foreground, background	#RRGGBB; used when custom-colors is true
sidebar-font-size	0 for system default, or 6..24
scrollback-lines	0..1000000; default 5000; new surfaces only, no live eviction; positive caps allow 512 rows of batched-trim slack
omp-theme	a theme name (from omp list) or path for eligible new PowerShell shells, or none (see below)
restore-commands	true/false, default false (see below)
conpty	inbox (default) or bundled; read when the pty-host next starts (see below)

config list is the authoritative list; it also reports the cursor and quick-terminal keys this table leaves out.

theme list/set uses the same four modes. settings requests the Properties dialog without raising the terminal; its reply is settings open requested. keymap reload reloads registry bindings: deleted entries return to their default or unbound state, an explicit zero stays unbound.

With copy-on-select off, mouse release and finalize leave the clipboard alone; explicit Copy and mark-mode Enter/Ctrl+C still copy. The registry escape hatches for the two default-on clipboard bindings are RightClickPaste and CopyOnCtrlC (DWORD 0).

Scrollback config affects the local replica, not the host's retained history, and is applied before a new or adopted surface receives bytes.

The ConPTY shells run on

conpty = inbox, the default, uses the conhost built into Windows. It answers some of a program's questions itself (device attributes, the cursor position) and drops the color queries.

conpty = bundled runs shells on the conpty.dll + x64\OpenConsole.exe that ship beside agliteterm.exe (Microsoft's, the pair Windows Terminal uses). It hands a program's output to agliteterm unchanged and passes its questions through, and agliteterm answers them: the foreground and background colors (OSC 10 / OSC 11, from foreground / background when custom-colors is on, else light gray on black; a change reaches running panes at once), device attributes (DA1, DA2), device status and the cursor position. Codex draws the band behind your messages from the color reply.

It is opt-in because of what happens when a pane changes width (the window, the sidebar, a split). The inbox conhost re-wraps its screen and sends it again; the bundled ConPTY re-wraps its own copy and sends nothing, expecting the terminal to re-wrap the same way, and agliteterm's emulator does not: it keeps the top-left of what it had. After a resize a shell pane shows lines cut at the old or new width, and what is typed next lands at the wrong place, until the screen is redrawn (cls, or a full-screen program repainting itself). A program that reads a reply without virtual-terminal input mode also gets the cursor-position reply as a key press on the bundled ConPTY.

The pty-host reads the key once, when it starts, and it outlives the window: every window that connects to a running host gets the ConPTY that host started with. The new value applies after the last window and shell of that host are gone. If either file is missing, or the dll does not load, the host falls back to the inbox conhost without telling agliteterm; agliteterm.log records the argument each host was started with and whether the two files were there.

Panes start with COLORTERM=truecolor, and with AGWINTERM_THEME_COLORS=rrggbb;rrggbb (foreground;background), which the pty-host answers color queries with while no window is attached.

Font face and size are chosen in Properties. There is deliberately no zoom: a raster face only exists at the strike sizes its pack ships.

Shell profiles

profiles list reads the current catalog; profiles reload validates %LOCALAPPDATA%\agliteterm\profiles.json and replaces the catalog atomically. A missing file uses detected shells in memory. Neither operation writes the file; malformed or unreadable reloads refuse and keep the last good catalog. Startup logs malformed files and falls back to detected shells.

{"default":"Build","profiles":[{"name":"Build","command":"cmd.exe","args":["/k"],"cwd":"C:\\src"}]}

• The New Session dialog, the --profile NAME startup switch and session new --profile NAME use exact names (ASCII-case-insensitive). Unknown or empty names refuse; command plus profile is ambiguous and refuses.
• An explicit cwd overrides the profile cwd. Running sessions keep their resolved launch spec.
• Supported profile fields are name, command, args and cwd. Nonempty env or icon, elevation and unknown fields refuse rather than silently doing nothing.
• Limits: names max 128 UTF-8 bytes; app and cwd max 259; at most 16 args, each max 2047 bytes; file max 1 MiB, 128 profiles.
• An empty argument array keeps PowerShell prompt integration; nonempty arrays are passed unchanged. Arguments containing control characters refuse, because the launch-state TSV format cannot preserve them.

oh-my-posh

omp list discovers local .omp.json themes, first directory wins: POSH_THEMES_PATH, the normal winget/scoop/chocolatey locations, then app-data omp-themes.

omp set NAME [--persist] requests initialization through the stock PSReadLine idle reader in PowerShell 7 (PSReadLine 2.2.6–2.x).

• Completed input and previous completed switches are allowed; a nonempty editing buffer refuses without submitting or clearing the draft.
• Adopted, unsupported-reader, alternate-screen, readonly, exited and non-PowerShell panes refuse. Use config set omp-theme for future shells instead.
• A successful reply confirms that native initialization and its generated script completed. A claimed request without a timely result reports an unknown outcome; do not retry automatically.
• Persistence requires timely success, unchanged pane policy and no newer saved configuration.
• Theme content and OMP-generated shell code may execute commands; only apply themes you trust.

config get/set omp-theme reads or sets the path for eligible new PowerShell shells without initializing existing ones; none clears it. Persisted initialization is not injected into adopted shells or nonempty explicit profile argv. Paths must fit the host's encoded startup argument; unsupported or overlong paths refuse. A live write followed by a persistence failure reports both outcomes.

Captured-command replay

config set restore-commands true opts into replaying captured commands (K records) on a future fresh restore; the default is false. Review captured commands first. This does not immediately execute anything in existing panes.

The same opt-in turns on the quit-time capture: closing the window fills each real pane's slot from what that pane is running, so the replay has the close to work from.

Captured commands use legacy K records for ordinary lines and lossless K2 records for tabs or newlines; older builds ignore K2 records. The API field is capturedCommands in either case. See restore capture and the state file.