Settings and themes

Impulse keeps its settings in one JSON file and shows them in a searchable Settings tab, where every change applies as soon as you make it. This page covers the Settings tab, editing settings.json directly, every setting and its default, the built-in themes and how to write your own, and how to change keyboard shortcuts.

#Open Settings

Settings opens as a tab in the current window, next to your terminals and editors. Each window has at most one Settings tab; opening it again brings the existing one forward.

• Press ⌘, or choose Impulse › Settings….
• From the command palette (⇧⌘P), run Open Settings.
• To jump straight to one setting, run Find a Setting… in the palette (or type set: in the palette) and pick it. See Find a setting.

The left column lists the categories: General, Editor, Terminal, Appearance, Git, Automation, Language Servers and Advanced. A number next to a category counts the settings in it that differ from their defaults. At the bottom of the column are the Only changed settings checkbox and the Open settings.json link.

Each setting row shows its title, its settings.json key in small type (you can select and copy it), a short description, and its control. A setting you've changed from its default has an accent-colored bar on its left edge and a Reset to default button (a circular arrow) on its right. There is no "reset everything" button; see Start over for that.

How the controls work:

• Switches and menus apply when you click them.
• Number fields take a typed value when you press Return or move out of the field; the arrows beside them step the value. Values outside the allowed range are clamped to the nearest limit.
• Text fields (such as Quick terminal shortcut) apply when you press Return or move out of the field.
• Font menus list the monospaced font families installed on your Mac. JetBrains Mono comes with Impulse.
• Scratch folder takes a typed path (~ works) or a folder you pick with Choose….

Impulse saves settings.json a moment after each change; you never need to save Settings yourself.

#Find a setting

When you open Settings, the cursor is in the Search settings field at the top of the left column. Type part of a setting's title, its key, its section name or a word from its description. Results come from every category and are grouped under headings like Editor › Font and Terminal › Font. Press Esc to clear the search, or click a category to leave the results.

• Only changed settings lists every setting you've changed, across all categories. Combined with a search, it narrows the results to changed settings that match.
• The Automation, Language Servers and Advanced categories are separate pages and don't appear in search results.

From the command palette, type set: followed by part of a setting's name (for example set:minimap), or run Find a Setting…. Changed settings are marked "changed" in the list. Choosing one opens the Settings tab with that setting's key in the search field.

#Edit settings.json

Every setting lives in one file:

~/Library/Application Support/impulse/settings.json

The development build ("Impulse Dev") uses ~/Library/Application Support/impulse-dev/settings.json instead, which is copied from the release build's file the first time the dev build runs.

Impulse writes the file as formatted JSON with the keys sorted, and it writes every setting, so the file always shows the current value of each one. The file is readable only by you (permissions 0600). If settings.json is a symbolic link (for example into a dotfiles repository), Impulse writes through the link to the real file instead of replacing the link.

#Open it in the editor

Open the file in an Impulse editor tab with any of these:

• The Open settings.json link at the bottom of the Settings tab's left column.
• Settings › Advanced › settings.json.
• The palette command Open settings.json.
• The Open Settings File button on the warning banner described below.

If the file doesn't exist yet, Impulse writes it first. In the editor, the file is checked against a schema of every setting: you get completions for keys and values, descriptions when you hover over a key, and warnings for wrong types, values that aren't allowed, and numbers outside their range.

settings.json is plain JSON. Comments and trailing commas aren't allowed.

#When your edits apply

Impulse watches the file. When you save it, from Impulse's editor or any other app, the new values apply to every window within a moment, the theme (color_scheme) included.

#Values Impulse can't use

• A key whose value has the wrong type (for example "font_size": "big") falls back to that setting's default. The rest of the file still loads.
• A number outside its setting's range (the Values column in the tables below) is clamped to the nearest limit, the same as in the Settings tab.
• A value that isn't one of a menu's choices is kept, and the menu in Settings shows it as an extra item.
• Keys Impulse doesn't know are ignored, and they disappear the next time Impulse saves the file.

#If the file can't be read

If settings.json isn't valid JSON (a missing comma, a stray comment) or can't be read, a banner appears under the window's titlebar: Settings file could not be loaded, with Open Settings File and a dismiss button. The banner says which settings are in use; hover over it to see the error.

• If this happens when Impulse starts, Impulse uses the default settings ("Using the default settings") and copies the broken file next to the original as settings.invalid-<timestamp>.json, so nothing you wrote is lost. The banner shows where the copy is, for example ~/Library/Application Support/impulse/settings.invalid-1759834200.json.
• If the file breaks while Impulse is running (you saved it mid-edit), Impulse keeps the settings it already had ("Keeping the settings Impulse already had").

