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

> Learn to define custom comment types in tuicr config. Easily categorize issues, suggestions, notes, and praise for better workflow. Enhance your project management today.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```toml

# ~/.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`](https://github.com/agavra/tuicr/blob/main/docs/CONFIG.md) with this complete configuration:

```toml
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`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_panel.rs) and [`src/ui/comment_navigator.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_navigator.rs) apply the `label` and `color` to terminal UI elements
- **Markdown export**: [`src/output/markdown.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_panel.rs)) |
| **Sidebar navigator** | Types filter and organize the comment overview ([`src/ui/comment_navigator.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_navigator.rs)) |
| **Markdown export** | `[TYPE]` prefix prepended to each comment; legend lists all `definition` values ([`src/output/markdown.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs), [`src/ui/comment_panel.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_panel.rs), [`src/ui/comment_navigator.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_navigator.rs), and [`src/output/markdown.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs) accepts standard terminal names (`yellow`, `light_red`, `green`) or hex values for precise control.