Configuration

Macros has no settings panel. Your configuration is a Steel program — init.scm — evaluated at startup. It can set options, rebind keys, define commands, load themes, and call any of the editor's primitives.

Config file location#

The built-in defaults load first (they ship inside the binary). Then your personal init.scm loads and can override anything. Macros looks for it in the first of:

Platform	Path
macOS / Linux	~/.config/macros/init.scm
with $XDG_CONFIG_HOME set	$XDG_CONFIG_HOME/macros/init.scm
Windows	%APPDATA%\macros\init.scm

If none exists, the editor just uses its defaults. Create the file and start adding to it.

Splitting your config across files#

;; Resolved relative to the config directory:
(include "keys.scm")
(include "lsp.scm")

;; Absolute paths work too:
(load "/Users/me/dotfiles/macros/extra.scm")

Editor options#

Set options with (set-option "name" value). Values are typed — pass a number, a boolean (#t / #f), or a string, and the value is coerced to the option's type when you set it. (A quoted "string" works for any option too, so older configs keep running.) These are the defaults, set in the built-in config:

;; Theme — see Themes & faces
(load-theme "macros-dark")

;; Typography
(set-option "font-size"   13)
(set-option "line-height" 20)
(set-option "tab-width"   4)

;; Completion popup (corfu-style) — see Completion
(set-option "completion-style"       "popup")  ; "popup" or "minibuffer"
(set-option "completion-auto"        #t)       ; pop up while typing
(set-option "completion-auto-prefix" 2)        ; min chars before auto-popup
(set-option "completion-max-rows"    10)
(set-option "completion-show-detail" #t)       ; signature/type beside name
(set-option "completion-show-kind"   #t)       ; kind tag (fn, var, kw, …)

;; Cursor
(set-option "cursor-style" "auto")  ; "auto" | "bar" | "block"
(set-option "cursor-width" 2)       ; bar width in px

;; Gutter & chrome
(set-option "line-numbers"  #t)
(set-option "scroll-bar"    #t)
(set-option "divider-width" 1)      ; width of the split-window divider

;; Files on disk
(set-option "auto-revert"   #f)     ; re-read a buffer when its file changes on disk

;; Helm selection UI — see Helm
(set-option "helm-fuzzy"  #t)       ; fuzzy (nucleo) vs substring matching
(set-option "helm-height" 0.5)      ; fraction of the window height

Reading an option#

Read an option back from Scheme with (get-option "name"). It returns the current value as a native boolean / number / string, or #f if the option isn't set:

(when (get-option "completion-auto")
  (message "auto-completion is on"))

Per-mode options#

Append :mode-name to scope an option to one major mode. For example, the dired sidebar turns its line-number gutter off:

(set-option "line-numbers:dired-sidebar-mode" #f)

Watching the filesystem#

Macros watches the filesystem so the editor stays in sync with changes made outside it (a git checkout, a code formatter, a build step, another editor).

Auto-revert is opt-in (Emacs global-auto-revert-mode). Turn it on with:

(set-option "auto-revert" #t)

When a file you're visiting changes on disk and the buffer has no unsaved edits, Macros re-reads it automatically, keeping point where it was. A buffer with unsaved changes is never clobbered — instead you get a one-line warning, and you can reconcile with M-x revert-buffer (:e!) when ready. Macros' own saves don't trigger a spurious revert (the on-disk text already matches the buffer).

Live sidebar/dired refresh is always on — no option needed. While the file tree or a dired buffer is open, creating, renaming, or deleting files in the directories it shows refreshes the view automatically. The refresh never steals focus: if the sidebar is in another pane while you edit, it updates in place and your cursor stays put.

Session state#

Some state persists across restarts automatically, no configuration required:

• Cursor position — when you reopen a file, point jumps back to where you left it (Emacs save-place-mode).
• Recent files — the recent-files ring survives a restart (Emacs recentf).

Both are stored in your config directory, in ~/.config/macros/saveplace and ~/.config/macros/recentf, and updated as you save.

Turning on modal editing#

Macros uses standard Emacs keybindings by default. For Vim-style modal editing, enable evil-mode in your config:

(evil-mode)
;; ...and (evil-disable) turns it back off.

This is vanilla evil-mode — plain Vim keys, no leader. See Modal editing for the full picture.

A starter init.scm#

;; ~/.config/macros/init.scm
(load-theme "macros-dark")
(set-option "font-size" 14)

;; A personal binding: jump to definition.
(bind-key "fundamental" "ctrl-c d" 'lsp-find-definition)

;; A command of your own, callable with M-x insert-date.
(define (insert-date)
  (insert-string (call-process "date" '("+%Y-%m-%d"))))

Reload by restarting, or evaluate expressions live with M-: (eval-expression). For the full API, see Scripting with Steel.

For a complete, lived-in config — evil-mode, a Spacemacs-style SPC leader, custom commands, and per-mode LSP/Org bindings, annotated piece by piece — see Example config.