Settings Reference

Accessing Settings

Fresh provides multiple ways to configure settings:

Settings Editor
config.json
Command Palette

Press Ctrl+, or use View → Settings… to open the visual settings editor.Settings are organized by category with search and inline documentation.

Edit ~/.config/fresh/config.json directly for full control.Changes are automatically reloaded when the file is saved.

Press Ctrl+P and type >settings to quickly access configuration commands.

Display Settings

Control visual appearance of the editor:

config.json

{
  "editor": {
    "line_numbers": true,
    "relative_line_numbers": false,
    "line_wrap": true,
    "syntax_highlighting": true,
    "show_menu_bar": true,
    "show_tab_bar": true,
    "show_status_bar": true,
    "show_vertical_scrollbar": true,
    "show_horizontal_scrollbar": false,
    "use_terminal_bg": false,
    "cursor_style": "default",
    "rulers": [80, 120]
  }
}

Display Options

Setting	Type	Default	Description
`line_numbers`	boolean	`true`	Show line numbers in gutter
`relative_line_numbers`	boolean	`false`	Show line numbers relative to cursor
`line_wrap`	boolean	`true`	Wrap long lines to fit window
`syntax_highlighting`	boolean	`true`	Enable syntax highlighting
`show_menu_bar`	boolean	`true`	Show menu bar at top
`show_tab_bar`	boolean	`true`	Show tab bar for open files
`show_status_bar`	boolean	`true`	Show status bar at bottom
`show_vertical_scrollbar`	boolean	`true`	Show vertical scrollbar
`show_horizontal_scrollbar`	boolean	`false`	Show horizontal scrollbar
`use_terminal_bg`	boolean	`false`	Use terminal’s background color
`cursor_style`	string	`"default"`	Cursor style (see below)
`rulers`	number[]	`[]`	Vertical ruler columns

Cursor Styles

Available cursor styles:

"default" - Terminal default
"blinking_block" - Blinking block (█)
"steady_block" - Solid block
"blinking_bar" - Blinking vertical bar (│)
"steady_bar" - Solid vertical bar
"blinking_underline" - Blinking underline (_)
"steady_underline" - Solid underline

Whitespace Indicators

Control visibility of whitespace characters:

config.json

{
  "editor": {
    "whitespace_show": true,
    "whitespace_spaces_leading": false,
    "whitespace_spaces_inner": false,
    "whitespace_spaces_trailing": false,
    "whitespace_tabs_leading": true,
    "whitespace_tabs_inner": true,
    "whitespace_tabs_trailing": true
  }
}

Setting	Type	Default	Description
`whitespace_show`	boolean	`true`	Master toggle for whitespace indicators
`whitespace_spaces_leading`	boolean	`false`	Show leading space indicators (·)
`whitespace_spaces_inner`	boolean	`false`	Show inner space indicators
`whitespace_spaces_trailing`	boolean	`false`	Show trailing space indicators
`whitespace_tabs_leading`	boolean	`true`	Show leading tab indicators (→)
`whitespace_tabs_inner`	boolean	`true`	Show inner tab indicators
`whitespace_tabs_trailing`	boolean	`true`	Show trailing tab indicators

Per-language show_whitespace_tabs setting can override tab visibility for specific languages (e.g., disable for Go).

Editing Settings

Configure editing behavior:

config.json

{
  "editor": {
    "tab_size": 4,
    "auto_indent": true,
    "auto_close": true,
    "auto_surround": true,
    "scroll_offset": 3,
    "default_line_ending": "lf",
    "trim_trailing_whitespace_on_save": false,
    "ensure_final_newline_on_save": false
  }
}

Setting	Type	Default	Description
`tab_size`	number	`4`	Number of spaces per tab
`auto_indent`	boolean	`true`	Auto-indent new lines
`auto_close`	boolean	`true`	Auto-close brackets and quotes
`auto_surround`	boolean	`true`	Surround selection with matching pairs
`scroll_offset`	number	`3`	Keep N lines visible above/below cursor
`default_line_ending`	string	`"lf"`	Line ending for new files (`"lf"`, `"crlf"`, `"cr"`)
`trim_trailing_whitespace_on_save`	boolean	`false`	Remove trailing whitespace on save
`ensure_final_newline_on_save`	boolean	`false`	Ensure file ends with newline

Bracket Matching

Configure bracket highlighting:

config.json

{
  "editor": {
    "highlight_matching_brackets": true,
    "rainbow_brackets": true
  }
}

Setting	Type	Default	Description
`highlight_matching_brackets`	boolean	`true`	Highlight matching bracket pairs
`rainbow_brackets`	boolean	`true`	Use rainbow colors for nested brackets

