# 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](agent-integration.md));
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.

![A program in a pane asks for the background, the foreground, the device attributes and the cursor position, and prints the four replies](img/qa-terminal-queries.png)

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.

```json
{"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](control-api.md#restore-capture) and [the state file](state-file.md).