init.el

require 'package loads the built-in package manager.

package-archives declares the two repositories packages are fetched from: GNU ELPA (the official, copyright-assigned archive) and MELPA (the large community archive). Each entry is a (name . url) cons cell.

package-quickstart makes package.el maintain a single quickstart file containing package autoloads, load paths, and the activated package list. Loading that compiled bundle is much faster than scanning every installed package directory on every startup.

load is given the suffix-less name so it appends load-suffixes itself — trying package-quickstart.elc then package-quickstart.el — which keeps the compiled-first preference and lets native-comp swap in a .eln when one exists. With NOERROR, load returns nil if neither file exists, and only then — a first run or after deleting the quickstart file — does it fall back to a full package-initialize followed by package-quickstart-refresh.

Self-bootstrapping: if use-package isn't installed yet (first ever launch), download the archive contents index (package-refresh-contents) and install it. On every subsequent launch the unless is a no-op.

require then loads it, and use-package-always-ensure t makes every use-package form auto-install its package from ELPA if missing.

Turns off Emacs's automatic file~ backup copies, which otherwise litter every directory you edit in. Pure preference.

Lets you answer the long yes-or-no-p prompts ("Quit? (yes or no)") with a single y/n instead of typing the whole word plus RET.

Modern Emacs (28+) exposes the use-short-answers variable, so when it's boundp just set it. On older Emacs the variable doesn't exist, so the else branch falls back to aliasing yes-or-no-p straight to the already-short y-or-n-p.

Enables Emacs's own mouse reporting in the terminal, so the wheel arrives as real mouse-4/mouse-5 events that route to mwheel-scroll.

Tunes scrolling so the view moves, not point:

• mouse-wheel-follow-mouse — scroll the window under the pointer.
• mouse-wheel-progressive-speed nil — constant speed; don't accelerate on fast spins.
• mouse-wheel-scroll-amount — 2 lines per notch; Shift+wheel = 1 line; Ctrl+wheel = text zoom.
• scroll-conservatively 101 + scroll-step 1 — scroll one line at a time for keyboard motion, never recenter with a jump.
• scroll-margin 0 — let the cursor reach the very top/bottom edge before the view is dragged.
• make-cursor-line-fully-visible nil — don't force a recenter after a wheel scroll.

display-line-numbers-type t selects absolute line numbers (switch to 'relative or 'visual for Vim-style relative numbering).

global-display-line-numbers-mode shows them in the gutter everywhere; global-hl-line-mode highlights the line point is on.

recentf tracks recently opened files (consumed by consult-recent-file at SPC f r). :ensure nil because it ships with Emacs. :custom raises the remembered count to 100; :init (recentf-mode 1) turns it on.

The :config block fixes a multi-instance race. Each Emacs holds its own in-memory recentf-list and overwrites the shared save file on exit, so the last one to quit would erase the other's history.

• mem snapshots this instance's list.
• recentf-load-list re-reads what's currently on disk.
• append + delete-dups merges both, then seq-take caps it at the max.

Installs the doom-themes pack, enables bold and italic face variants, and loads doom-one (the dark theme from Doom Emacs). The t second argument to load-theme means "no confirmation, trust this theme."

nerd-icons supplies the glyph fonts that the modeline and dirvish draw file-type icons from.

doom-modeline is the rich status bar matching the theme. :after nerd-icons guarantees the icon library loads first; :init activates the mode.

Evil brings modal Vim editing. Settings are in :init because they must be set before the package loads:

• evil-want-integration t — load Evil's integration layer.
• evil-want-keybinding nil — required so that evil-collection (next) provides the keybindings instead of Evil's own defaults; the two would clash otherwise.
• evil-want-C-u-scroll t — restore Vim's C-u half-page scroll (Emacs normally uses C-u as a prefix arg).
• evil-echo-state nil — don't print -- INSERT -- etc. in the echo area (the modeline already shows the state).

:config (evil-mode 1) turns it on globally.

evil-collection supplies consistent Evil bindings for hundreds of built-in and third-party modes (dired, help, magit, …). :after evil orders it after Evil.

delq 'magit … removes magit from the list of modes it will touch before evil-collection-init applies the rest.

In GUI Emacs, cursor-type alone changes the cursor shape — but in emacs -nw it does nothing. This package emits DECSCUSR escape sequences on each Evil state change so the host terminal's cursor reflects the mode:

• normal / visual / motion → block
• insert → vertical bar
• replace / operator → underline (hbar)
• emacs state → hollow box