Either way, Impulse stops saving settings until the file is fixed, so it never overwrites your broken file with defaults. Changes you make in the Settings tab meanwhile apply but aren't saved. Fix the file and save it; Impulse reloads it and the banner goes away.

#Start over

To return every setting to its default, quit Impulse and delete settings.json. Impulse starts with the defaults and writes a new file the next time a setting changes.

#Settings reference

The tables below list every setting in the order the Settings tab shows them. "Key" is the name in settings.json. Switches are true or false in the file.

#General

#Quick terminal

#Startup

#Window

#Sidebar

#Workspaces

#Editor

#Font

#Indentation

File types under Automation can set a different tab width or indentation for files that match a pattern.

#Display

#Scrolling

#Cursor

#Behavior

#Terminal

#Font

#Cursor

#Blocks & input

See Terminal for command blocks, the input bar, history and completions.

#Agents

#Behavior

#Clipboard

#Bell & notifications

#Scrollback

#Appearance

#Git

#Commit

#Remote

#Tags

#Review

See Git for committing, pulling and tags, and Review for the diff view.

#Automation

The Automation page has two lists, each with an Add button. Fields save when you press Return or move out of them, and the trash button removes a row.

Both lists match files by a simple pattern:

• * matches every file.
• *.ts matches files ending in .ts (ignoring case).
• Anything else must equal the file's name exactly, for example Makefile or package.json.

Both kinds of command run only for files inside folders you trust. They run in the folder that contains the saved file, with the arguments you give them; write {file} in an argument where the saved file's full path should go (Impulse doesn't add it otherwise). The command field is split into words like a shell would (quotes group words), but the command isn't run through a shell, so pipes, && and variables don't work. The command must be a plain program name or an absolute path. A plain name is looked up on your login shell's PATH, the same one language servers use, so tools from Homebrew, npm and the like are found even when Impulse starts from the Dock. Output isn't shown, but when a command fails, a notification names it and shows the first line of its error output. A formatter that runs for more than a minute is stopped.

#Commands on save

"Run after saving files that match a pattern, e.g. a linter or code generator." Each row has a Name, a pattern, a command with its arguments, and a Reload checkbox ("Reload the file afterwards (for commands that rewrite it)"). With Reload on, the editor shows what the command wrote to the file, unless you've kept typing since the save.

In settings.json, this list is commands_on_save:

"commands_on_save": [
  {
    "name": "Lint",
    "command": "npx",
    "args": ["eslint", "--fix", "."],
    "file_pattern": "*.ts",
    "reload_file": true
  }
]

#File types

"Indentation and a formatter per file pattern, overriding the editor defaults." Each row has a pattern, a Tab width menu (default, 2, 4 or 8), an Indent menu (default, Spaces or Tabs), and an optional formatter command.

