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

> Explore Tuicr configuration options in this guide to customize themes, diff layouts, Git backends, and UI panels. Personalize your code review TUI experience without recompiling.

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

---

**Tuicr loads user preferences from a [`config.toml`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```toml

# ~/.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:

```bash

# Use a custom theme file directly

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

```

Programmatic usage in Rust:

```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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs)**: Defines the `Config` struct, default values, and parsing logic.
- **[`src/app.rs`](https://github.com/agavra/tuicr/blob/main/src/app.rs)**: `App::new()` consumes the configuration to initialize UI state.
- **[`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs)**: Implements color palette rendering based on selected themes.
- **[`src/output/markdown.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.