Configuration Reference

grüt is configured via a TOML file. Every option has a sensible default — you only need to set the values you want to change.

grüt

⌕ Click to enlarge

Config File Location

grüt looks for its config file at:

• Linux / macOS: ~/.config/grut/config.toml
• Windows: %APPDATA%\grut\config.toml

If the file does not exist, grüt uses built-in defaults. You can create the file manually or run grut config defaults --output ~/.config/grut/config.toml to generate one with all defaults.

[general]

Top-level application settings.

[general]
keybinding_scheme = "default"   # "default" | "vim" | "classic"
default_layout    = "explorer"  # "explorer" | "git" | "review" | "agent" | "full"
auto_save_session = true        # restore last session on startup
show_first_run_help = true      # show help overlay on first launch

[file_tree]

Controls the file explorer panel.

[file_tree]
show_hidden           = true      # show dotfiles and hidden directories
icon_mode             = "auto"    # "nerd" | "ascii" | "auto" (detect Nerd Font)
sort_directories_first = true     # directories before files in the tree
git_status_markers    = true      # show ●/✗/? markers next to files
max_depth             = 20        # max tree depth (0 = unlimited)

[preview]

Controls the file preview panel.

[preview]
enabled             = true
width               = 40          # percentage of available width (20–80)
syntax_highlighting = true
max_file_size       = 1048576     # bytes; skip preview for files larger than this
line_numbers        = true
word_wrap           = false

[git]

Git integration settings.

[git]
refresh_method       = "fsnotify"   # "fsnotify" | "poll"
default_branch       = "main"       # fallback when origin/HEAD is unavailable
worktree_first       = true         # prefer worktrees over branches
worktree_merge_method = "merge"     # "merge" | "rebase" | "squash"
auto_fetch_interval  = "5m"         # auto-fetch period (0 = disabled)
show_commit_graph    = true         # show graph lines in log view
max_log_entries      = 500          # max commits loaded in log view
sign_commits         = false        # GPG/SSH sign commits

[terminal]

Embedded terminal settings.

[terminal]
shell       = ""          # shell binary (empty = system default)
scrollback  = 10000       # scrollback buffer lines
render_fps  = 30          # terminal render frames per second
prefix_key  = "ctrl+b"   # prefix key for terminal commands

[ai]

AI integration and context builder settings.

[ai]
auto_install_deps = false         # auto-install AI tool dependencies
context_mode      = "manual"      # "manual" | "smart"
token_model       = "gpt-4"      # model used for token counting

[theme]

Theme selection. Use a built-in name or a path to a custom theme file.

[theme]
name = "default"   # "default" | "catppuccin" | "tokyonight" | "gruvbox"
                   # or an absolute/relative path to a .toml theme file

[session]

Session persistence settings.

[session]
enabled  = true
max_age  = 30      # days; auto-delete sessions older than this

[bookmarks]

Pinned directories for quick navigation.

[bookmarks]
paths = [
  "~/projects",
  "~/dotfiles",
]
show_in_sidebar = true   # display bookmarks in the file tree sidebar

[logging]

Diagnostic logging.

[logging]
level = "warn"    # "debug" | "info" | "warn" | "error"
file  = ""        # log file path (empty = stderr)

Full Example

A complete config with every section:

# grüt configuration
# ~/.config/grut/config.toml

[general]
keybinding_scheme   = "vim"
default_layout      = "git"
auto_save_session   = true
show_first_run_help = false

[file_tree]
show_hidden            = true
icon_mode              = "nerd"
sort_directories_first = true
git_status_markers     = true
max_depth              = 0

[preview]
enabled             = true
width               = 50
syntax_highlighting = true
max_file_size       = "2MB"
line_numbers        = true
word_wrap           = false

[git]
refresh_method        = "fsnotify"
default_branch        = "main"
worktree_first        = false
worktree_merge_method = "merge"
auto_fetch_interval   = "5m"
show_commit_graph     = true
max_log_entries       = 1000
sign_commits          = true

[terminal]
shell      = "/bin/zsh"
scrollback = 10000
render_fps = 30
prefix_key = "ctrl+a"

[ai]
auto_install_deps = true
context_mode      = "selection"
token_model       = "gpt-4"

[theme]
name = "catppuccin"

[session]
enabled = true
max_age = "30d"

[bookmarks]
paths = [
  "~/projects",
  "~/dotfiles",
]
show_in_sidebar = true

[logging]
level = "warn"
file  = ""