Skip to main content

​
Introduction

Jarvis uses a single TOML configuration file with sensible defaults for every field. You only need to override the values you want to change—missing fields are automatically filled with their defaults.
The configuration schema version is 1 (CONFIG_SCHEMA_VERSION = 1).

​
Config File Location

Jarvis resolves its configuration file using the platform’s standard config directory under the jarvis/ subfolder:
PlatformPath
macOS~/Library/Application Support/jarvis/config.toml
Linux~/.config/jarvis/config.toml
WindowsC:\Users\<USER>\AppData\Roaming\jarvis\config.toml
If the file does not exist when Jarvis starts, it creates a default config.toml populated with commented-out documentation for every section.

​
How Configuration Loading Works

The configuration system follows a four-step process:
1

Load TOML

The config.toml file is read and deserialized. All fields use #[serde(default)], so a partial config (or even an empty file) works correctly.
2

Apply theme

If theme.name is anything other than "jarvis-dark", the theme file is located and its overrides are merged into the config.
3

Discover plugins

The ~/.config/jarvis/plugins/ directory is scanned for local plugin folders containing a plugin.toml manifest.
4

Validate

All numeric ranges, keybind uniqueness, and other constraints are checked. If validation fails, an error is returned.

​
Minimal Configuration Example

An empty file or just a theme selection is valid:
config.toml
# Minimal config - everything uses defaults
[theme]
name = "dracula"

​
Complete Configuration Sections

The configuration file is organized into the following sections:

Theme

Color schemes and visual customization

Colors

Full color palette with Catppuccin Mocha defaults

Font

Typography for terminal/code and UI elements

Terminal

Terminal emulator settings: scrollback, cursor, bell, mouse

Shell

Shell process configuration

Window

Window appearance and behavior

Layout

Panel layout geometry and tiling

Opacity

Transparency settings for all UI layers

Background

Background display modes (hex grid, solid, image, video, gradient)

Effects

Visual effects: scanlines, vignette, bloom, glow, flicker

Visualizer

Central visualizer system (orb, particle, waveform)

Keybinds

Keyboard shortcuts

​
Hot Reload

Jarvis supports live configuration reloading—you can edit config.toml while Jarvis is running and changes will take effect automatically.

​
How It Works

The reload system has three layers:
  1. ConfigWatcher — Uses the notify crate to watch the config file’s parent directory for filesystem events (Modify and Create events). It filters events to only react to changes affecting the actual config file by matching the filename.
  2. Debouncing — When a change is detected, the watcher enters a 500ms debounce window. Any additional filesystem events during this window are coalesced into a single reload. This prevents rapid reloads when editors perform atomic saves (write to temp file + rename).
  3. ReloadManager — Listens for change signals from the watcher, then:
    • Re-reads and parses the TOML file
    • Applies the selected theme (if not jarvis-dark)
    • Validates the new configuration
    • Publishes the new config via a tokio::sync::watch channel
If the reload fails (parse error, validation error), the failure is logged as a warning and the previous valid config remains in effect.

​
What Triggers a Reload

  • Saving the config file in any text editor
  • Replacing the file via copy/rename
  • Any Modify or Create filesystem event on the config file
Changes are debounced with a 500ms window. If the watcher receives multiple change signals within 500ms, they are collapsed into one reload event.

​
Config Validation Rules

After loading and theme application, the config is validated against constraints. If any fail, Jarvis returns a ConfigError::ValidationError with all violations.

​
Common Validation Rules

​
font.size
u32
default:13
Valid range: 8–32
​
layout.panel_gap
u32
default:6
Valid range: 1–20 pixels
​
layout.max_panels
u32
default:5
Valid range: 1–10 panels
​
opacity.*
f64
default:"varies"
All opacity fields: 0.0–1.0
​
keybinds.*
string
No duplicate bindings — Each key combination must be unique

​
Example Configurations

[theme]
name = "tokyo-night"

[font]
family = "JetBrains Mono"
size = 14
ligatures = true

[terminal]
scrollback_lines = 50000
cursor_style = "beam"

[terminal.mouse]
copy_on_select = true

[window]
decorations = "transparent"
opacity = 0.95
blur = true

[startup.boot_animation]
enabled = false

[[auto_open.panels]]
kind = "terminal"
command = "claude"
title = "Claude Code"

[[auto_open.panels]]
kind = "terminal"
title = "Terminal"

​
Config API Reference

​
Loading Configuration

use jarvis_config::{load_config, config_to_json};

let config = load_config().expect("failed to load config");
let json = config_to_json(&config);
println!("{json}");

​
Saving Configuration

use jarvis_config::{save_config, save_config_to_path};

// Save to default platform path
save_config(&config)?;

// Save to custom path
save_config_to_path(&config, "/path/to/config.toml")?;
Writes are atomic: the config is first written to a .tmp file, then renamed to the final path. If the rename fails (on Windows), it falls back to a direct write.

​
Next Steps

Theme System

Learn about built-in themes and creating custom themes

Keybindings

Customize keyboard shortcuts

Tiling Configuration

Configure panel layout and window management