Completion Settings

Configure auto-completion behavior:

config.json

{
  "editor": {
    "quick_suggestions": true,
    "quick_suggestions_delay_ms": 10,
    "suggest_on_trigger_characters": true,
    "accept_suggestion_on_enter": "on"
  }
}

Setting	Type	Default	Description
`quick_suggestions`	boolean	`true`	Show suggestions while typing
`quick_suggestions_delay_ms`	number	`10`	Delay before showing suggestions (ms)
`suggest_on_trigger_characters`	boolean	`true`	Show suggestions on trigger chars (`.`, `::`)
`accept_suggestion_on_enter`	string	`"on"`	Enter key behavior: `"on"`, `"off"`, `"smart"`

Accept Suggestion on Enter

"on" - Enter always accepts completion
"off" - Enter inserts newline (use Tab to accept)
"smart" - Enter accepts only if completion differs from typed text

LSP Settings

Configure Language Server Protocol features:

config.json

{
  "editor": {
    "enable_inlay_hints": true,
    "enable_semantic_tokens_full": false
  }
}

Setting	Type	Default	Description
`enable_inlay_hints`	boolean	`true`	Show LSP inlay hints (type hints, parameter names)
`enable_semantic_tokens_full`	boolean	`false`	Request full-document semantic tokens

Mouse Settings

Configure mouse behavior:

config.json

{
  "editor": {
    "mouse_hover_enabled": true,
    "mouse_hover_delay_ms": 500,
    "double_click_time_ms": 500
  }
}

Setting	Type	Default	Description
`mouse_hover_enabled`	boolean	`true`	Show LSP hover info on mouse hover
`mouse_hover_delay_ms`	number	`500`	Delay before showing hover info
`double_click_time_ms`	number	`500`	Time window for double-click detection

Auto-Save and Recovery

Configure file saving and recovery:

config.json

{
  "editor": {
    "auto_save_enabled": false,
    "auto_save_interval_secs": 30,
    "recovery_enabled": true,
    "auto_recovery_save_interval_secs": 2,
    "auto_revert_poll_interval_ms": 2000
  }
}

Setting	Type	Default	Description
`auto_save_enabled`	boolean	`false`	Enable persistent auto-save to disk
`auto_save_interval_secs`	number	`30`	Auto-save interval (seconds)
`recovery_enabled`	boolean	`true`	Enable file recovery (auto-save to recovery files)
`auto_recovery_save_interval_secs`	number	`2`	Recovery save interval
`auto_revert_poll_interval_ms`	number	`2000`	Check for external file changes interval

auto_save_enabled saves to the original file on disk. recovery_enabled saves to temporary recovery files for crash recovery.

Keyboard Enhancement

Configure advanced keyboard protocol features:

config.json

{
  "editor": {
    "keyboard_disambiguate_escape_codes": true,
    "keyboard_report_event_types": false,
    "keyboard_report_alternate_keys": true,
    "keyboard_report_all_keys_as_escape_codes": false
  }
}

Setting	Type	Default	Description
`keyboard_disambiguate_escape_codes`	boolean	`true`	Use CSI-u for unambiguous key reporting
`keyboard_report_event_types`	boolean	`false`	Report key repeat/release events
`keyboard_report_alternate_keys`	boolean	`true`	Send alternate keycodes
`keyboard_report_all_keys_as_escape_codes`	boolean	`false`	Report all keys as escape sequences

See Keyboard Configuration for details on the Kitty Keyboard Protocol.

Performance Settings

Optimize editor performance:

config.json

{
  "editor": {
    "highlight_timeout_ms": 5,
    "snapshot_interval": 100,
    "highlight_context_bytes": 10000,
    "large_file_threshold_bytes": 1048576,
    "estimated_line_length": 80,
    "read_concurrency": 64,
    "file_tree_poll_interval_ms": 3000
  }
}

Setting	Type	Default	Description
`highlight_timeout_ms`	number	`5`	Max syntax highlighting time per frame (ms)
`snapshot_interval`	number	`100`	Undo snapshot interval (number of edits)
`highlight_context_bytes`	number	`10000`	Context bytes for syntax highlighting
`large_file_threshold_bytes`	number	`1048576`	File size threshold for large file mode (bytes)
`estimated_line_length`	number	`80`	Average line length estimate for large files
`read_concurrency`	number	`64`	Max concurrent filesystem reads
`file_tree_poll_interval_ms`	number	`3000`	File tree refresh interval

Large File Behavior

Files larger than large_file_threshold_bytes (1MB default) will:

Skip LSP features
Use constant-size scrollbar thumb
Use viewport-only parsing

File Explorer Settings

Configure the file tree sidebar:

config.json

{
  "file_explorer": {
    "respect_gitignore": true,
    "show_hidden": false,
    "show_gitignored": false,
    "custom_ignore_patterns": ["*.log", "tmp/"],
    "width": 0.3
  }
}

Setting	Type	Default	Description
`respect_gitignore`	boolean	`true`	Respect `.gitignore` files
`show_hidden`	boolean	`false`	Show hidden files (starting with `.`)
`show_gitignored`	boolean	`false`	Show gitignored files
`custom_ignore_patterns`	string[]	`[]`	Custom ignore patterns (glob)
`width`	number	`0.3`	Explorer width as fraction of screen (0.0-1.0)

Clipboard Settings

Configure clipboard behavior:

config.json

{
  "clipboard": {
    "use_osc52": true,
    "use_system_clipboard": true
  }
}

Setting	Type	Default	Description
`use_osc52`	boolean	`true`	Use OSC 52 escape sequences
`use_system_clipboard`	boolean	`true`	Use system clipboard APIs

Disable use_osc52 if you experience clipboard hangs in certain terminals like PuTTY.

Terminal Settings

Configure integrated terminal:

config.json

{
  "terminal": {
    "jump_to_end_on_output": true
  }
}

Setting	Type	Default	Description
`jump_to_end_on_output`	boolean	`true`	Auto-scroll to bottom on new output

Warning Notifications

Configure diagnostic warnings:

config.json

{
  "warnings": {
    "show_status_indicator": true
  }
}

Setting	Type	Default	Description
`show_status_indicator`	boolean	`true`	Show warning/error indicators in status bar

Package Manager Settings

Configure plugin and theme installation:

config.json

{
  "packages": {
    "sources": [
      "https://github.com/sinelaw/fresh-plugins-registry"
    ]
  }
}

Setting	Type	Default	Description
`sources`	string[]	`["https://github.com/sinelaw/fresh-plugins-registry"]`	Plugin registry URLs

Per-Language Settings

Override settings per language:

config.json

{
  "languages": {
    "rust": {
      "tab_size": 4,
      "use_tabs": false,
      "auto_indent": true,
      "show_whitespace_tabs": true,
      "formatter": {
        "command": "rustfmt",
        "args": [],
        "stdin": true,
        "timeout_ms": 10000
      },
      "format_on_save": true,
      "on_save": [
        {
          "command": "cargo",
          "args": ["clippy"],
          "timeout_ms": 5000,
          "enabled": true
        }
      ]
    },
    "go": {
      "tab_size": 8,
      "use_tabs": true,
      "show_whitespace_tabs": false
    }
  }
}

Language Configuration

Setting	Type	Description
`extensions`	string[]	File extensions
`filenames`	string[]	Exact filename matches
`grammar`	string	Tree-sitter grammar name
`comment_prefix`	string	Comment syntax
`tab_size`	number	Spaces per tab (overrides global)
`use_tabs`	boolean	Insert tab characters
`auto_indent`	boolean	Auto-indent new lines
`auto_close`	boolean	Auto-close brackets (overrides global)
`auto_surround`	boolean	Auto-surround selection (overrides global)
`show_whitespace_tabs`	boolean	Show tab indicators
`formatter`	object	Formatter configuration
`format_on_save`	boolean	Auto-format on save
`on_save`	array	Actions to run on save

Formatter Configuration

{
  "formatter": {
    "command": "prettier",
    "args": ["--write", "$FILE"],
    "stdin": true,
    "timeout_ms": 10000
  }
}

Setting	Type	Default	Description
`command`	string	-	Formatter executable
`args`	string[]	`[]`	Arguments (use `$FILE` for file path)
`stdin`	boolean	`true`	Pass buffer via stdin
`timeout_ms`	number	`10000`	Timeout in milliseconds

On-Save Actions

{
  "on_save": [
    {
      "command": "eslint",
      "args": ["--fix", "$FILE"],
      "stdin": false,
      "timeout_ms": 5000,
      "enabled": true
    }
  ]
}

Setting	Type	Default	Description
`command`	string	-	Command to run
`args`	string[]	`[]`	Arguments
`stdin`	boolean	`false`	Pass buffer via stdin
`timeout_ms`	number	`10000`	Timeout
`enabled`	boolean	`true`	Enable/disable action

LSP Server Configuration

Configure language servers:

config.json