etcc-use-blink nil forces the steady DECSCUSR codes (ESC [ 2/4/6 q) in every state — no blinking.

evil-surround ports Vim surround operations: ys adds, cs changes, and ds deletes surrounding pairs; visual-state S surrounds the selected region.

evil-commentary adds comment operators: gcc toggles the current line, gc{motion} comments a motion, and gc works on a visual selection using the major mode's comment syntax.

evil-goggles briefly highlights the text affected by edits such as yank, delete, change, paste, and indent. Diff faces make additions/deletions easy to spot, while pulse animation is disabled to keep terminal redraws cheap.

A vertical split that also follows focus into the new pane. Evil's evil-window-vsplit by itself leaves point in the original window; the evil-window-right 1 moves into the freshly created one. interactive makes it a callable command. Bound to s-n below.

Opens a terminal in a fresh split (bound to s-t):

• vsplit-window-follow makes the split and moves into it.
• evil-buffer-new shows an empty *new* buffer there.
• (ghostel '(4)) launches the terminal. The non-numeric prefix arg '(4) forces a new terminal rather than reusing an existing one.

A no-prompt help command (bound to K in elisp buffers, Vim-style). symbol-at-point grabs the symbol under the cursor; if there is one, helpful-symbol opens the richer Helpful buffer without the usual minibuffer prompt.

The when-let scans live windows for one whose buffer is derived from helpful-mode, then selects it. Focus lands in the help window, so you can immediately scroll it and press q to dismiss. If there's no symbol, user-error reports it cleanly (no stack trace).

Opens a normal find-file prompt rooted at this config directory. It is bound to SPC f p, so editing the private config never depends on the current project or buffer.

SPC f i previews the dired/dirvish file at point with macOS Quick Look. It delegates to qlmanage -p asynchronously so terminal Emacs does not block or need to render media itself.

SPC f o opens the relevant directory in Finder. In dired/dirvish it follows the listed directory; elsewhere it uses default-directory.

SPC o o opens the current file in Obsidian. It detects the nearest parent directory containing .obsidian, uses that directory name as the vault name, builds an obsidian://open URL for the file relative to the vault root, and hands it to macOS open.

general is the keybinding DSL. general-create-definer builds a reusable leader command, neoemacs/leader:

• :states — active in normal, visual, and motion Evil states.
• :keymaps 'override — bind in an override map so nothing shadows the leader.
• :prefix "SPC" — Space is the leader.
• :global-prefix "M-SPC" — M-Space works as a fallback in insert/emacs states where Space inserts text.

The leader menu. Each entry maps a key sequence to a command plus a :which-key label shown in the popup. Two top-level shortcuts: SPC SPC → find file in project, SPC , → switch buffer.

Mnemonic groups, where :ignore t defines a prefix that only carries a which-key label (no command of its own):

• f files — ff find, fp config file, fr recent, fi Quick Look, fo Finder.
• b buffers — switch / kill / ibuffer / next / prev.
• p project — pp switch project, pf find file, pb project buffer.
• g git — status, blame, file log, and diff-hl hunk navigation/stage/revert.
• o open — oo opens the current file in Obsidian.
• u → vundo, a visual undo tree.
• h → the whole help-command map.

With the dashboard gone, startup time is exposed through the normal help map: SPC h t and C-h t both call emacs-init-time.

State- and keymap-scoped bindings (layer 2 of the keybinding architecture):

• - in normal state → dired-jump (vim-vinegar-style "jump to the directory of this file").
• s-h/j/k/l — move between windows (the Super/Cmd key + hjkl).
• s-n — vertical split and follow; s-w — delete window.
• S-s-[ — rotate windows; S-s-] — maximize (delete others).
• K — only in emacs-lisp-mode / lisp-interaction-mode, describe the symbol under point.

expand-region grows/shrinks the selection by semantic units (word → string → sexp → defun …). In visual state, v expands the region and V contracts it — keep tapping v to widen the selection one syntactic level at a time.

vundo visualizes the built-in undo history as a tree. It does not replace Emacs undo and does not create persistent undo-history files. It is reached via SPC u, and the Unicode glyphs make the tree clearer in the terminal.

which-key shows a popup of the available follow-up keys after you start a prefix (this is what renders the leader menu labels). :ensure nil because it's built in to modern Emacs. which-key-idle-delay 0.5 waits half a second before showing the popup.

Vertico is the UI layer: it turns minibuffer completion into a clean vertical list of candidates instead of the default horizontal one.

vertico-directory ships with Vertico and makes file-name completion behave like a path editor. RET enters directories, DEL deletes one character, and M-DEL deletes a whole path component. The tidy hook removes shadowed path prefixes like stale ~/ text when an absolute path is typed.

Orderless is the matching layer: type space-separated fragments in any order (e.g. buf swi matches "switch-buffer"). completion-styles tries orderless first, falling back to basic.

The file category override uses partial-completion so path completion keeps the familiar /u/s/b → /usr/share/bin shorthand.

Marginalia is the annotation layer: it adds rich notes in the right margin of each candidate — docstrings for commands, file sizes and permissions, variable values, and so on.

nerd-icons-completion adds colored icons to file, directory, and buffer candidates. A local advice then post-processes file completion affixations and tints directory names with the same face as the folder icon, while regular file names keep their default text face.

Consult is the commands layer — enhanced search/navigation that feeds candidates into Vertico. Bound via plain global chords:

• C-s — consult-line (live in-buffer search).
• C-x b — buffer switcher with previews.
• M-y — browse the kill ring on paste.
• M-g g — go to line; M-g i — jump via imenu.

embark is the context-action layer: s-] opens actions for the current target or minibuffer candidate, and M-. runs the default action. C-h b / SPC h b are upgraded to embark-bindings, a searchable active-keybinding view.

embark-consult connects Embark exports and previews to Consult candidate buffers, so search results can be exported into editable or actionable buffers.

wgrep makes grep result buffers editable. A typical flow is consult-ripgrep, embark-export, then C-c C-p to enter wgrep mode; edits are saved back to the touched files with C-c C-c. Auto-save is enabled so changed buffers are written when the wgrep edit is committed.

helpful replaces the common help commands under both C-h and SPC h. It shows source, values, callers, keybindings, and richer symbol context than the built-in help buffers.

ibuffer is the bulk buffer-management view, bound to C-x C-b and SPC b i. Evil collection supplies familiar navigation and marking keys. ibuffer-auto-mode keeps the list live, and ibuffer-expert removes repetitive kill confirmations.

ibuffer-projectile groups buffers by Projectile project. Embark can also export a narrowed consult-buffer candidate set directly into ibuffer for bulk actions.

Magit is the Git interface. C-x g opens status. Inside the status buffer, e is rebound to magit-ediff-show-working-tree — diffing the working tree against HEAD in ediff (overriding magit's default magit-ediff-dwim on that key).

magit-display-buffer-function = the …same-window-except-diff-v1 variant: magit-status opens in the current window, while diffs and other secondary buffers still pop to another window.

Transient is the popup-menu engine behind magit (and many other packages) — :ensure nil because it ships with Emacs, and :defer t keeps it off the startup path. This makes Esc an alias for C-g (transient-quit-one), so pressing Escape backs out of any open transient one level. Bound in transient-map, so it applies to every transient, not just magit's.

Built-in ediff (:ensure nil), deferred until a diff session starts, and tuned two ways:

• ediff-split-window-function = horizontal split → the two diff buffers sit side by side with a vertical divider, not stacked.
• ediff-window-setup-function = plain → the control panel stays in the same frame instead of spawning a popup frame.

diff-hl shows version-control changes in the terminal margin with text glyphs, because fringe indicators are invisible in emacs -nw. It is enabled on emacs-startup-hook so it is ready after init without costing startup time.

The Magit hooks refresh indicators around stage/commit operations, and the dired hook shows per-file VC status in dirvish/dired buffers. The actual config also strips theme-applied background colors from diff-hl faces so the terminal shows readable +, -, and ! glyphs instead of solid color blocks.

Dirvish upgrades dired with previews and icons. dirvish-override-dired-mode makes it the default for all dired. :after (nerd-icons general) ensures icons and the keybinding DSL are ready.

• The dired hook disables line numbers in file-manager buffers.
• dirvish-attributes — show icons and subtree-expansion state. VC state is handled by diff-hl-dired-mode instead because it is visible in terminal margins.
• dirvish-hide-details nil — keep the full ls -l detail columns visible.
• dired-listing-switches — -A "almost all" shows dotfiles but hides ./..; -l long format. When GNU ls (Homebrew coreutils gls) is present, --group-directories-first is added to sort directories ahead of files, and insert-directory-program is pointed at gls.
• dirvish-hide-cursor nil — keep a real block cursor visible (dirvish normally hides it and relies on hl-line; here etcc renders a proper terminal block).
• dired-dwim-target t — with two dired/dirvish panes, copy and rename default to the directory in the other pane.

C-c f opens dirvish. In normal state inside dired: h goes up a directory, l enters the file/dir, TAB toggles a subtree inline.

diredfl colorizes the long-listing columns such as permissions, owner, group, size, and modification time. Since dirvish buffers derive from dired, the hook covers both.

dired-x enables dired-omit-mode, hiding uninteresting files such as lock/autosave entries and common compiled artifacts. The omit message is silenced with dired-omit-verbose nil.

kkp enables the Kitty Keyboard Protocol in terminal Emacs, so chords the terminal would otherwise swallow (e.g. C-S-x, distinguishing C-i from Tab) actually reach Emacs.

clipetty sends kills (copies) to the host system clipboard via the OSC 52 escape sequence, so yanking in terminal Emacs works even over SSH and through tmux. Enabled on after-init.

ghostel is a terminal emulator powered by libghostty; its native module is a prebuilt binary that auto-downloads on first use. :commands (ghostel) sets up the autoload, and s-t runs the vsplit-and-launch helper from earlier. Terminal buffers turn line numbers off locally because the gutter is not useful there.

evil-ghostel keeps the terminal cursor in sync with Emacs point across Evil state changes, so normal-state hjkl navigation works inside the terminal buffer. It hooks onto ghostel-mode. Its :config block (broken out in the rows below) adds Escape routing, C-c/C-x passthrough, and two advices that tame the redraw anchor on an animated terminal.

Escape DWIM. A single Esc is something a terminal program legitimately wants (vi, less, menus), but Esc is also how you leave Evil's insert state. This disambiguates by timing.

• read-key inside with-timeout waits up to neoemacs/ghostel-escape-timeout (0.25s) for a second key. read-key is used because it decodes KKP/input-decode-map sequences; raw read-event can leak bytes to ghostel as control characters.
• If that second key is itself an Escape (--escape-event-p), the user meant "leave insert" → run Evil's normal insert-state Esc binding and send nothing to the terminal.
• Otherwise it was a lone Esc (or Esc followed by another key): push the stray key back onto unread-command-events so it isn't lost, and forward a real escape to ghostel.

Ctrl passthrough. C-c and C-x are precious Emacs prefixes, but inside a terminal you usually want them to reach the program running there (C-c to interrupt, etc.). ghostel-send-current-control recovers the base letter from last-command-event via event-basic-type and forwards it as a real Ctrl chord with ghostel-send-key; the guard user-errors if it's somehow not a Ctrl+letter.

The evil-define-key* wires up the insert-state map: Esc → the DWIM handler, C-c/C-x → the passthrough.

Roam advice. Each redraw, ghostel--redraw-now re-anchors any window following the live viewport via ghostel--anchor-window, whose final set-window-point snaps point back to the terminal cursor. On a static terminal redraws are rare so it's invisible; on an animated one (~30fps) it fights every hjkl in normal state.

This :around advice skips the anchor exactly when point is parked off the live cursor ((/= (point) ghostel--cursor-char-pos)) in a motion-capable Evil state. Auto-follow resumes the moment you return to insert state or land back on the cursor row.

Wheel scroll. In insert state the redraw anchor is still live, so a mouse-wheel scroll into scrollback gets immediately yanked back to the live cursor. Normal state is exactly where the roam advice above suppresses that anchor — so this flips the buffer to normal state on any wheel event.

• ghostel redispatches the wheel to mwheel-scroll when it scrolls the Emacs buffer (mouse tracking off), so that's the advised function.
• It only switches from insert/emacs — normal/visual already roam, and flipping out of visual would drop a selection.

projectile provides project-aware navigation. :defer t keeps it off the startup path, and :bind-keymap installs an autoloaded C-c p prefix that loads projectile-command-map on demand. projectile-mode turns on once the package is actually loaded.

consult-projectile wires projectile into the consult/vertico UI; it's reached at SPC p p through the leader.

markdown-mode with file-pattern associations. README.md gets gfm-mode (GitHub-Flavored Markdown); other .md / .markdown files get plain markdown-mode. The \\' anchors match the end of the filename.

envrc applies each buffer's directory .envrc via direnv (needs the direnv executable on PATH).

A formatting helper. Given an absolute directory, it returns <parent>/<dir> — e.g. ~/.config/neoemacs → config/neoemacs.

• directory-file-name + expand-file-name normalize the path (strip trailing slash, make absolute).
• name is the last component; parent is the one above.
• If there's no parent (root), just return the name.

Picks which directory names the tab, in precedence order:

1. Inside a projectile project → the project root.
2. Else a dired buffer → the listed directory.
3. Else a file-visiting buffer → the file's directory.
4. Otherwise nil → leave the tab name unchanged.

fboundp guards the projectile call in case it isn't loaded yet.

The worker. Gated on the $ZELLIJ env var, so it's a no-op outside zellij. It looks at the selected window's buffer (the hooks may fire with a different current buffer), computes the name, and compares it to the last name stored per frame (each Emacs frame maps to its own zellij pane).

Only when the name actually changed does it update the frame parameter and shell out. The executable-find guard avoids errors if the env var is present but the binary is unavailable, and start-process runs asynchronously with output discarded, so buffer switches never block on the subprocess.

Registers the worker on the full range of context changes:

• window-selection-change-functions — window focus moved.
• window-buffer-change-functions — a window's buffer changed (e.g. switch-to-buffer).
• dired-after-readin-hook / dirvish-setup-hook — directory navigation.

provide 'init registers the feature so require works.

The custom-set-variables / custom-set-faces blocks are written by Emacs's Custom system — edit config by hand above them, never inside. They are currently empty placeholders, but Emacs keeps them at the end of the file.