agex
Docs menuSettings

Reference

Settings

The settings page, the config.json file behind it, every setting with its default, keybindings, and the other files agex keeps.

Open settings

Press ⌘,, choose Agex › Settings…, or run Preferences: Open Settings in the command palette (⇧⌘P). Settings open as a page in an editor tab. They cover fonts, the window, terminals, editors, panels, Git, agents, notifications, the status bar and keybindings.

The settings page

Every setting is on one scrolling page, grouped by section, with a search box on top. The box is focused when the page opens, and it matches setting names and descriptions.

The menu on the left follows you: the section you're reading lights up and unfolds to its settings, and the one at the top of the view is marked. Click a section or a setting to scroll there. A setting you jump to is highlighted, and clicking a row on the page highlights it in the menu too.

Each row says what the setting does and has its control: a switch, a segmented choice, a number or text box, or a select box. Three select boxes do a little more:

  • Font lists monospace fonts first, each drawn in itself. Type to search every font.
  • Notification sound has ▶ on each sound to play it without closing the list, and ▶ beside the box plays the one in use.
  • Default agent shows each agent with its logo.

In any select box, ↑ ↓ and ↵ pick, and Esc closes.

A change applies at once. Changed settings carry a blue bar on the page, a dot in the menu and a count on their section. Hover a row to reset it to its default.

Settings that the file holds as maps or lists of objects (environment variables, custom agents and keybindings) open the JSON at their line.

In a narrow tab, the menu becomes a drawer, opened with the sidebar button in the header, and rows put their controls under the description.

The settings file

Click Open JSON on the page, or run Preferences: Open Settings (JSON), to open the file itself:

~/.config/agex/config.json

Edits apply when you save, whether in agex or in any other editor. The page writes into the same file and changes only the line it sets, removing it when you go back to the default, so your comments and order stay.

