Config reference

Hunk reads TOML preferences from the user config and an optional repository config. This reference is generated from the same catalog that src/core/config.ts uses to parse preference keys.

Resolution and scope

Layers apply from lowest to highest precedence:

built-in defaults
user config top-level keys, then the matching command table, then [pager] when pager chrome is active
repository .hunk/config.toml top-level keys, matching command table, and pager table
explicit CLI options

The user path is $XDG_CONFIG_HOME/hunk/config.toml when configured. Otherwise Hunk uses $HOME/.config/hunk/config.toml or %USERPROFILE%/.config/hunk/config.toml; if none of those environment variables are set, no user config is loaded. Custom theme tables are root-only; preference keys may appear at top level, in a command table, or in [pager].

Preference keys

mode

Choose responsive, side-by-side, or stacked diff layout.

Type: string
Accepted: auto, split, or stack
Built-in default: auto

vcs

Select the version-control adapter explicitly. An explicit id outranks detection; an id no loaded backend owns falls back to detection with a startup notice.

Type: string
Accepted: git, jj, sl, or an id a loaded extension backend registers
Built-in default: detected from the checkout (Git fallback)

theme

Select the active color theme.

Type: string
Accepted: a built-in theme id or custom
Built-in default: github-dark-default

watch

Reload supported review inputs when their source changes.

Type: boolean
Accepted: true or false
Built-in default: false

exclude_untracked

Hide untracked files from working-tree reviews.

Type: boolean
Accepted: true or false
Built-in default: false

line_numbers

Show old and new line-number columns.

Type: boolean
Accepted: true or false
Built-in default: true

tab_width

Set terminal-cell tab stops used for display and wrapping.

Type: integer
Accepted: 1 through 16
Built-in default: 4

wrap_lines

Wrap long diff lines instead of keeping one visual row.

Type: boolean
Accepted: true or false
Built-in default: false

hunk_headers

Show hunk metadata rows in the review stream.

Type: boolean
Accepted: true or false
Built-in default: true

menu_bar

Show the top application menu bar.

Type: boolean
Accepted: true or false
Built-in default: true

agent_notes

Show agent notes when a review opens.

Type: boolean
Accepted: true or false
Built-in default: false

copy_decorations

Include diff signs and line numbers in copied selections.

Type: boolean
Accepted: true or false
Built-in default: false

prompt_save_view_preferences

Ask before discarding view changes that can be persisted.

Type: boolean
Accepted: true or false
Built-in default: true

transparent_background

Let the terminal background show through Hunk surfaces.

Type: boolean
Accepted: true or false
Built-in default: false
Aliases: transparentBackground (deprecated)

color_moved

Enable moved-line coloring when the renderer supports it.

Type: boolean
Accepted: true or false
Built-in default: —

Command tables

Table	Applies to
`[vcs]`	working-tree and target reviews (`hunk diff`)
`[show]`	commit and target display reviews (`hunk show`)
`[stash-show]`	stash reviews (`hunk stash show`)
`[diff]`	two-file comparisons (`hunk diff <left> <right>`)
`[patch]`	patch-file reviews (`hunk patch`)
`[difftool]`	Git difftool pair reviews (`hunk difftool`)

[pager] is an additional overlay for any review opened with pager-style chrome. It is applied after the matching command table in the same file.

Custom themes

Set theme = "custom" and add a root [custom_theme] table. custom_theme.base accepts one of these built-in ids and defaults to github-dark-default when layered custom themes need a base:

andromeeda
aurora-x
ayu-dark
ayu-light
ayu-mirage
catppuccin-frappe
catppuccin-latte
catppuccin-macchiato
catppuccin-mocha
dark-plus
dracula
dracula-soft
everforest-dark
everforest-light
github-dark
github-dark-default
github-dark-dimmed
github-dark-high-contrast
github-light
github-light-default
github-light-high-contrast
gruvbox-dark-hard
gruvbox-dark-medium
gruvbox-dark-soft
gruvbox-light-hard
gruvbox-light-medium
gruvbox-light-soft
horizon
horizon-bright
houston
kanagawa-dragon
kanagawa-lotus
kanagawa-wave
laserwave
light-plus
material-theme
material-theme-darker
material-theme-lighter
material-theme-ocean
material-theme-palenight
min-dark
min-light
monokai
night-owl
night-owl-light
nord
one-dark-pro
one-light
plastic
poimandres
red
rose-pine
rose-pine-dawn
rose-pine-moon
slack-dark
slack-ochin
snazzy-light
solarized-dark
solarized-light
synthwave-84
tokyo-night
vesper
vitesse-black
vitesse-dark
vitesse-light

These deprecated IDs remain accepted by theme and custom_theme.base, then normalized to their replacements:

