Configuration and customization#

Automexia starts with useful defaults. Make it yours by choosing the appearance, shortcuts, and supported visual features that help you work. You can enable or disable supported features and adjust their presentation in the interface or settings file; some layout and input rules stay fixed.

Start with the first-session guide. Windows and macOS settings below describe planned support; platform compatibility needs separate validation.

Choose a customization path#

• Change something visible now: start with in-app controls and Customizations pages.
• Decide which surface owns a setting: use the interface-versus-file guide.
• Save a lasting preference: create a starter file, then change one value and reload safely.
• Copy an example: choose one small settings file for readable text, a compact workspace, colors, shell/editor, or scrollback.
• Find exact keys and defaults: use the configuration reference.

An in-app preview shows how a presentation choice could look; it does not change the program run by a shell. File settings can affect new sessions and may require reload or restart. Check the result before making another change.

Change settings while Automexia is open#

Current source offers direct controls plus Customizations pages for supported appearance and presentation features. The separate Settings → Profiles editor creates named session launch recipes. Neither interface edits every config.toml key: the default shell and many advanced settings remain file-owned. Confirm which pages your development build exposes.

• Text size: Ctrl+= or Ctrl+- changes the application-wide font-size preference; Ctrl+0 clears the saved override.
• Appearance: Alt+Shift+T switches light/dark appearance.
• Fonts: Ctrl+Shift+L lists available families. To choose one permanently, set [fonts].family in config.toml.
• Other interface actions: Ctrl+Shift+P opens the command palette. Search for an available action there; the palette does not run shell commands.
• Feature controls: open Customizations → Open Customizations, or use Ctrl+Shift+S (Cmd+Shift+S on macOS), to edit supported presentation switches and styles with a live sample.
• Configuration file: Ctrl+Shift+, opens config.toml in an external editor; it is a different route from the in-app Customizations pages.

On Linux, runtime font-size and appearance choices persist for the next launch. They can take precedence over matching config.toml values. The shortcut and palette actions available in a particular source build may differ; check its palette before relying on a key. Windows and macOS planned shortcuts are in Shortcuts and input.

Choose the right Customizations page#

Open a feature page, change one control, and compare its fictional preview before saving. On a narrow window the sample moves below the controls. You can use Tab/Shift+Tab to move among controls, arrows to change a choice, Space to toggle a switch, and Enter to edit a number. Escape cancels a draft or moves back through the page hierarchy. A Reset action previews defaults and asks for confirmation; Restore saved returns to the prior choices. A preview is not a provider query and never runs a command.

For Information tags, a tag can be shown/hidden, reordered, or given its own text, icon, color, source, and shape. The format also controls overall spacing and layout. A custom literal tag is display-only. Turn DevOps detection off if you do not want tool-context tags; OS, Git, user, and independent custom-text tags are separate. For Inline tables, border and stripe choices are visual; source text and selection remain the truth. The same principle applies to log/Kubernetes colors and command-result bands.

Installed extension packages may add preference pages. A visible setting only shows a saved choice; it does not prove that package code, provider login, or network behavior is active. Do not turn on an unfamiliar feature to test a remote environment. For table behavior, see Table output.

Choose how to change each part#

• Shell and starting directory: use --working-dir <PATH> or -e <PROGRAM> [ARGS...] for one launch. Set working-dir or [shell] in config.toml for the ordinary default. For a recurring alternative, use Settings → Profiles to choose its executable, arguments, and directory, or define it under [profiles] in the file.
• Text and cursor: adjust the terminal-wide font size or list fonts with the in-app keys above. Use line-height, [fonts], and [cursor] in the file for starting text size, font family, and cursor behavior.
• Colors and appearance: toggle light/dark appearance or use the Theme page for supported choices. Use theme plus a file under themes/ for a custom declarative palette. Window opacity is a separate [window] setting, not a theme color.
• Window, tabs, and panes: click tabs or panes and resize a window or split divider for the current layout. Use [window], [navigation], and [panel] for starting size, tab behavior, and pane spacing.
• History and clipboard: scroll, select, and copy in the terminal. Use scrollback-history-limit, enable-scroll-bar, and copy-on-select in the file to change retention and selection behavior.
• Keyboard actions: find occasional actions in the palette. Use [bindings] to remap a frequent action; the keyboard reference lists valid action names.

