> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings Reference

> Complete reference for all Fresh editor configuration options

## Accessing Settings

Fresh provides multiple ways to configure settings:

<Tabs>
  <Tab title="Settings Editor">
    Press `Ctrl+,` or use **View → Settings...** to open the visual settings editor.

    Settings are organized by category with search and inline documentation.
  </Tab>

  <Tab title="config.json">
    Edit `~/.config/fresh/config.json` directly for full control.

    Changes are automatically reloaded when the file is saved.
  </Tab>

  <Tab title="Command Palette">
    Press `Ctrl+P` and type `>settings` to quickly access configuration commands.
  </Tab>
</Tabs>

## Display Settings

Control visual appearance of the editor:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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            |

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

## Editing Settings

Configure editing behavior:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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           |

<Warning>
  `auto_save_enabled` saves to the original file on disk. `recovery_enabled` saves to temporary recovery files for crash recovery.
</Warning>

## Keyboard Enhancement

Configure advanced keyboard protocol features:

```json config.json theme={null}
{
  "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](/configuration/keyboard) for details on the Kitty Keyboard Protocol.

## Performance Settings

Optimize editor performance:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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   |

<Note>
  Disable `use_osc52` if you experience clipboard hangs in certain terminals like PuTTY.
</Note>

## Terminal Settings

Configure integrated terminal:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="View complete example configuration">
    ```json config.example.json theme={null}
    {
      "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"
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Keyboard Configuration" icon="keyboard" href="/configuration/keyboard">
    Customize keybindings and keymaps
  </Card>

  <Card title="Theme System" icon="palette" href="/configuration/themes">
    Built-in themes and color customization
  </Card>
</CardGroup>