When you save a file that matches, its formatter runs before the commands on save, and the editor then shows the formatted file (unless you've kept typing since the save). The first row whose pattern matches and that has a formatter is used.

The Tab width and Indent choices apply to editors whose file matches, in place of the Editor › Indentation settings; "default" keeps those. Each comes from the first matching row that sets it, so a *.go row with Tabs and a later *.go row with tab width 8 combine. Open editors change as soon as you edit a row.

In settings.json, this list is file_type_overrides:

"file_type_overrides": [
  {
    "pattern": "*.md",
    "tab_width": 2,
    "use_spaces": true,
    "format_on_save": { "command": "npx", "args": ["prettier", "--write", "{file}"] }
  }
]

#Language Servers

The Language Servers page shows the language servers that give the editor completions, diagnostics, go to definition and formatting. See Editor for what they do.

• Managed by Impulse lists the web-language servers Impulse installs with npm into its own folder (~/Library/Application Support/impulse/lsp, or ~/.local/share/impulse/lsp if an earlier install is there): typescript-language-server, intelephense, vscode-html-language-server, vscode-css-language-server, vscode-json-language-server, vscode-eslint-language-server, tailwindcss-language-server, vue-language-server, svelteserver, graphql-lsp, emmet-ls, yaml-language-server, docker-langserver and bash-language-server. Each row shows where the server was found, or "Not installed".
• Install All installs or updates all of them with npm. It needs Node.js and npm; without npm the button is disabled and the page says "Install Node.js (npm) to manage these." When the install finishes, the page shows "Language servers installed." or the error npm reported. The palette command Install Web LSP Servers does the same thing.
• From your system lists the servers you install yourself with a package manager such as Homebrew or rustup: rust-analyzer, pyright-langserver, clangd and sourcekit-lsp (which comes with Xcode and the Command Line Tools). Impulse looks for them on your login shell's PATH.

Language servers only start in folders you trust.

#Advanced

The Advanced page links to the two places where you edit settings that don't fit the Settings tab:

• Keyboard shortcuts: "Rebind any command, and add shortcuts that run shell commands." See Customize keyboard shortcuts.
• settings.json: "Every setting as JSON, with completion and validation in the editor." See Edit settings.json.

#Keys that only appear in settings.json

#Themes

A theme colors the whole window: the window chrome, the editor, the terminal (including its 16 ANSI colors), Markdown previews, the input bar's syntax colors and the review diff. Impulse has 19 built-in themes and loads your own from a folder.

#Choose a theme

1. Open Settings (⌘,) and select Appearance.
2. Choose a theme from the Theme menu.

The theme applies at once to every window and to the quick terminal. Reset to default next to the menu goes back to Nord.

You can also set color_scheme in settings.json to a theme's id. The theme changes as soon as you save the file.

#Built-in themes

The menu lists them in this order. A theme's variant also sets the window's light or dark appearance.

The four light themes switch the whole window, chrome included, to a light appearance. Here is Harbor:

In settings.json, a few alternate spellings of the ids also work, such as rose_pine, tokyonight or github_dark.

#Create your own theme

Themes are TOML files. To add one:

1. Create the folder ~/Library/Application Support/impulse/themes if it doesn't exist. (The dev build reads the same folder.)
2. Save a theme file there, for example campfire.toml. The file name without .toml, in lowercase, is the theme's id: Campfire.toml is the theme campfire.
3. In Settings › Appearance, choose it from the Theme menu. If the Settings tab was already open, close it and open it again so the menu picks up the new file.

The Theme menu lists your theme under the name inside the file. Your themes are listed after the built-in ones.

A file with the same id as a built-in theme (for example nord.toml) replaces that built-in theme.

Impulse reads the file each time the theme is applied. After editing it, choose another theme and then yours again, or restart Impulse.

If the file can't be parsed (a TOML syntax error, a missing required key or a value of the wrong type), Impulse uses the built-in theme with the same id, or Nord, and a notice at the bottom of the window names the file and the problem, such as "palette.accent is missing or isn't a string" or a syntax error with its line and column. Click Open File in the notice to fix it, then choose the theme again. Write every color as a hex value; color names and other formats aren't understood.

A complete theme needs only a name, a variant and ten colors. Everything else is worked out from them:

name = "Campfire"
variant = "dark"

[palette]
bg = "#1f1d1a"
fg = "#e8dfd0"
accent = "#e0a458"
red = "#e06c5b"
orange = "#e0915b"
yellow = "#e0c25b"
green = "#9cc27a"
cyan = "#6cc2b8"
blue = "#7aa6d6"
magenta = "#c58fc4"

Add the optional [ui], [syntax] and [terminal] tables to set specific colors yourself:

[ui]
selection = "#e0a45840"
fg_comment = "#8a8072"

[syntax]
keyword = "#c58fc4"
string = "#9cc27a"

The built-in themes are good starting points; their files are in Impulse's source at impulse-macos/Sources/ImpulseKit/Resources/Themes/.

#Theme file reference

Colors are hex strings: "#RRGGBB", or "#RRGGBBAA" with an alpha channel (for example a translucent selection, "#68B0E050").

#Top level

#[palette]

#[ui]

All optional.

#[syntax]

All optional. These color the editor, previews and diffs.

#[terminal]

Optional, but if you include it you must give all 16 colors: black, red, green, yellow, blue, magenta, cyan, white, bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan and bright_white. The names match Alacritty, Ghostty and Kitty, so you can copy a palette from those.

Without a [terminal] table, Impulse builds the 16 colors from the palette: black is bg lightened by 10%, red through cyan (normal and bright) are the palette hues, white is fg_muted, bright black is fg_comment, and bright white is fg. The terminal's default text and background are always fg and bg.

#Customize keyboard shortcuts

Every command in the menus and the command palette that has (or can have) a shortcut is listed in the Keyboard Shortcuts tab, where you can rebind it, remove its shortcut, or add shortcuts that run shell commands. For the full list of default shortcuts, see Keyboard shortcuts.

#Open the Keyboard Shortcuts tab

• Press ⌥⌘, or choose Impulse › Keyboard Shortcuts….
• Run Keyboard Shortcuts from the command palette.
• Click Keyboard shortcuts in Settings › Advanced.

Commands are grouped under Tabs, Panes, Blocks, Terminal, Editor, Navigation, Git, Font and App. Each row shows the command's name, its id in small type, and its shortcut, or Unbound if it has none.

To find a command, type in Search commands (it matches names, ids, categories and shortcuts), or click Search by keys and press a shortcut to list only the commands that use it. Click the small x next to the shortcut filter to clear it.

#Change a shortcut

1. Click the command's shortcut (or Unbound). It changes to "Press keys… (⌫ removes, esc cancels)".
2. Press the new shortcut.

The new shortcut works right away, in the menus, the command palette and the terminal. It must include ⌘, ⌃ or ⌥; only the function keys F1–F12 can be used alone. If you press a key without one of those modifiers, Impulse beeps, the chip says why (for example "⇧A needs ⌘, ⌃ or ⌥"), and it waits for another shortcut; press Esc to stop.

A changed shortcut gets an accent bar on its left edge and a Reset to default button (a circular arrow) on its right.

#Remove or reset a shortcut

• To remove a shortcut, click it and press ⌫ (Delete) on its own. The command shows Unbound.
• To go back to the default, click Reset to default on the command's row. Recording the default shortcut again has the same effect.
• Press Esc, or click anywhere else, while recording to cancel without changing anything.

#Conflicts

When two commands share a shortcut, both rows show a warning triangle. Hover over it to see the other command ("Also bound to …"). Conflicts include the shortcuts you add under Run in Terminal, and the shortcuts you can't change, such as ⌘1–⌘9, ⌘O or ⌘Q ("Also bound to Quit Impulse (can't be changed)"; see What you can't change).