Legacy ID	Replacement
`graphite`	`github-dark-default`
`midnight`	`github-dark-dimmed`
`paper`	`github-light-default`
`ember`	`dark-plus`
`zenburn`	`everforest-dark`

custom_theme.label accepts a non-empty string. Every semantic color below accepts a six-digit #rrggbb value:

Key	Description
`custom_theme.background`	Override the background semantic color.
`custom_theme.panel`	Override the panel semantic color.
`custom_theme.panelAlt`	Override the panelAlt semantic color.
`custom_theme.border`	Override the border semantic color.
`custom_theme.accent`	Override the accent semantic color.
`custom_theme.accentMuted`	Override the accentMuted semantic color.
`custom_theme.text`	Override the text semantic color.
`custom_theme.muted`	Override the muted semantic color.
`custom_theme.addedBg`	Override the addedBg semantic color.
`custom_theme.removedBg`	Override the removedBg semantic color.
`custom_theme.movedAddedBg`	Override the movedAddedBg semantic color.
`custom_theme.movedRemovedBg`	Override the movedRemovedBg semantic color.
`custom_theme.contextBg`	Override the contextBg semantic color.
`custom_theme.addedContentBg`	Override the addedContentBg semantic color.
`custom_theme.removedContentBg`	Override the removedContentBg semantic color.
`custom_theme.contextContentBg`	Override the contextContentBg semantic color.
`custom_theme.addedSignColor`	Override the addedSignColor semantic color.
`custom_theme.removedSignColor`	Override the removedSignColor semantic color.
`custom_theme.lineNumberBg`	Override the lineNumberBg semantic color.
`custom_theme.lineNumberFg`	Override the lineNumberFg semantic color.
`custom_theme.selectedHunk`	Override the selectedHunk semantic color.
`custom_theme.badgeAdded`	Override the badgeAdded semantic color.
`custom_theme.badgeRemoved`	Override the badgeRemoved semantic color.
`custom_theme.badgeNeutral`	Override the badgeNeutral semantic color.
`custom_theme.fileNew`	Override the fileNew semantic color.
`custom_theme.fileDeleted`	Override the fileDeleted semantic color.
`custom_theme.fileRenamed`	Override the fileRenamed semantic color.
`custom_theme.fileModified`	Override the fileModified semantic color.
`custom_theme.fileUntracked`	Override the fileUntracked semantic color.
`custom_theme.noteBorder`	Override the noteBorder semantic color.
`custom_theme.noteBackground`	Override the noteBackground semantic color.
`custom_theme.noteTitleBackground`	Override the noteTitleBackground semantic color.
`custom_theme.noteTitleText`	Override the noteTitleText semantic color.

Syntax scopes

[custom_theme.syntax_scopes] accepts arbitrary non-empty Shiki/TextMate scope names as TOML keys and six-digit hex colors as values. These exact scope overrides are the preferred syntax customization API.

The deprecated [custom_theme.syntax] table remains accepted for one compatibility window with these semantic keys: custom_theme.syntax.default, custom_theme.syntax.keyword, custom_theme.syntax.string, custom_theme.syntax.comment, custom_theme.syntax.number, custom_theme.syntax.function, custom_theme.syntax.property, custom_theme.syntax.type, custom_theme.syntax.variable, custom_theme.syntax.operator, custom_theme.syntax.punctuation. Hunk normalizes them into exact scope overrides and emits a startup notice.

Named themes

Declare any number of additional themes as [themes.<id>] tables. Each one accepts exactly the keys [custom_theme] accepts, plus the id in the table name, and is selectable with theme = "<id>" or --theme <id>. Ids are lowercase words separated by - or _; ids belonging to built-in themes, to auto, or to the custom_theme table are skipped with a startup notice. [custom_theme] itself keeps the id custom. Same-id tables merge field by field across the user and repository layers, with the repository layer winning.

Extensions

[extensions] controls which user extensions load. It is root-only and does not accept command or [pager] overrides.

Key	Type	Accepted	Built-in default	Description
`extensions.enabled`	boolean	`true` or `false`	`true`	Load user extensions. `--no-extensions` forces this off for one run, and bundled VCS backends stay loaded either way.
`extensions.paths`	array of strings	entry file or directory paths	`[]`	Extension entry points loaded at startup. Paths a repository config contributes are trust-gated before they run.

Repository .hunk/config.toml paths are kept separate from user paths: Hunk prompts for trust before executing repository-declared extension code, and --no-extensions disables user extensions entirely for one run.

Each extension reads its own settings from a [extension.<id>] table. Hunk does not interpret those keys; it passes the table through to the extension. Repository tables merge over user tables key by key, and Hunk emits a startup notice naming every extension whose settings the repository overrides.