Settings & Themes

Aether’s terminal UI is powered by Wisp. UI preferences live in Wisp’s settings file, while agent configuration options (models, reasoning, servers) are advertised by the Aether ACP server at runtime.

UI settings

Stored in ~/.wisp/settings.json:

{
  "theme": { "source": "builtin", "id": "sage" },
  "statusLine": {
    "separator": " · ",
    "left": ["cwd", "gitRef"],
    "right": [
      "agent",
      "mode",
      { "type": "model", "maxWidth": 32 },
      "reasoning",
      "context",
      "serverHealth"
    ]
  },
  "keybindings": {
    "toggleGitDiff": "ctrl+d",
    "openPromptSearch": "ctrl+p"
  }
}

The top-level fields are theme, statusLine, contentPadding, and keybindings. contentPadding sets the number of blank columns of padding around the conversation content (default 2, minimum 2). Status line segments are described below.

Override the home directory with WISP_HOME:

export WISP_HOME=~/my-wisp-config

Status line segments

Each left and right entry is a segment. Shorthand names are strings; segments that take options use an object form.

Segment	Form	Description
cwd	"cwd" or { "type": "cwd", "maxWidth": 40 }	Current working directory (truncatable).
gitRef	"gitRef"	Active git branch or tag.
agent	"agent"	Active agent name.
mode	"mode"	Active mode (user-invocable agent profile).
model	"model" or { "type": "model", "maxWidth": 32 }	Active model (truncatable).
reasoning	"reasoning"	Current reasoning effort, when applicable.
context	"context"	Context window usage indicator.
serverHealth	"serverHealth"	MCP server connection health summary.
text	{ "type": "text", "value": "...", "style": "muted" }	Arbitrary fixed text. style is optional.

text segment styles: primary, secondary, muted, info, success, warning, error.

Keybindings

Global bindings accept strings such as "ctrl+g", "shift+backtab", or "esc". Supported keys are exit, cancel, submit, openCommandPicker, openFilePicker, toggleGitDiff, cycleReasoning, cycleMode, and openPromptSearch. Omitted bindings retain their defaults, and invalid bindings are ignored.

Themes

Select a built-in theme with "theme": { "source": "builtin", "id": "sage" }. For a custom Clankerdiff JSON theme, place the file in ~/.wisp/themes/ and select it with "theme": { "source": "file", "file": "custom.json" }.

• Directory~/.wisp/

  • settings.json
  • Directorythemes/

    • custom.json

The theme colors the entire UI: conversation text, syntax highlighting, diff rendering, status line, and overlays.

Settings overlay

Open with /settings. The overlay shows all configurable options:

• Model — Override the model used by the currently active agent runtime. Reasoning effort is adjusted from within the model pane, cycling it with Tab / Shift+Tab (also cyclable from anywhere with the global Tab binding)
• Mode — Switch to a different user-invocable agent profile, including its prompts, MCP servers, tools, model, and provider settings (also cyclable with Shift+Tab)
• MCP servers — View connected servers and their status
• Provider logins — Authenticate with providers that require it

These options are advertised by the agent — the terminal UI discovers them at session start. Different agents may expose different options.

How agent config works

The terminal UI doesn’t know about models or reasoning levels directly. Instead:

1. The agent sends SessionConfigOption entries describing available settings
2. The UI renders them in the settings overlay
3. When you change a value, the selection is sent back to the agent
4. The agent applies the change

The Tab (reasoning) and Shift+Tab (mode) shortcuts cycle through the most common agent-provided options. In Aether-backed sessions, mode changes are applied at the next safe prompt boundary. The current turn completes or is cancelled normally, and the next prompt uses the selected agent profile. Model changes remain scoped to the currently active agent runtime.

Authentication

Some agents or MCP servers require authentication. The settings overlay shows:

• Provider logins — Start OAuth flows or enter API keys
• MCP server auth — Authenticate individual MCP servers

Authentication state is managed by the agent, not stored locally.