How to Customize Themes in Tuicr: Complete Configuration Guide

You can customize themes in Tuicr using the --theme command-line flag, the config.toml configuration file, or by adding custom .tmTheme files to the themes directory.

Tuicr is a terminal-based code review tool that provides extensive theming capabilities through its Theme struct defined in src/theme/mod.rs. The architecture supports both built-in preset color schemes and user-provided TextMate themes, allowing complete control over panel backgrounds, diff highlights, file-status colors, and status-bar styling.

Selecting a Built-In Theme

Tuicr offers three methods to activate a theme, with command-line arguments taking precedence over configuration files.

Command-Line Flag

Use the --theme flag to override any configuration file setting when launching the application. This is ideal for testing different palettes or running multiple instances with distinct appearances.

tuicr --theme solarized_dark

The flag accepts any built-in preset name or the basename of a custom .tmTheme file stored in the themes directory.

Configuration File

For persistent theming, create a config.toml in the appropriate XDG 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"

The theme key must match one of the built-in preset identifiers or a custom theme filename (without extension).

Default Fallback

If no explicit theme is specified, Tuicr falls back to Theme::default(), which currently returns Theme::dark() as defined in src/theme/mod.rs lines 101-138. The system does not currently auto-detect terminal background color, defaulting to the dark palette.

Adding Custom Themes

Tuicr supports TextMate .tmTheme files for users who want to extend beyond the nine built-in presets (Solarized, Catppuccin, Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest).

Creating a Custom Theme

Write a standard .tmTheme XML file defining your color palette. Tuicr uses the syntect crate to parse these themes via ThemeSet::load_from_reader.

Installation Location

Place your .tmTheme file in the Tuicr themes directory:

• Unix: $XDG_CONFIG_HOME/tuicr/themes/
• Windows: %APPDATA%\tuicr\themes\

Activation

The filename (minus the .tmTheme extension) becomes the theme identifier. For example, installing my-custom.tmTheme allows activation via:

tuicr --theme my-custom

The loader uses the themes_dir helper function located at line 16 of src/theme/mod.rs to locate and parse these files.

How Themes are Applied Internally

Understanding the internal architecture helps when debugging theme issues or contributing to the codebase.

Core Theme Structure

The Theme struct in src/theme/mod.rs (lines 101-138) defines the default dark and light constructors, while lines 140-400 implement the preset themes. This struct supplies every color used by the UI, from diff addition highlights to comment-type hues.

Style Translation Layer

UI components do not access Theme fields directly. Instead, they use helper functions in src/ui/styles.rs that accept a &Theme reference and return ratatui::style::Style objects. Key helpers include:

• styles::diff_add_style(&theme) – line 13
• styles::status_bar_style(&theme) – line 65

Application Flow

When Tuicr initializes, the App struct (constructed in src/app/init.rs or src/app/mod.rs) stores a theme: Theme instance. This instance is populated by reading the theme setting from CLI arguments or config.toml via src/config/mod.rs. All rendering modules—including src/ui/app_layout.rs, src/ui/status_bar.rs, and src/ui/submit_modals.rs—pull colors from this single source of truth, ensuring consistent theming across the interface.

Summary

• Tuicr themes are controlled via the --theme flag, config.toml, or default to the dark palette.
• Built-in presets include Solarized, Catppuccin, Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest, defined in src/theme/mod.rs.
• Custom themes use standard .tmTheme files placed in $XDG_CONFIG_HOME/tuicr/themes/ or %APPDATA%\tuicr\themes\.
• Internal implementation uses the Theme struct parsed by src/config/mod.rs and rendered through helper functions in src/ui/styles.rs that generate ratatui style objects.

Frequently Asked Questions

How do I find the list of available built-in themes in Tuicr?

The built-in themes are defined as constructors in src/theme/mod.rs between lines 140-400. Available options include solarized_dark, solarized_light, catppuccin_mocha, catppuccin_latte, ayu_dark, one_dark, github_light, tokyo_night, gruvbox_dark, nord, and everforest. You can also view the current list by checking the Theme implementation in the source code or running tuicr --help to see example values.

Can I use my existing VS Code theme with Tuicr?

Yes, if your VS Code theme is available in TextMate .tmTheme format. Export or convert your theme to a .tmTheme file, place it in your system's Tuicr themes directory (~/.config/tuicr/themes/ on Linux/macOS or %APPDATA%\tuicr\themes\ on Windows), and activate it using tuicr --theme filename_without_extension. Tuicr uses syntect's ThemeSet::load_from_reader to parse these files.

Why isn't my custom theme appearing when I use the --theme flag?

Ensure the .tmTheme file is placed directly in the themes directory (not a subdirectory) and that you reference it by filename without the extension. Verify the directory path by checking the themes_dir helper implementation in src/theme/mod.rs line 16, which resolves the path using XDG directories on Unix or APPDATA on Windows. Also confirm the file has valid XML syntax, as syntect will fail to load malformed themes.

Does Tuicr support automatic light/dark mode switching based on terminal settings?

Currently, no. The default theme is hardcoded to Theme::dark() in src/theme/mod.rs when no explicit theme is provided. While the architecture supports extending this detection in the future, you must manually specify light themes via the --theme flag or config.toml to use palettes like Theme::light() or github_light.

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