How to Configure Tuicr Themes: CLI Flags, Config Files, and Custom Palettes

Tuicr themes are configured via the --theme CLI flag, the theme key in config.toml, or custom .tmTheme files placed in the themes directory, with all color definitions centralized in the Theme struct in src/theme/mod.rs.

Tuicr is a terminal-based code review tool that supports extensive visual customization through its theme system. You can configure Tuicr themes using command-line arguments, configuration files, or custom TextMate theme files to match your preferred color palette. The architecture separates theme definitions from UI rendering, allowing you to switch palettes without modifying the application code.

Understanding the Theme System Architecture

The core of Tuicr’s appearance is the Theme struct defined in src/theme/mod.rs (lines 101-138). This struct encapsulates every color used by the interface, including panel backgrounds, diff highlights, file-status indicators, comment-type hues, and status-bar styling.

Tuicr ships with nine built-in preset themes: Solarized, Catppuccin, Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest. These are implemented as constructor methods (e.g., Theme::dark(), Theme::light()) in src/theme/mod.rs (lines 140-400). The application uses syntect to parse TextMate theme files, enabling support for the standard .tmTheme format.

Selecting a Built-In Theme

Using the Command-Line Flag

The fastest way to change themes is the --theme flag, which overrides any configuration file setting. Launch Tuicr with your preferred preset:

tuicr --theme solarized_dark

This flag accepts any built-in theme name (such as catppuccin_mocha, github_dark, or nord) and applies it immediately on startup.

Using the Configuration File

For persistent preferences, set the theme key in your config.toml. Tuicr follows the XDG Base Directory specification:

• Unix/Linux/macOS: $XDG_CONFIG_HOME/tuicr/config.toml (typically ~/.config/tuicr/config.toml)
• Windows: %APPDATA%\tuicr\config.toml

Create or edit the file to include:

theme = "catppuccin_mocha"

If no theme is specified via CLI or config, Tuicr falls back to Theme::default(), which currently returns Theme::dark(). The configuration is parsed in src/config/mod.rs, which exposes both the theme key and the themes_dir helper function.

Creating and Loading Custom Themes

Tuicr supports user-provided syntax-highlighting themes through the themes directory mechanism, implemented via crate::config::themes_dir (see src/theme/mod.rs line 16).

Preparing Your Custom Theme File

Create a custom palette using the TextMate theme format (.tmTheme). These XML-based files define color scopes for syntax highlighting and UI elements. Tuicr loads these using syntect::parsing::ThemeSet::load_from_reader, ensuring compatibility with existing editor themes.

Installing Custom Themes

Place your .tmTheme file in the appropriate directory for your platform:

• Unix: $XDG_CONFIG_HOME/tuicr/themes/ (usually ~/.config/tuicr/themes/)
• Windows: %APPDATA%\tuicr\themes\

The filename (without the .tmTheme extension) becomes the theme identifier. For example, my-custom.tmTheme is referenced as my-custom.

Activating Custom Themes

Reference your custom theme using the same methods as built-ins:

tuicr --theme my-custom

Or in config.toml:

theme = "my-custom"

How Theme Colors Are Applied at Runtime

When Tuicr initializes, the App struct stores the selected theme in a theme: Theme field. The application uses helper functions in src/ui/styles.rs to translate Theme fields into ratatui::style::Style objects consumed by the rendering engine.

Key style functions include:

• Diff addition styling: styles::diff_add_style(&theme) (see src/ui/styles.rs line 13)
• Status bar background: styles::status_bar_style(&theme) (see src/ui/styles.rs line 65)

UI modules such as src/ui/app_layout.rs, src/ui/status_bar.rs, and src/ui/submit_modals.rs obtain the current theme from the App instance and apply these style helpers. This ensures a single source of truth for colors throughout the interface, whether you are viewing diffs, reading comments, or navigating the submission modal.

Summary

• Theme definitions live in src/theme/mod.rs, with built-in presets covering popular palettes like Solarized, Catppuccin, and Nord.
• Configuration accepts the --theme CLI flag or the theme key in config.toml located in the XDG config directory.
• Custom themes use standard .tmTheme files placed in tuicr/themes/ under your config directory, loaded via syntect.
• Runtime application occurs through the App struct and src/ui/styles.rs helpers, ensuring consistent coloring across all UI components.

Frequently Asked Questions

Where does Tuicr look for custom theme files?

Tuicr searches for .tmTheme files in the themes subdirectory of your configuration folder: $XDG_CONFIG_HOME/tuicr/themes/ on Unix systems or %APPDATA%\tuicr\themes\ on Windows. The loader uses the themes_dir helper from src/config/mod.rs to resolve this path dynamically based on platform conventions.

Can I use my existing VS Code or Sublime Text themes?

Yes, provided they are in the TextMate .tmTheme format. Tuicr uses syntect’s ThemeSet::load_from_reader to parse these files, so any standard TextMate theme compatible with syntect will work. Simply copy the .tmTheme file into your Tuicr themes directory and reference it by filename.

Why does my theme change not apply immediately?

Theme selection happens at application startup in src/app/init.rs (or src/app/mod.rs). The App struct initializes with a specific Theme instance, and there is currently no runtime hot-reloading mechanism. You must restart Tuicr after changing the theme value in config.toml or switching custom theme files.

What is the default theme if I don't specify one?

If no theme is provided via --theme or configuration, Tuicr calls Theme::default(), which currently returns Theme::dark(). This fallback is defined in src/theme/mod.rs and provides a dark palette optimized for terminal readability until you configure a specific preference.

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