How to Create and Use Custom Themes in Tuicr Configuration

You can create custom themes in tuicr by placing .tmTheme files in the themes directory and activating them via the --theme flag or config.toml file, or choose from nine built-in presets including Solarized, Catppuccin, and Nord.

Tuicr is a terminal-based code review tool that supports extensive visual customization through its Theme system. The application uses a centralized Theme struct defined in the source code to manage every color used in the interface, from panel backgrounds to diff highlights. Whether you prefer built-in presets or want to import your own TextMate themes, tuicr's configuration system provides multiple pathways to customize your code review experience.

Understanding the Theme System

Core Theme Structure

The theme engine centers on the Theme struct defined in src/theme/mod.rs (lines 101-138). This structure supplies every color used by the UI, including panel backgrounds, diff highlights, file-status colors, comment-type hues, and status-bar styling. The struct provides default constructors Theme::dark() and Theme::light() that establish baseline color palettes.

Built-in Preset Themes

Tuicr ships with nine built-in color schemes implemented in src/theme/mod.rs (lines 140-400):

• Solarized (dark and light variants)
• Catppuccin (Mocha, Macchiato, Frappe, Latte)
• Ayu
• OneDark
• GitHub
• Tokyo Night
• Gruvbox
• Nord
• Everforest

Selecting a Theme

Command-Line Flag

The fastest way to switch themes is using the --theme flag, which overrides any configuration file setting.

tuicr --theme solarized_dark

Configuration File

For persistent theming, create a config.toml in your platform's configuration directory. On Unix systems, this is $XDG_CONFIG_HOME/tuicr/config.toml (typically ~/.config/tuicr/config.toml); on Windows, use %APPDATA%\tuicr\config.toml.

theme = "catppuccin_mocha"

Default Behavior

If no theme is specified, tuicr falls back to Theme::default(), which currently returns Theme::dark(). The system is architected to allow future terminal background detection, but presently defaults to the dark palette.

Creating and Loading Custom Themes

Tuicr supports user-defined syntax-highlighting themes through the TextMate .tmTheme format. The loader uses crate::config::themes_dir (defined at src/theme/mod.rs line 16) to locate user themes and parses them using syntect's ThemeSet::load_from_reader.

To add a custom theme:

1. Create a .tmTheme file defining your color palette
2. Place it in the themes directory:
   • Unix: $XDG_CONFIG_HOME/tuicr/themes/ (usually ~/.config/tuicr/themes/)
   • Windows: %APPDATA%\tuicr\themes\
3. Reference the theme by filename (without extension)

For example, with a file named my-custom.tmTheme:

tuicr --theme my-custom

How Themes Are Applied in the Codebase

When tuicr initializes, the App struct stores a theme: Theme instance that serves as the single source of truth for all UI colors. UI components access these colors through helper functions in src/ui/styles.rs, which accept a &Theme reference and return ratatui::style::Style values.

Key style helpers include:

• styles::diff_add_style(&theme) (line 13) for diff additions
• styles::status_bar_style(&theme) (line 65) for status bar backgrounds

All rendering code in ui/app_layout.rs, ui/status_bar.rs, and ui/submit_modals.rs pulls colors from the App instance's theme through these style helpers, ensuring consistent application across the interface.

Summary

• The Theme struct in src/theme/mod.rs (lines 101-138) controls all UI colors, with built-in presets defined in lines 140-400
• Activate themes via --theme flag, config.toml, or accept the default dark theme
• Create custom themes by placing .tmTheme files in the XDG config themes directory
• The App struct stores the active theme, while src/ui/styles.rs translates theme fields into ratatui Style objects for rendering

Frequently Asked Questions

What file format should I use for custom tuicr themes?

Tuicr uses the TextMate .tmTheme format for custom syntax highlighting themes. These XML-based files define color palettes that syntect parses using ThemeSet::load_from_reader. Place your .tmTheme files in the themes directory (e.g., ~/.config/tuicr/themes/ on Unix) and reference them by filename without the extension.

Where does tuicr look for the configuration file?

Tuicr follows the XDG Base Directory Specification. On Unix systems, it searches for config.toml in $XDG_CONFIG_HOME/tuicr/ (defaulting to ~/.config/tuicr/). On Windows, the configuration resides in %APPDATA%\tuicr\config.toml. The themes subdirectory within this path stores custom .tmTheme files.

Can I override the config file theme temporarily?

Yes. The --theme command-line flag takes precedence over the config.toml setting. Running tuicr --theme <NAME> loads the specified theme for that session only, regardless of what is saved in your configuration file. This allows quick switching without modifying persistent settings.

Which built-in themes are available in tuicr?

Tuicr includes nine built-in color schemes: Solarized (dark/light), Catppuccin variants (Mocha, Macchiato, Frappe, Latte), Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest. These are implemented in src/theme/mod.rs (lines 140-400) and can be referenced by their lowercase names with underscores (e.g., solarized_dark, catppuccin_mocha).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}