The file is JSON with comments (// and /* */) and trailing commas, and it only needs the settings you change.

Default Settings

Default Settings, in the JSON tab, or Preferences: Open Default Settings, opens every setting with its default and what it does. It's read-only and opens next to your settings, so you can copy across. It ends with every action you can bind and the keys it has now.

Example

{
  "font_size": 14,
  "terminal": { "cursor_shape": "beam", "copy_on_select": true, "env": { "EDITOR": "nvim" } },
  "editor": { "tab_size": 2, "minimap": false, "auto_save": "after_delay" },
  "files": { "exclude": [".DS_Store", ".git", "*.log"] },
  "git": { "pull_mode": "rebase", "auto_fetch_minutes": 10, "commit_message_command": "codex exec" },
  "agents": {
    "default": "codex",
    "custom": [{ "id": "codex", "name": "Codex", "command": "codex --full-auto" }],
    "hidden": ["goose"],
  },
  "notifications": { "sound": "Ping", "on_finish": false },
  "status_bar": { "context_warning_percent": 60 },
  "keybindings": {
    "cmd-shift-n": "agex::NewTerminal",
    "cmd-d": null,                                                    // unbind
    "cmd-shift-s": { "action": "editor::SaveFile", "context": "Editor" },
  },
}

Errors and older settings

A setting with a wrong value, or a name agex doesn't know, is skipped, and everything else still applies. The page shows each problem under its setting, the JSON tab lists them all, and a red pill in the top bar says how many there are until you fix them.

Settings from before the file had sections, such as "shell", "git_avatars" and "agents": [...], still work.

Settings reference

Fonts and window

SettingDefaultWhat it does
font_family""Monospace font for terminals, editors and diffs. Empty picks the first installed of JetBrains Mono, Geist Mono, SF Mono and Menlo.
font_size13Font size in points (6–48). ⌘= and ⌘- zoom from here; ⌘0 comes back to it.
background_opacity0.88How opaque the window's frosted glass is, from 0.2 (see-through) to 1 (solid).
project_iconstrueUse each project's own icon for its tile in the rail. Off shows the project's initial.

Terminal

SettingDefaultWhat it does
terminal.shell""Shell program for new terminals. Empty uses $SHELL.
terminal.env{}Extra environment variables for new terminals, like { "EDITOR": "nvim" }.
terminal.scrollback10000Lines kept above the screen.
terminal.line_height1.35Line height as a multiple of the font size (1–2.5).
terminal.option_as_metafalseOption sends Meta (ESC-prefixed keys) instead of typing ∂, ƒ, ©, …
terminal.cursor_shape"block"Cursor shape until a program sets its own: "block", "beam" or "underline".
terminal.copy_on_selectfalseCopy text to the clipboard as soon as you select it.
terminal.scroll_multiplier1.0Scroll speed of the mouse wheel and trackpad (0.1–10).
terminal.font_ligaturesfalseLigatures (->, !=, =>) when the font has them.

Editor

SettingDefaultWhat it does
editor.font_sizenullEditor font size in points. null follows font_size.
editor.line_height1.55Line height as a multiple of the font size (1–3).
editor.tab_size4Columns a tab character takes (1–16). Indentation itself is detected from each file.
editor.minimaptrueShow the minimap. The header button flips it until you restart or change this.
editor.blame_columnfalseShow the blame column. Its header button flips it the same way.
editor.inline_blametrueWho last changed the cursor line, when and why, at the end of the line.
editor.line_numberstrueLine numbers in the gutter.
editor.indent_guidestrueFaint vertical lines at each indentation level.
editor.highlight_occurrencestrueHighlight other occurrences of the selection or the word under the cursor.
editor.highlight_current_linetrueShade the line the cursor is on.
editor.cursor_blinktrueBlink the cursor while the editor has focus.
editor.scroll_beyond_last_linetrueLet the last line scroll up to a third of the way up the view.
editor.preview_tabstrueFiles clicked in Files or Search open in a preview tab that the next one replaces. Off always keeps tabs.
editor.trim_trailing_whitespacefalseRemove spaces and tabs at the ends of lines when saving.
editor.insert_final_newlinefalseMake sure the file ends with a newline when saving.
editor.auto_save"off"Save on its own: "off", "after_delay" or "on_focus_change".
editor.auto_save_delay_ms1000How long to wait after you stop typing, with "after_delay".
editor.max_file_size_mb8Bigger files show a note instead of opening (1–512 MB).

Diff

SettingDefaultWhat it does
diff.view"unified"How diff tabs start: "unified" or "split" (side by side).

Files

SettingDefaultWhat it does
files.show_ignoredtrueStart with Git-ignored files shown, dimmed. The eye button toggles it.
files.exclude[".DS_Store", ".git"]Names or globs never shown, like "*.log", "build" or "src/**/*.snap".
files.confirm_deletetrueAsk before moving files to the Trash.
SettingDefaultWhat it does
search.match_casefalseStart with Match Case on.
search.whole_wordfalseStart with Match Whole Word on.
search.regexfalseStart with Use Regular Expression on.
search.include""What files to include starts with, like "src, *.ts".
search.exclude""What files to exclude starts with, like "*.lock, dist".
search.max_results20000Search stops after this many matches.

Git

SettingDefaultWhat it does
git.avatarstrueAuthors' pictures in history, from GitHub and Gravatar. This sends hashed author emails to Gravatar and asks GitHub's API about the repository. Off shows initials only.
git.changes_view"list"How changes start: "list" or "tree".
git.pull_mode"default"What Pull and Sync do: "default" (plain git pull, so your git config decides), "merge" or "rebase".
git.history_page_size300Commits loaded at a time in History.
git.smart_committrueCommitting with nothing staged commits all your changes.
git.auto_fetch_minutes0Fetch in the background every this many minutes. 0 never fetches.
git.commit_message_command""Command that writes commit messages for the pen button. It gets the prompt as its last argument and the diff on stdin, and prints the message, like "codex exec" or "llm -m gpt-4o". Empty uses claude -p, else gemini -p.
git.commit_message_prompt""The prompt for that command. Empty asks for a summary line of at most 72 characters and, if needed, a short body.

Agents

SettingDefaultWhat it does
agents.default""The agent that ⇧⌘T and New agent start (claude, codex, gemini, …). Empty uses the first one found.
agents.custom[]Extra agent CLIs, or overrides of built-in ones with the same id. See Custom agents.
agents.hidden[]Ids of detected agents to hide, like ["goose"].
agents.detect_externaltrueShow agents you started outside agex. See Agents running elsewhere.
agents.notes_skilltrueInstall the agex-notes skill so agents can read and update your notes. Off removes it. See Notes.

Notifications

SettingDefaultWhat it does
notifications.enabledtrueTell you when an agent you aren't looking at finishes a task or asks you something. Off turns everything below off.
notifications.sound"Glass"A sound from /System/Library/Sounds (Glass, Ping, Hero, Submarine, …). Empty is silent.
notifications.on_finishtrueNotify when an agent finishes a task you gave it.
notifications.on_questiontrueNotify when an agent asks for permission or a choice.
notifications.popupstruePopups in the corner of the window.
notifications.systemtruemacOS notifications while agex is in the background.
notifications.dock_badgetrueThe number of agents waiting on you, on the Dock icon.
notifications.dock_bouncetrueBounce the Dock icon when an agent starts waiting on you.

Status bar

SettingDefaultWhat it does
status_bar.visibletrueShow the status bar under the terminals.
status_bar.session_panefalseMove the agent's pieces into a Session view in the right panel. See Session panel.
status_bar.context_metertrueThe context meter of the agent in front.
status_bar.prompt_cachetrueHow long that agent's prompt cache stays warm, for agents that write it down (Claude Code).
status_bar.subagentstrueIts sub-agents at work, with a list (Claude Code, OpenCode, Kilo Code).
status_bar.threadstrueThe threads branched off its session, with a list (Claude Code, Codex, OpenCode, Kilo Code, Pi).
status_bar.other_agentstrueThe list of the project's other agents.
status_bar.serverstrueThe servers the project's agents and terminals started, with their ports.
status_bar.keep_awaketrueThe keep-awake coffee cup.
status_bar.context_warning_percent70Context use, as a share of the window before compaction, that turns meters amber.
status_bar.context_danger_percent90Context use that turns meters red.

Keep awake

SettingDefaultWhat it does
keep_awake.displaytrueKeep the display on too. Off lets it sleep while the Mac stays awake.
keep_awake.glowtrueThe warm glow around the window while it's on.
keep_awake.soundtrueA sound as it turns on and off, in step with the glow.
keep_awake.on_launchfalseTurn it on when agex starts.
SettingDefaultWhat it does
menu_bar.visibletrueThe agex icon in the macOS menu bar.
menu_bar.waiting_counttrueHow many agents wait on you, next to the icon.

Command line

SettingDefaultWhat it does
cli.pathtrueThe agex command in your PATH (Add agex to PATH).
cli.folder""Where the command goes. Empty uses the first of /usr/local/bin, /opt/homebrew/bin, ~/.local/bin and ~/bin that's in your PATH.
cli.controltrueLet the agex command start agents, jump to them, resume sessions and open projects in the app. Off, it can still read your history and notes.

Scripts

SettingDefaultWhat it does
scripts.package_manager""What runs package.json scripts: "npm", "pnpm", "yarn" or "bun". Empty goes by the project's packageManager field or lockfile.

Keybindings

keybindings maps keystrokes to actions. Your bindings win over the built-in ones, and null removes one.

{
  "keybindings": {
    "cmd-shift-n": "agex::NewTerminal",
    "cmd-d": null,
    "cmd-shift-s": { "action": "editor::SaveFile", "context": "Editor" },
  },
}
  • Write keystrokes like "cmd-shift-t" or "ctrl-tab", or a sequence like "cmd-k cmd-s".
  • For a binding that works in only one place, give a context: "Terminal", "Editor", "TextInput" or "Workspace".
  • Every action and its current keys are listed at the end of Default Settings.

For the built-in keys, see Keyboard shortcuts.

Other files agex keeps

FileWhat's in it
~/.config/agex/config.jsonYour settings.
~/.config/agex/state.jsonYour projects and the sidebar layout.
~/.config/agex/agents.jsonInterrupted agents, for up to a week.
~/.agex/notes/Your notes, one folder per project.
~/Library/Caches/agex/iconsProject icons, as 144px tiles.

An agent only appears once its executable is found. After installing a new one, choose Rescan for agents in the New agent menu.