Settings Reference

Settings Reference

VimCode settings are stored in ~/.config/vimcode/settings.json. Changes made via :set are written through immediately.

Accessing settings

• :set option — change a setting from command mode
• :set option? — query current value (e.g. :set ts? → tabstop=4)
• :set option! — toggle a boolean option
• :set (no args) — show summary of all settings
• :Settings — open settings.json in an editor tab
• Settings sidebar — click the gear icon in the activity bar for a visual settings form
• :config reload — reload settings from disk

:set options

These options can be changed at runtime with :set. Changes are persisted to settings.json.

Option	Aliases	Default	Description
number / nonumber	nu	on	Absolute line numbers
relativenumber / norelativenumber	rnu	off	Relative line numbers (with number = hybrid)
expandtab / noexpandtab	et	on	Tab key inserts spaces
tabstop=N	ts	4	Width of Tab key / tab display
shiftwidth=N	sw	4	Indent width for >> / <<
autoindent / noautoindent	ai	on	Copy indent from current line on Enter/o/O
incsearch / noincsearch	is	on	Incremental search as you type
hlsearch / nohlsearch	hls	on	Highlight all search matches
ignorecase / noignorecase	ic	off	Case-insensitive search
smartcase / nosmartcase	scs	off	Override ignorecase when pattern has uppercase
scrolloff=N	so	0	Lines to keep above/below cursor when scrolling
cursorline / nocursorline	cul	off	Highlight the line the cursor is on
colorcolumn=N	cc	""	Comma-list of column guides to highlight
textwidth=N	tw	0	Auto-wrap inserted text at column N (0=off)
wrap / nowrap		off	Soft-wrap long lines at viewport edge
splitbelow / nosplitbelow	sb	off	Horizontal splits open below
splitright / nosplitright	spr	off	Vertical splits open to the right
autoread / noautoread	ar	on	Automatically reload files modified on disk
lsp / nolsp		on	Enable/disable LSP language servers
formatonsave / noformatonsave	fos	off	Auto-format buffer via LSP before saving
mode=vim / mode=vscode		vim	Editor mode

Settings.json-only options

These are set directly in ~/.config/vimcode/settings.json:

Key	Default	Description
terminal_scrollback_lines	5000	Rows kept in terminal scrollback (0 = unlimited)
leader	" " (Space)	Leader key for <leader> sequences
extension_registry_url	GitHub URL	URL for remote extension registry (self-hosted override)
show_hidden_files	false	Show dotfiles in file explorer
swap_file	true	Write swap files for crash recovery
updatetime	4000	Milliseconds between swap file writes
breadcrumbs	true	Show file path + symbol hierarchy below tab bar
autohide_panels	false	TUI: hide sidebar/activity bar at startup
indent_guides	true	Show vertical indent guide lines
match_brackets	true	Highlight matching bracket pair
auto_pairs	true	Auto-close brackets and quotes in Insert mode

AI settings

Key	Default	Description
ai_provider	"anthropic"	AI provider: "anthropic", "openai", or "ollama"
ai_api_key	""	API key (falls back to ANTHROPIC_API_KEY / OPENAI_API_KEY env vars)
ai_model	""	Model override (leave empty for provider default)
ai_base_url	""	Base URL override (for Ollama: http://localhost:11434)
ai_completions	false	Enable AI inline completions (ghost text) in insert mode

LSP settings

Key	Default	Description
lsp	true	Enable/disable LSP
lsp_servers	[]	Custom LSP server definitions (see LSP Configuration)

Key binding groups

See Key Remapping for details on:

• panel_keys — sidebar, terminal, fuzzy finder bindings
• explorer_keys — file explorer action bindings
• completion_keys — completion popup bindings
• keymaps — user-defined key → command mappings

Settings sidebar

Click the gear icon in the activity bar to open a VSCode-style settings form:

• Searchable — type to filter settings
• Grouped by category — Appearance, Editor, Search, Workspace, LSP, Terminal, Plugins, AI
• Interactive controls:
  • GTK: native Switch, SpinButton, DropDown, Entry widgets
  • TUI: [✓]/[ ] toggles, value ▸ cycling, inline text editing with Ctrl+V paste
• Colorscheme picker — includes custom VSCode themes from ~/.config/vimcode/themes/
• User Keymaps row — opens a scratch buffer editor (:Keymaps)

Changes apply and save immediately.

Colorscheme

:colorscheme <name>        " Switch theme
:colorscheme               " List available themes

Built-in themes: onedark (default), gruvbox-dark, tokyo-night, solarized-dark.

Custom VSCode .json themes can be placed in ~/.config/vimcode/themes/ — see Theme Customization.

Workspaces

A .vimcode-workspace file at the project root captures per-project settings:

{
    "version": 1,
    "folders": [{"path": "."}],
    "settings": { "tabstop": 2, "expandtab": true }
}

Workspace settings overlay your global settings.json. When you switch directories, the overlay is reverted.

Commands:

• :OpenFolder <path> — open directory as workspace root
• :OpenWorkspace <path> — open .vimcode-workspace file
• :SaveWorkspaceAs <path> — save current folder as workspace
• :OpenRecent — recent workspaces picker

Session persistence

All state lives in ~/.config/vimcode/:

File	Contents
settings.json	Editor options
session.json	Open files, cursor/scroll positions, history, window geometry
sessions/<hash>.json	Per-workspace sessions (keyed by path hash)
swap/	Swap files for crash recovery
extensions/	Installed extensions
plugins/	User Lua plugins
themes/	Custom VSCode color themes
registry_cache.json	Cached extension registry

Open files, cursor positions, command/search history, window geometry, and explorer state are all restored on startup.