How to Define Custom Comment Types in tuicr: Configuring Issue, Suggestion, Note, and Praise Categories

Define custom comment types in tuicr by adding a comment_types array to your TOML configuration file at $XDG_CONFIG_HOME/tuicr/config.toml (Linux/macOS) or %APPDATA%\tuicr\config.toml (Windows), with each entry specifying id, optional label, color, and definition fields.

tuicr, the terminal-based code review tool by agavra/tuicr, ships with no predefined comment categories by default. By configuring comment_types, you replace the untyped None mode with a fully customized classification system that controls badges in the TUI, export tags in markdown, and the tab-cycle order for comment entry.

How comment_types Replaces Built-in Behavior

When comment_types is absent from your configuration, tuicr operates in untyped mode: all comments lack badges, export without [TYPE] prefixes, and the tab cycle contains only the implicit None type.

Adding comment_types completely replaces this behavior. The array you define becomes the sole source of comment classifications. According to the configuration schema in src/model/comment.rs:

• The first valid entry becomes the default type for new comments
• The array order determines tab-cycle sequence
• An implicit None type is always appended for untyped comments
• Invalid entries trigger startup warnings and are skipped

Structure of a Comment Type Definition

Each entry in comment_types supports four fields:

Field	Required	Purpose
id	Yes	Stable identifier stored in review sessions; used for matching and persistence
label	No	Display text for badges and export tags; defaults to id.to_uppercase()
definition	No	Description shown to LLMs and in the "Comment types:" export legend
color	No	Badge color as terminal name (yellow, light_red) or hex (#RRGGBB)

The parsing logic in src/model/comment.rs validates these fields and applies defaults for optional values.

Minimal Custom Comment Types Configuration

Start with this two-type setup in your tuicr config:

# ~/.config/tuicr/config.toml

comment_types = [
  { id = "question", definition = "ask for clarification" },
  { id = "blocker", color = "red", definition = "must be fixed before merge" },
]

This configuration yields:

• [QUESTION] badges with default coloring
• [BLOCKER] badges in red
• Untyped comments available via the implicit None type

Full Example: Issue, Suggestion, Note, and Praise Types

Replicate and extend the built-in style shown in docs/CONFIG.md with this complete configuration:

comment_types = [
  { id = "note",       label = "NOTE",       definition = "general observations",    color = "yellow" },
  { id = "suggestion", label = "SUGGESTION", definition = "possible improvements" },
  { id = "issue",      label = "ISSUE",      definition = "problems to fix",         color = "red" },
  { id = "praise",     label = "PRAISE",     definition = "positive feedback",       color = "green" },
  { id = "nit",        label = "NITPICK",    definition = "small optional tweaks",   color = "#d19a66" },
]

Key implementation details from the source:

• Badge rendering: src/ui/comment_panel.rs and src/ui/comment_navigator.rs apply the label and color to terminal UI elements
• Markdown export: src/output/markdown.rs generates [TYPE] prefixes and the "Comment types:" legend using these same values
• Tab cycling: Press <Tab> in comment mode to rotate through note → suggestion → issue → praise → nit → None

Where Comment Types Appear in the UI and Export

Location	Effect of Configuration
TUI comment list	Colored badges display label next to each comment (src/ui/comment_panel.rs)
Sidebar navigator	Types filter and organize the comment overview (src/ui/comment_navigator.rs)
Markdown export	[TYPE] prefix prepended to each comment; legend lists all definition values (src/output/markdown.rs)
LLM context	definition fields populate the "Comment types:" section sent to language models

Configuration File Locations by Platform

Platform	Path
Linux/macOS	$XDG_CONFIG_HOME/tuicr/config.toml (typically ~/.config/tuicr/config.toml)
Windows	%APPDATA%\tuicr\config.toml

tuicr reads this file at startup. Changes take effect on the next launch.

Validation and Error Handling

The parser in src/model/comment.rs enforces these rules:

• Missing id field: entry discarded with warning
• Duplicate id values: later entries override earlier ones
• Invalid color values: fallback to terminal default
• Empty comment_types array or all-invalid entries: reverts to None-only mode

Summary

• tuicr uses comment_types in config.toml to define custom comment types including issue, suggestion, note, and praise categories
• Each type requires an id and accepts optional label, color, and definition fields
• The configuration replaces rather than merges with defaults; first entry becomes default
• Comment types control TUI badges, markdown export tags, and tab-cycle order
• Implementation spans src/model/comment.rs, src/ui/comment_panel.rs, src/ui/comment_navigator.rs, and src/output/markdown.rs

Frequently Asked Questions

What happens if I omit the comment_types key entirely?

tuicr runs in untyped mode. All comments lack badges, export without [TYPE] prefixes, and the tab cycle contains only the implicit None type for leaving untyped comments.

Can I modify comment types without restarting tuicr?

No. Configuration changes require a restart. tuicr parses config.toml once at startup and does not hot-reload the comment_types array.

Why does my custom type show a different label than expected?

Check your label field. If omitted, tuicr applies id.to_uppercase() automatically. For case-sensitive labels or lowercase display, explicitly set label to your preferred text.

How do I use a custom hex color for badges?

Specify color as a six-digit hex string with leading hash: color = "#d19a66". The color parser in src/model/comment.rs accepts standard terminal names (yellow, light_red, green) or hex values for precise control.

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