How to Customize Comment Types with Colors and Definitions in tuicr Config

tuicr allows you to define custom comment classifications with unique labels, descriptions, and display colors by configuring the comment_types array in your config.toml file, which the application parses into CommentTypeConfig structs at startup.

The agavra/tuicr repository is a terminal-based code review tool that supports customizable comment classifications to streamline your workflow. You can tailor how different comment types appear in the UI by modifying your local configuration file. This guide explains how to customize comment types with colors and definitions in tuicr config using the CommentTypeConfig structure and related parsing logic.

Understanding the CommentTypeConfig Structure

The data model for custom comment types lives in src/config/mod.rs. The CommentTypeConfig struct defines four fields that control how each classification appears in the terminal interface:

pub struct CommentTypeConfig {
    /// Identifier used in the comment body, e.g. "issue"
    pub id: String,
    /// Human-readable label shown in the UI (optional)
    pub label: Option<String>,
    /// Long-form description used in the export header (optional)
    pub definition: Option<String>,
    /// Colour for UI rendering – a named colour or `#RRGGBB` (optional)
    pub color: Option<String>,
}

When tuicr loads, the parse_comment_types function scans the configuration file and builds a Vec<CommentTypeConfig> from valid entries. Invalid entries trigger warnings and are ignored, ensuring the UI remains stable even with malformed configuration.

Configuring comment_types in config.toml

All customization happens in the config.toml file located at $XDG_CONFIG_HOME/tuicr/ on Unix systems or %APPDATA%/tuicr/ on Windows. The configuration recognizes two primary keys for comment type management:

• comment_type_prefix – A boolean flag (default true) that controls whether tuicr prepends "[TYPE] " to comment bodies before submission.
• comment_types – An array of objects matching the CommentTypeConfig schema.

Adding Custom Comment Types

Define new classifications by appending entries to the comment_types array. Each entry requires an id and optionally accepts label, definition, and color.

# $XDG_CONFIG_HOME/tuicr/config.toml

comment_type_prefix = true

[[comment_types]]
id = "question"
label = "question"
definition = "A clarifying question"
color = "yellow"

[[comment_types]]
id = "bug"
label = "bug"
definition = "A definite defect"
color = "#FF5555"

With this configuration, the Comment Navigator displays yellow "question" tags and red "bug" tags. When submitting comments, the body automatically prepends [question] or [bug] because comment_type_prefix is enabled.

Disabling the Type Prefix

To send raw comment bodies without automatic type tagging, set the prefix flag to false:

comment_type_prefix = false

The UI continues to color-code comments based on their assigned types, but the remote platform receives the text without [TYPE] markers. This is useful when the forge provides its own classification system.

Overriding Built-in Types

tuicr ships with four default classifications: note, issue, suggestion, and praise. You can override any built-in type by defining a new entry with the same id. The parser retains the first valid occurrence and ignores subsequent duplicates, issuing a warning to the console.

[[comment_types]]
id = "issue"
label = "critical"
color = "#FF0000"
definition = "A blocking issue that must be resolved"

This replaces the default "issue" styling with red coloring and updated labeling.

How the UI Applies Colors and Labels

The UI layer in src/ui/styles.rs looks up each comment's type_id (stored in src/model/comment.rs) and applies the corresponding color from its CommentTypeConfig. Colors render in both the comment line prefix and the Comment Navigator panel.

Supported color values include ratatui named colors (like "yellow", "blue", "green") and hexadecimal RGB strings (like "#FF5555"). If no color is specified, the UI falls back to default terminal styling.

Parsing and Validation

The parse_comment_types function in src/config/mod.rs handles validation during startup. It ensures that:

• Each entry has a valid string id.
• Optional fields conform to expected types.
• Duplicate IDs are detected and filtered, keeping only the first definition.

This validation prevents runtime crashes from configuration errors while providing clear feedback about ignored entries.

Summary

• Define custom types using the CommentTypeConfig struct in src/config/mod.rs via the comment_types array in config.toml.
• Control visual styling with the color field, supporting named colors or hex codes like "#FF5555".
• Manage prefixes with the comment_type_prefix boolean to toggle automatic [TYPE] tagging on comment submission.
• Override defaults by redefining built-in IDs (note, issue, suggestion, praise); duplicates are ignored with warnings.
• Locate config files at $XDG_CONFIG_HOME/tuicr/config.toml on Unix or %APPDATA%/tuicr/config.toml on Windows.

Frequently Asked Questions

Where is the tuicr configuration file located?

tuicr follows platform conventions for configuration storage. On Unix systems, the file resides at $XDG_CONFIG_HOME/tuicr/config.toml, typically expanding to ~/.config/tuicr/config.toml. Windows users should place the file at %APPDATA%/tuicr/config.toml.

What color formats are supported for comment types?

The color field accepts ratatui named colors such as "yellow", "red", or "blue", as well as hexadecimal RGB strings formatted as "#RRGGBB". Invalid color values fall back to default terminal styling without breaking the application.

Can I override the default comment types like "issue" or "suggestion"?

Yes. The four built-in types—note, issue, suggestion, and praise—can be overridden by defining new entries with matching id values. The parser uses the first valid definition encountered and logs warnings for any subsequent duplicates.

What happens if I have duplicate comment type IDs in my config?

When parse_comment_types encounters duplicate id values, it retains the first valid entry and discards the rest. The application emits a warning to notify you of the ignored duplicates, ensuring the UI initializes with a consistent set of comment types.

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