{
  "lsp": {
    "rust": {
      "command": "rust-analyzer",
      "args": [],
      "enabled": true,
      "auto_start": false,
      "process_limits": {
        "max_memory_percent": 50,
        "max_cpu_percent": 90,
        "enabled": true
      },
      "initialization_options": {
        "checkOnSave": false,
        "diagnostics": {"enable": true}
      }
    }
  }
}

LSP Configuration

Setting	Type	Default	Description
`command`	string	-	LSP server executable
`args`	string[]	`[]`	Command arguments
`enabled`	boolean	`true`	Enable server
`auto_start`	boolean	`false`	Auto-start when opening files
`initialization_options`	object	`null`	Server-specific options
`process_limits`	object	-	Memory/CPU limits

Process Limits

{
  "process_limits": {
    "max_memory_percent": 50,
    "max_cpu_percent": 90,
    "enabled": true
  }
}

Setting	Type	Default	Description
`enabled`	boolean	`true`	Enable process limits
`max_memory_percent`	number	`50`	Max memory usage (% of system)
`max_cpu_percent`	number	`90`	Max CPU usage (%)

Full Example Configuration

View complete example configuration

config.example.json

{
  "theme": "high-contrast",
  "check_for_updates": true,
  "editor": {
    "tab_size": 4,
    "auto_indent": true,
    "line_numbers": true,
    "relative_line_numbers": false,
    "scroll_offset": 3,
    "syntax_highlighting": true,
    "line_wrap": true,
    "highlight_timeout_ms": 5,
    "snapshot_interval": 100,
    "large_file_threshold_bytes": 1048576,
    "estimated_line_length": 80,
    "enable_inlay_hints": true,
    "enable_semantic_tokens_full": false,
    "auto_save_enabled": false,
    "auto_save_interval_secs": 30,
    "recovery_enabled": true,
    "auto_recovery_save_interval_secs": 2,
    "highlight_context_bytes": 10000,
    "mouse_hover_enabled": true,
    "mouse_hover_delay_ms": 500,
    "double_click_time_ms": 500,
    "auto_revert_poll_interval_ms": 2000,
    "file_tree_poll_interval_ms": 3000
  },
  "file_explorer": {
    "respect_gitignore": true,
    "show_hidden": false,
    "show_gitignored": false,
    "custom_ignore_patterns": [],
    "width": 0.3
  },
  "clipboard": {
    "use_osc52": true,
    "use_system_clipboard": true
  },
  "terminal": {
    "jump_to_end_on_output": true
  },
  "keybindings": [],
  "active_keybinding_map": "default"
}

Getting Started

Core Features

Configuration

Advanced Features

Plugins

Reference

Settings Reference

Accessing Settings

Display Settings

Display Options

Cursor Styles

Whitespace Indicators

Editing Settings

Bracket Matching

Completion Settings

Accept Suggestion on Enter

LSP Settings

Mouse Settings

Auto-Save and Recovery

Keyboard Enhancement

Performance Settings

Large File Behavior

File Explorer Settings

Clipboard Settings

Terminal Settings

Warning Notifications

Package Manager Settings

Per-Language Settings

Language Configuration

Formatter Configuration

On-Save Actions

LSP Server Configuration

LSP Configuration

Process Limits

Full Example Configuration

Next Steps

Keyboard Configuration

Theme System

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Advanced Features

Plugins

Reference

​Accessing Settings

​Display Settings

​Display Options

​Cursor Styles

​Whitespace Indicators

​Editing Settings

​Bracket Matching

​Completion Settings

​Accept Suggestion on Enter

​LSP Settings

​Mouse Settings

​Auto-Save and Recovery

​Keyboard Enhancement

​Performance Settings

​Large File Behavior

​File Explorer Settings

​Clipboard Settings

​Terminal Settings

​Warning Notifications

​Package Manager Settings

​Per-Language Settings

​Language Configuration

​Formatter Configuration

​On-Save Actions

​LSP Server Configuration

​LSP Configuration

​Process Limits

​Full Example Configuration

​Next Steps

Keyboard Configuration

Theme System

Build docs developers (and LLMs) love

Accessing Settings

Display Settings

Display Options

Cursor Styles

Whitespace Indicators

Editing Settings

Bracket Matching

Completion Settings

Accept Suggestion on Enter

LSP Settings

Mouse Settings

Auto-Save and Recovery

Keyboard Enhancement

Performance Settings

Large File Behavior

File Explorer Settings

Clipboard Settings

Terminal Settings

Warning Notifications

Package Manager Settings

Per-Language Settings

Language Configuration

Formatter Configuration

On-Save Actions

LSP Server Configuration

LSP Configuration

Process Limits

Full Example Configuration

Next Steps