config.md

LinuxChat config.json Guide

LinuxChat now supports an advanced user config file at:

~/.config/LinuxChat/.config/config.json

If the file does not exist, LinuxChat creates it automatically on first startup. After editing this file, restart LinuxChat and the new configuration will take effect.

What this file controls

config.json is the advanced appearance and behavior layer for LinuxChat. It is intended for users who want more control than the built-in light/dark toggle.

It currently controls:

• theme startup mode
• custom colors
• transparency
• window border on or off
• corner radius
• animation on or off
• extra CSS injection

Load order

At startup, LinuxChat applies settings in this order:

1. built-in defaults
2. saved app state and DB settings
3. config.json overrides

That means config.json is the final appearance override layer.

Default file

{
  "version": 1,
  "ui": {
    "transparency": 0.92,
    "show_window_border": true,
    "window_radius": 14,
    "enable_blur_hint": false,
    "animation_enabled": true
  },
  "theme": {
    "mode": "dark",
    "background_color": "#0b0b0b",
    "surface_color": "#111111",
    "sidebar_color": "#101010",
    "text_color": "#f5f5f5",
    "muted_text_color": "#a0a0a0",
    "accent_color": "#4da3ff",
    "user_bubble_color": "#1a1a1a",
    "assistant_bubble_color": "#151515",
    "input_background_color": "#101010",
    "code_block_background_color": "#161616",
    "code_block_text_color": "#f0f0f0",
    "border_color": "#2a2a2a"
  },
  "custom_css": {
    "enabled": true,
    "inject_css": ""
  },
  "advanced": {
    "reload_theme_on_startup": true,
    "strict_config_validation": false
  }
}

Full field reference

version

"version": 1

Config schema version. Keep this as 1 for the current release.

ui.transparency

"transparency": 0.92

Controls the alpha value used by the main window surfaces.

Recommended range:

• 1.0 = fully opaque
• 0.85 to 0.95 = balanced translucent look
• 0.15 = minimum supported clamp

If you set a value outside the supported range, LinuxChat clamps it internally.

ui.show_window_border

"show_window_border": true

• true: show the outer window border
• false: remove the outer border

ui.window_radius

"window_radius": 14

Controls the global corner radius used by the window and many rounded UI surfaces.

Recommended range:

• 0 = square
• 8 to 18 = balanced
• 24+ = very rounded

LinuxChat currently clamps this field into a safe range.

ui.enable_blur_hint

"enable_blur_hint": false

Reserved compatibility flag for compositor-related styling experiments. It is safe to leave this off.

ui.animation_enabled

"animation_enabled": true

Controls a small set of UI transitions such as sidebar reveal animation and some style transitions.

• true: keep transitions
• false: prefer snappier no-animation behavior

theme section

All theme color fields expect a color string GTK can parse. The safest format is standard hex:

"background_color": "#0b0b0b"

Recommended format:

• #RRGGBB

theme.mode

"mode": "dark"

Startup theme mode.

Allowed values:

• "dark"
• "light"

theme.background_color

Main window background.

theme.surface_color

Main content surface background.

theme.sidebar_color

Sidebar background.

theme.text_color

Primary text color.

theme.muted_text_color

Status text, meta text, elapsed text, and muted labels.

theme.accent_color

Focus and accent color used by selected elements and focus borders.

theme.user_bubble_color

User message bubble background.

theme.assistant_bubble_color

Assistant message bubble background.

theme.input_background_color

Message input and dropdown background.

theme.code_block_background_color

Code block background.

theme.code_block_text_color

Code block text color.

theme.border_color

Shared border color for window and many UI surfaces.

custom_css section

custom_css.enabled

"enabled": true

• true: apply inject_css
• false: ignore inject_css

custom_css.inject_css

"inject_css": ".assistant-bubble { border-width: 2px; }"

Extra GTK CSS appended after the built-in theme CSS. This is the most powerful advanced field.

Use this when the existing JSON fields are not enough.

Example:

"inject_css": ".assistant-bubble { border-width: 2px; }\n.user-bubble { border-style: dashed; }"

advanced section

advanced.reload_theme_on_startup

Currently reserved for future expansion. Keep it set to true.

advanced.strict_config_validation

Currently reserved for future expansion. Keep it set to false unless you are testing config behavior.

Example presets

1. Clean dark glass style

{
  "version": 1,
  "ui": {
    "transparency": 0.88,
    "show_window_border": true,
    "window_radius": 16,
    "enable_blur_hint": false,
    "animation_enabled": true
  },
  "theme": {
    "mode": "dark",
    "background_color": "#080b12",
    "surface_color": "#0f1420",
    "sidebar_color": "#0c111b",
    "text_color": "#edf3ff",
    "muted_text_color": "#8ea0c0",
    "accent_color": "#62a0ff",
    "user_bubble_color": "#16233a",
    "assistant_bubble_color": "#121827",
    "input_background_color": "#0d1320",
    "code_block_background_color": "#0b1220",
    "code_block_text_color": "#f3f6ff",
    "border_color": "#273246"
  },
  "custom_css": {
    "enabled": true,
    "inject_css": ""
  },
  "advanced": {
    "reload_theme_on_startup": true,
    "strict_config_validation": false
  }
}

2. Borderless dark style

{
  "version": 1,
  "ui": {
    "transparency": 0.94,
    "show_window_border": false,
    "window_radius": 14,
    "enable_blur_hint": false,
    "animation_enabled": false
  },
  "theme": {
    "mode": "dark",
    "background_color": "#0b0b0b",
    "surface_color": "#111111",
    "sidebar_color": "#101010",
    "text_color": "#f5f5f5",
    "muted_text_color": "#9a9a9a",
    "accent_color": "#4da3ff",
    "user_bubble_color": "#171717",
    "assistant_bubble_color": "#141414",
    "input_background_color": "#101010",
    "code_block_background_color": "#161616",
    "code_block_text_color": "#f0f0f0",
    "border_color": "#2a2a2a"
  },
  "custom_css": {
    "enabled": true,
    "inject_css": ""
  },
  "advanced": {
    "reload_theme_on_startup": true,
    "strict_config_validation": false
  }
}

3. Light theme with blue accents

{
  "version": 1,
  "ui": {
    "transparency": 0.98,
    "show_window_border": true,
    "window_radius": 12,
    "enable_blur_hint": false,
    "animation_enabled": true
  },
  "theme": {
    "mode": "light",
    "background_color": "#f4f7fb",
    "surface_color": "#ffffff",
    "sidebar_color": "#edf2f9",
    "text_color": "#101828",
    "muted_text_color": "#667085",
    "accent_color": "#3b82f6",
    "user_bubble_color": "#dbeafe",
    "assistant_bubble_color": "#ffffff",
    "input_background_color": "#ffffff",
    "code_block_background_color": "#f8fafc",
    "code_block_text_color": "#0f172a",
    "border_color": "#d0d7e2"
  },
  "custom_css": {
    "enabled": true,
    "inject_css": ""
  },
  "advanced": {
    "reload_theme_on_startup": true,
    "strict_config_validation": false
  }
}

Notes and limitations

• After editing config.json, restart LinuxChat.
• Invalid color strings are ignored and LinuxChat keeps the default value for that field.
• This file is for advanced appearance control. It does not replace normal chat data storage.
• The current implementation is intended to be stable and restart-driven, not hot-reload driven.

Recommended workflow

1. edit ~/.config/LinuxChat/.config/config.json
2. save the file
3. restart LinuxChat
4. verify the result
5. tune values gradually

Safe rollback

If your custom config looks bad, replace it with the default file contents from this document and restart LinuxChat.