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
| Setting | Default | What 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_size | 13 | Font size in points (6–48). ⌘= and ⌘- zoom from here; ⌘0 comes back to it. |
background_opacity | 0.88 | How opaque the window's frosted glass is, from 0.2 (see-through) to 1 (solid). |
project_icons | true | Use each project's own icon for its tile in the rail. Off shows the project's initial. |
Terminal
| Setting | Default | What it does |
|---|---|---|
terminal.shell | "" | Shell program for new terminals. Empty uses $SHELL. |
terminal.env | {} | Extra environment variables for new terminals, like { "EDITOR": "nvim" }. |
terminal.scrollback | 10000 | Lines kept above the screen. |
terminal.line_height | 1.35 | Line height as a multiple of the font size (1–2.5). |
terminal.option_as_meta | false | Option 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_select | false | Copy text to the clipboard as soon as you select it. |
terminal.scroll_multiplier | 1.0 | Scroll speed of the mouse wheel and trackpad (0.1–10). |
terminal.font_ligatures | false | Ligatures (->, !=, =>) when the font has them. |
Editor
| Setting | Default | What it does |
|---|---|---|
editor.font_size | null | Editor font size in points. null follows font_size. |
editor.line_height | 1.55 | Line height as a multiple of the font size (1–3). |
editor.tab_size | 4 | Columns a tab character takes (1–16). Indentation itself is detected from each file. |
editor.minimap | true | Show the minimap. The header button flips it until you restart or change this. |
editor.blame_column | false | Show the blame column. Its header button flips it the same way. |
editor.inline_blame | true | Who last changed the cursor line, when and why, at the end of the line. |
editor.line_numbers | true | Line numbers in the gutter. |
editor.indent_guides | true | Faint vertical lines at each indentation level. |
editor.highlight_occurrences | true | Highlight other occurrences of the selection or the word under the cursor. |
editor.highlight_current_line | true | Shade the line the cursor is on. |
editor.cursor_blink | true | Blink the cursor while the editor has focus. |
editor.scroll_beyond_last_line | true | Let the last line scroll up to a third of the way up the view. |
editor.preview_tabs | true | Files clicked in Files or Search open in a preview tab that the next one replaces. Off always keeps tabs. |
editor.trim_trailing_whitespace | false | Remove spaces and tabs at the ends of lines when saving. |
editor.insert_final_newline | false | Make 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_ms | 1000 | How long to wait after you stop typing, with "after_delay". |
editor.max_file_size_mb | 8 | Bigger files show a note instead of opening (1–512 MB). |
Diff
| Setting | Default | What it does |
|---|---|---|
diff.view | "unified" | How diff tabs start: "unified" or "split" (side by side). |
Files
| Setting | Default | What it does |
|---|---|---|
files.show_ignored | true | Start 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_delete | true | Ask before moving files to the Trash. |
Search
| Setting | Default | What it does |
|---|---|---|
search.match_case | false | Start with Match Case on. |
search.whole_word | false | Start with Match Whole Word on. |
search.regex | false | Start 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_results | 20000 | Search stops after this many matches. |
Git
| Setting | Default | What it does |
|---|---|---|
git.avatars | true | Authors' 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_size | 300 | Commits loaded at a time in History. |
git.smart_commit | true | Committing with nothing staged commits all your changes. |
git.auto_fetch_minutes | 0 | Fetch 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
| Setting | Default | What 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_external | true | Show agents you started outside agex. See Agents running elsewhere. |
agents.notes_skill | true | Install the agex-notes skill so agents can read and update your notes. Off removes it. See Notes. |
Notifications
| Setting | Default | What it does |
|---|---|---|
notifications.enabled | true | Tell 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_finish | true | Notify when an agent finishes a task you gave it. |
notifications.on_question | true | Notify when an agent asks for permission or a choice. |
notifications.popups | true | Popups in the corner of the window. |
notifications.system | true | macOS notifications while agex is in the background. |
notifications.dock_badge | true | The number of agents waiting on you, on the Dock icon. |
notifications.dock_bounce | true | Bounce the Dock icon when an agent starts waiting on you. |
Status bar
| Setting | Default | What it does |
|---|---|---|
status_bar.visible | true | Show the status bar under the terminals. |
status_bar.session_pane | false | Move the agent's pieces into a Session view in the right panel. See Session panel. |
status_bar.context_meter | true | The context meter of the agent in front. |
status_bar.prompt_cache | true | How long that agent's prompt cache stays warm, for agents that write it down (Claude Code). |
status_bar.subagents | true | Its sub-agents at work, with a list (Claude Code, OpenCode, Kilo Code). |
status_bar.threads | true | The threads branched off its session, with a list (Claude Code, Codex, OpenCode, Kilo Code, Pi). |
status_bar.other_agents | true | The list of the project's other agents. |
status_bar.servers | true | The servers the project's agents and terminals started, with their ports. |
status_bar.keep_awake | true | The keep-awake coffee cup. |
status_bar.context_warning_percent | 70 | Context use, as a share of the window before compaction, that turns meters amber. |
status_bar.context_danger_percent | 90 | Context use that turns meters red. |
Keep awake
| Setting | Default | What it does |
|---|---|---|
keep_awake.display | true | Keep the display on too. Off lets it sleep while the Mac stays awake. |
keep_awake.glow | true | The warm glow around the window while it's on. |
keep_awake.sound | true | A sound as it turns on and off, in step with the glow. |
keep_awake.on_launch | false | Turn it on when agex starts. |
Menu bar
| Setting | Default | What it does |
|---|---|---|
menu_bar.visible | true | The agex icon in the macOS menu bar. |
menu_bar.waiting_count | true | How many agents wait on you, next to the icon. |
Command line
| Setting | Default | What it does |
|---|---|---|
cli.path | true | The 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.control | true | Let 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
| Setting | Default | What 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
| File | What's in it |
|---|---|
~/.config/agex/config.json | Your settings. |
~/.config/agex/state.json | Your projects and the sidebar layout. |
~/.config/agex/agents.json | Interrupted agents, for up to a week. |
~/.agex/notes/ | Your notes, one folder per project. |
~/Library/Caches/agex/icons | Project 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.