For temporary logging, use --enable-log-file or a log environment override. For a project-specific launch, choose a named profile or a launcher with CLI options instead of changing the default for every tab. Platform-specific config tables are available when a supported setting must differ by OS.

1. Create a starter config#

Run:

automexia --write-config

This creates a starter at the platform configuration root without overwriting an existing file.

Default roots:

The root can contain config.toml, themes/, extensions/, and logs/.

2. Open the config from Automexia#

Use:

• Windows: Ctrl+,
• Linux/BSD: Ctrl+Shift+,
• macOS: Cmd+,

The configured editor is used. By default the reference defines Notepad on Windows and vi on Unix unless you override [editor].

Example editor override:

[editor]
program = "code"
args = ["--wait"]

3. Start with a small config#

A practical starting point is:

line-height = 1.22
confirm-before-quit = true
scrollback-history-limit = 10000

[window]
width = 1280
height = 760
mode = "Windowed"
opacity = 1.0

[navigation]
mode = "Tab"
hide-if-single = false
max-tab-width = 200

[fonts]
size = 18.0
family = "Cascadia Code"

[cursor]
shape = "Block"
blinking = false

Do not copy the entire schema into your personal file. A smaller file is easier to reason about and lets new defaults/improvements apply to settings you never intentionally changed.

4. Choose the default shell#

Permanent shell selection lives under [shell]:

[shell]
program = "bash"
args = []

If shell.program is unset/empty, Automexia selects the user's default shell.

Use this setting for your everyday default. Use automexia -e ... when you need a different shell for only one launch.

The argument list is an exact vector, not a shell command string. Avoid embedding pipelines/redirection there; those belong in an actual shell session.

5. Configure fonts without breaking runtime zoom#

Example:

[fonts]
size = 18.0
family = "Cascadia Code"
features = ["calt=1", "liga=1"]

Runtime zoom changes the application-wide font-size preference:

• Windows/Linux/BSD: Ctrl+0, Ctrl+=/Ctrl++, Ctrl+-
• macOS: Cmd+0, Cmd+=/Cmd++, Cmd+-

Reset clears the saved override and returns to the configured size.

In the Linux development build, runtime font size and appearance preferences persist in state/user-preferences-v1.toml and can override corresponding config.toml values. Close Automexia before editing that state file and keep a backup.

6. Configure window appearance#

A simple window section might be:

[window]
width = 1280
height = 760
mode = "Windowed"
opacity = 1.0
decorations = "Disabled"

Other supported controls include blur, background image, colorspace, initial title, platform-specific decoration options, and quake-window dimensions. Use Configuration reference before changing advanced compositor/renderer settings; some are intentionally platform-specific.

Opacity or background image?#

Use window.opacity to change the whole background transparency. Use window.background-image when you want a local image behind terminal content. These are separate from terminal image previews, which display paths/protocol graphics as terminal content/overlays.

7. Configure navigation and pane appearance#

Example:

[navigation]
mode = "Tab"
current-working-directory = true
hide-if-single = false
use-split = true
unfocused-split-opacity = 0.7
max-tab-width = 200

Use current-working-directory = true when new sessions should inherit validated directory metadata where the action supports it. Remember that a clone split is still the explicit workflow when you want the active launch context reproduced.

Pane-local tab rails and operational footers follow responsive product rules and do not have a general “turn every visual invariant into a setting” model. This keeps the terminal grid/layout contract predictable.

8. Themes: fixed, adaptive, or forced#

The top-level config supports:

• theme = "name" to load themes/name.toml;
• adaptive-theme = { dark = "...", light = "..." } to switch based on appearance;
• force-theme = "dark" or "light" to force one appearance.

Choose one approach deliberately:

• Fixed theme when you always want one palette.
• Adaptive theme when you follow OS light/dark appearance.
• Force theme when app appearance must be independent of the host.

Both adaptive theme files must load successfully. Theme/config failures do not replace the current runtime state with partially parsed values; Automexia keeps the last known-good configuration.

9. Add a custom key binding#

Bindings live under [bindings]:

[bindings]
keys = [
  { key = "F5", with = "control | shift", action = "ReloadConfig" },
  { key = "O", with = "control | alt", action = "OpenCommandPalette" },
]

Use custom bindings for frequent operations with a clear personal mnemonic. Do not assign a new shortcut just because an action exists; the command palette is a lower-maintenance choice for occasional actions.

Bindings are explicit overrides. Unknown action names are rejected rather than silently removing a matching default. The full stable action-name list is in Keyboard and input reference.

10. Reload safely#

Configuration is bounded and validated. If a runtime reload encounters malformed/oversized config or a theme error, the last known-good runtime configuration remains active.

Use one of these approaches:

• restart Automexia after a configuration edit;
• invoke the registered reload action where exposed;
• bind ReloadConfig to a shortcut you prefer.

This is safer than partially applying whatever happened to parse before an error.

11. Environment overrides are for environment-specific behavior#

The configuration system also recognizes environment-level overrides such as:

• AUTOMEXIA_CONFIG_HOME — replaces the whole writable config root;
• AUTOMEXIA_LOG_LEVEL — overrides configured logging level.

Use these for controlled environments, test setups, portable launch scripts, or diagnostics. Prefer ordinary config.toml for normal personal preferences because it is easier to discover and maintain.

12. Copy-ready settings examples#

Use one example at a time as your complete config.toml; do not paste them all together. Each file sets only what the scenario needs. If you already have a config, back it up and copy only the settings you want. Then restart Automexia or use the reload action, and check the result. On Linux, a saved runtime font or appearance choice can override the matching file setting.

More readable text#

Use this when text feels small or lines feel crowded. Font size is the long-term starting size; Ctrl+= and Ctrl+- still adjust the active pane.

line-height = 1.3

[fonts]
size = 21.0

[cursor]
shape = "Block"
blinking = false

Compact workspace#

Use this when a smaller screen needs more terminal space. The tab bar hides when there is only one window tab; create another tab to see it again.

[window]
width = 1180
height = 720

[navigation]
mode = "Tab"
hide-if-single = true
max-tab-width = 160

[fonts]
size = 16.0

[panel]
padding = [4]

Your own colors#

Use a named theme when you want the same palette at every launch. Put this in config.toml:

theme = "quiet-blue"

[bindings]
keys = [
  { key = "F5", with = "control | shift", action = "ReloadConfig" },
]

Then create themes/quiet-blue.toml under the same configuration root. Create the themes/ directory first if it does not exist:

[colors]
background = "#101820"
foreground = "#e7eef5"
cursor = "#79c0ff"
selection-background = "#264a69"
selection-foreground = "#ffffff"

Restart or press Ctrl+Shift+F5 to reload after saving both files. On reload, an invalid theme leaves the last valid runtime configuration in place. Remove the theme line and reload to return to the default palette. See Configuration reference for more color keys and fixed versus adaptive themes.

Preferred shell and editor#

Use this when you want new sessions to start in Zsh and want the open-config action to use VS Code. Both zsh and the code command must be already installed and available to Automexia. Existing sessions keep the shell they started with.

[shell]
program = "zsh"
args = []

[editor]
program = "code"
args = ["--wait"]

On Linux, Ctrl+Shift+, opens the config in that editor; it is still a file edit, not a built-in settings form. Remove [shell] to return to your default login shell.

Review long output#

Use this when you read long build logs and often copy selected lines. More scrollback retains more rows in memory; it is not a durable log. With copy-on-select = true, selecting terminal text also replaces your clipboard, which may include sensitive output.

scrollback-history-limit = 20000
enable-scroll-bar = true
copy-on-select = true

If automatic copying is not useful, remove copy-on-select and use Ctrl+Shift+C after selecting text instead.

13. A maintainable customization workflow#

1. Run Automexia with defaults first.
2. Identify one concrete friction point.
3. Decide whether it is temporary (CLI/runtime shortcut) or permanent (config).
4. Add the smallest possible override.
5. Reload/restart and verify only that behavior.
6. Keep comments explaining non-obvious platform workarounds.
7. Periodically remove overrides that no longer solve a real problem.

For every available key, type, range, default, and platform override, use Configuration reference.