Only one command can run for a given shortcut, so change one of them. A Run in Terminal shortcut takes priority over a built-in command with the same keys.

#Run a shell command from a shortcut

The Run in Terminal section at the end of the tab holds shortcuts that run a command for you. For example, to run the trailhead tests with ⌃⌥T:

1. Click Add next to RUN IN TERMINAL. A row named "New shortcut" appears.
2. Change the name to Run tests.
3. In the Command field, type npm test, then press Return.
4. Click the row's shortcut chip (Unbound) and press ⌃⌥T.

Pressing the shortcut runs the command in the focused terminal, as if you had typed it at the prompt. If no terminal is focused (you're in an editor, for example), the focused terminal is still running something, or the input bar is off (see Classic prompt mode), it opens a new terminal tab in the current tab's folder (a terminal's working directory, or the folder of the file you're editing) and runs the command there. Each entry with a name also appears in the command palette under "Custom", showing its shortcut.

The Command field is a command line for your shell, kept as you type it: quotes, pipes, && and variables work, for example npm run lint && npm test. Click the trash button to remove an entry.

#Shortcuts in settings.json

Your changes are stored in settings.json, so you can also edit them there or copy them to another Mac.

keybinding_overrides maps a command id (shown under each command in the Keyboard Shortcuts tab) to a shortcut. Only changed shortcuts are stored; "none" removes a command's shortcut.

"keybinding_overrides": {
  "split_right": "Cmd+Alt+D",
  "git_fetch": "Ctrl+Alt+F",
  "fullscreen": "none"
}

Write a shortcut as modifiers and a key joined by +:

• Modifiers: Cmd (or Command), Ctrl (or Control), Alt (or Option, Opt) and Shift, in any case.
• Keys: a single character (D, 5, ,, =), or one of Tab, Left, Right, Up, Down, Space, Return (or Enter), Escape (or Esc), Delete (or Backspace) and F1–F20.
• The plus key itself is written Cmd++.

custom_keybindings holds the Run in Terminal entries:

"custom_keybindings": [
  { "name": "Run tests", "key": "Ctrl+Alt+T", "command": "npm test" }
]

#What you can't change

• The standard macOS items: About Impulse, Hide Impulse (⌘H), Hide Others (⌥⌘H), Quit Impulse (⌘Q), Open… (⌘O), Close Window (⇧⌘W), Minimize (⌘M), the Edit menu's Undo, Redo, Cut, Paste and Match Style and Select All, and Impulse Help (⌘?). (Copy, Paste, Find… and Go to Line… can be changed.)
• Tab 1 through Tab 9 (⌘1–⌘9) in the Window menu.
• Keys inside a panel or field, such as the Review keys, the Changes panel keys, the input bar keys and hints mode. These are listed in Keyboard shortcuts.
• Commands that are only in the command palette (for example Trust This Folder… or Import Shell History) can't have a shortcut. Run them from the palette.

#Related

• Keyboard shortcuts
• Accessibility
• Command palette
• Editor
• Terminal
• Getting started