Tuicr Configuration Options: A Complete Guide to Customizing Your Code Review TUI

Tuicr loads user preferences from a config.toml file located at ~/.config/tuicr/config.toml (Unix) or %APPDATA%\tuicr\config.toml (Windows), allowing you to customize themes, diff layouts, Git backends, and UI panels without recompiling.

The open-source terminal UI for code reviews, agavra/tuicr, exposes a comprehensive set of configuration options that let you tailor the interface to your workflow. These settings are defined in the configuration module at src/config/mod.rs and applied at startup before the interface renders. Understanding these Tuicr configuration options allows you to control everything from color schemes to diff rendering behavior without touching the source code.

Core Tuicr Configuration Options

The Config struct in src/config/mod.rs defines the available fields, all of which are optional and provide sensible defaults if omitted.

Theme and Appearance

The theme option accepts a String value that selects the color palette. It defaults to "dark" but can reference any bundled theme name or a path to a custom .tmTheme file in $XDG_CONFIG_HOME/tuicr/themes/. The dark boolean flag (default true) toggles between dark and light variants when the selected theme supports both.

Diff View Settings

Control how code changes are rendered with diff_view and wrap. The diff_view parameter accepts either "side-by-side" (two-column layout) or "unified" (classic diff format). The wrap boolean (default false) enables line wrapping within diff panels; when disabled, long lines truncate with horizontal scrolling.

UI Panel Visibility

Manage workspace layout through show_file_list and show_pr_info. Setting show_file_list to false (default true) hides the left-hand file browser on startup, though it remains accessible via the <leader>e shortcut. The show_pr_info flag (default true) controls visibility of the pull request description panel during review sessions.

Git Backend and File Watching

The backend option selects the Git implementation, accepting "libgit2" (default) or "cli". The CLI backend is useful for sparse checkouts or when libgit2 compatibility issues arise. The review_watch_interval_ms setting (default 1000) configures how often Tuicr polls the review session file for external changes; set to 0 to disable auto-reload.

Export Customization

The export subsection customizes markdown output generated by :clip or :export commands. These settings, processed in src/output/markdown.rs, modify introductory text, "Reviewing..." paragraphs, and comment-type legends in exported review summaries.

Configuration Loading and Validation

According to the source code in src/config/mod.rs, Tuicr resolves the configuration path using the directories crate to locate $XDG_CONFIG_HOME/tuicr/config.toml (or the Windows equivalent). The loading sequence follows four steps:

1. Path Resolution: The directories crate identifies the platform-specific config directory.
2. Deserialization: The TOML file is parsed using toml::de::from_str into the Config struct.
3. Validation: The module verifies enum values (e.g., ensuring diff_view is valid) and warns about unknown keys while ignoring them for forward compatibility.
4. Application: The App::new() constructor in src/app.rs receives the resolved configuration and propagates values to the theme loader, diff renderer, and UI state managers.

Practical Configuration Examples

Create or modify your configuration file to customize behavior:

# ~/.config/tuicr/config.toml

theme = "dracula"
dark = true
diff_view = "unified"
wrap = true
show_file_list = false
review_watch_interval_ms = 2000
backend = "cli"

Override settings via command line:

# Use a custom theme file directly

tuicr --theme ~/.config/tuicr/themes/custom.tmTheme

Programmatic usage in Rust:

use tuicr::config::Config;

let mut cfg = Config::default();
cfg.diff_view = "side-by-side".into();
cfg.wrap = false;
// Pass cfg to App::new(cfg)

Implementation Reference

Key files governing Tuicr configuration behavior:

• src/config/mod.rs: Defines the Config struct, default values, and parsing logic.
• src/app.rs: App::new() consumes the configuration to initialize UI state.
• src/ui/styles.rs: Implements color palette rendering based on selected themes.
• src/output/markdown.rs: Handles export formatting controlled by the export config section.

Summary

• Tuicr reads settings from ~/.config/tuicr/config.toml (Linux/macOS) or %APPDATA%\tuicr\config.toml (Windows).
• The theme and dark options control the color scheme, supporting bundled names or custom .tmTheme files.
• diff_view and wrap customize how code differences appear in the terminal.
• show_file_list and show_pr_info manage default panel visibility.
• backend selects between libgit2 and Git CLI implementations, while review_watch_interval_ms controls external file polling.
• Unknown configuration keys trigger warnings but are ignored to maintain forward compatibility.

Frequently Asked Questions

Where does Tuicr look for the configuration file?

Tuicr uses the directories crate to resolve the configuration path, checking $XDG_CONFIG_HOME/tuicr/config.toml on Unix systems or %APPDATA%\tuicr\config.toml on Windows. If the file is missing, Tuicr runs with built-in defaults defined in src/config/mod.rs.

Can I use a custom color theme with Tuicr?

Yes. Set the theme option to either a bundled theme name like "dracula" or the absolute path to a .tmTheme file. Custom themes should be placed in $XDG_CONFIG_HOME/tuicr/themes/ for path resolution, and the dark boolean toggles between light and dark variants when available.

How do I switch between side-by-side and unified diff views?

Set the diff_view configuration option to "side-by-side" for a two-column layout showing old and new code separately, or "unified" for the traditional inline diff format. This value is validated during startup in src/config/mod.rs to ensure it matches supported variants.

What happens if I specify an unknown configuration key?

Tuicr's configuration parser logs a warning for unrecognized keys but continues execution using default values. This forward-compatible approach ensures that configuration files remain valid across version upgrades even as options are added or removed.

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