tuicr: TUI for Code Review

Review AI-generated diffs like a GitHub pull request, right from your terminal.

Why I built this

I use Claude a lot but there's no middle ground between "review every change" and "accept all edits". Reviewing every change slows things down to human speed, but accepting all edits makes the final review painful since I end up leaving comments one at a time and wait after each fix.

tuicr is the middle ground. Let the agent loose, review the changes like a normal PR, drop comments where needed, and export everything as structured feedback the agent can act on in one pass.

It makes my AI-assisted development go brrrrrr.

[!TIP] I pronounce it "tweaker"

Overview

A GitHub-style diff viewer in your terminal with vim keybindings. Scroll through changed files, leave comments, mark files as reviewed, and copy your full review to clipboard in a format ready to paste back to the agent.

Features

• Infinite scroll diff view - All changed files in one continuous scroll (GitHub-style)
• Vim keybindings - Navigate with j/k, Ctrl-d/u, g/G, {/}, [/]
• Expandable context - Press Enter on "... expand (N lines) ..." to reveal hidden context between hunks
• Comments - Add review-level, file-level, or line-level comments with types
• Visual mode - Select line ranges with v / V and comment on multiple lines at once
• Review tracking - Mark files as reviewed, persist progress to disk
• .tuicrignore support - Exclude matching files from review diffs
• Clipboard export - Copy structured Markdown optimized for LLM consumption
• Session persistence - Reviews auto-save and reload on restart
• Jujutsu support - Built-in jj support (tried first since jj repos are Git-backed)
• Mercurial support - Built-in hg support

Installation

Homebrew (macOS/Linux)

brew install agavra/tap/tuicr

Pre-built binaries

Download the latest release for your platform from GitHub Releases.

Mise (macOS/Linux/Windows)

mise use github:agavra/tuicr

From crates.io

cargo install tuicr

Using Nix

# build tuirc (links binary to ./result/bin/tuirc)
nix build github:agavra/tuicr

# or just run with
nix run github:agavra/tuicr

From source

git clone https://github.com/agavra/tuicr.git
cd tuicr
cargo install --path .

Usage

Run tuicr in any git, jujutsu, or mercurial repository:

cd /path/to/your/repo
tuicr

Detection order: Jujutsu → Git → Mercurial. Jujutsu is tried first because jj repos are Git-backed.

Options

By default, tuicr starts in commit selection mode.
If staged or unstaged changes exist, the first selectable entries are Staged changes and/or Unstaged changes.
When -r / --revisions is provided, tuicr opens that revision range directly. On narrow terminals (less than 100 columns), tuicr starts with the file list hidden; toggle it with ;e.

Configuration

Set a default theme in:

• Linux/macOS: $XDG_CONFIG_HOME/tuicr/config.toml (default: ~/.config/tuicr/config.toml)
• Windows: %APPDATA%\tuicr\config.toml

Examples:

theme = "catppuccin-mocha"

appearance = "system"
theme_dark = "gruvbox-dark"
theme_light = "gruvbox-light"

show_file_list = false
diff_view = "side-by-side"
wrap = true

comment_types = [
  { id = "note", label = "question", definition = "ask for clarification", color = "yellow" },
  { id = "suggestion", definition = "possible improvements" },
  { id = "issue", definition = "problems to fix" },
  { id = "praise", definition = "positive feedback" },
  { id = "nit", label = "nitpick", definition = "small optional tweaks", color = "#d19a66" }
]

show_file_list controls whether the file list panel is visible on startup (default: true). Toggle at runtime with ;e.

diff_view sets the default diff layout: "unified" (default) or "side-by-side". Toggle at runtime with :diff.

wrap enables line wrapping in the diff view (default: false). Toggle at runtime with :set wrap!.

comment_types replaces the default list and defines Tab cycle order. Each entry requires id and can optionally set label, definition, and color. Color accepts terminal names (for example yellow, light_red) or hex (#RRGGBB).

How comment_types works

• id is the stable internal value that is saved in sessions and used for matching.
• label is the visible tag shown in UI and export ([QUESTION], [NITPICK], etc.).
• definition is guidance text for LLMs, included in the exported Comment types: legend.
• color controls the comment badge/border color in the TUI.
• Declaring comment_types is a full replacement, if you define 2 types, only those 2 are available.
• If comment_types is missing, tuicr uses defaults: note, suggestion, issue, praise.
• Invalid entries are ignored with startup warnings, if all entries are invalid, tuicr falls back to defaults.

Minimal replacement example:

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

Theme resolution precedence:

1. --theme <THEME>
2. theme in config file path above (OS-specific)
3. theme_dark + theme_light in config (selected by appearance)
4. theme_dark only or theme_light only in config (appearance ignored)
5. --appearance <MODE> (only when no explicit theme or variants are set)
6. appearance in config (only when no explicit theme or variants are set)
7. built-in default (system)

Notes:

• Invalid --theme values cause an immediate non-zero exit.
• Unknown keys in config.toml are ignored with a startup warning.

Ignoring Files With .tuicrignore

tuicr reads .tuicrignore from the repository root and excludes matching files from all review diffs.

Rules follow gitignore-style pattern matching, including ! negation.

Example:

target/
dist/
*.lock
!Cargo.lock

Keybindings

Navigation

File Tree

Panel Focus

Review Actions

Visual Mode

Comment Mode

Commands

Commit Selection (startup)

Inline Commit Selector (multi-commit reviews)

When reviewing multiple commits, an inline commit selector panel appears at the top of the diff view. Focus it with ;k or Tab.

Confirm Dialogs

Review Output

When you export your review (:clip or confirm on :wq), tuicr copies structured Markdown to your clipboard. The format is optimized for pasting into AI agent conversations:

I reviewed your code and have the following comments. Please address them.

Comment types: ISSUE (problems to fix), SUGGESTION (improvements), NOTE (observations), PRAISE (positive feedback)

1. **[SUGGESTION]** `src/auth.rs` - Consider adding unit tests
2. **[ISSUE]** `src/auth.rs:42` - Magic number should be a named constant
3. **[NOTE]** `src/auth.rs:50-55` - This block could be refactored

Each comment is numbered and self-contained with its file path and line number or range (if applicable). If comment_types is configured, this legend and the [TYPE] tags reflect your configured labels and definitions.

Session Persistence

Sessions are automatically saved to ~/.local/share/tuicr/reviews/ (XDG compliant). When you reopen tuicr in the same repository, your previous review progress (comments, reviewed status) is restored.

Agent Integrations

tuicr ships a repo-managed skill bundle at skills/tuicr/.

It opens tuicr in a tmux split pane so you can review changes interactively and feed comments back to your coding agent.

Usage: /tuicr or ask your coding agent to "review my changes with tuicr".

Claude Code

Prerequisites: Claude Code running inside tmux, tuicr installed.

Installation (choose one):

# Copy the shared skill into Claude's local skills directory
mkdir -p ~/.claude/skills
cp -r /path/to/tuicr/skills/tuicr ~/.claude/skills/tuicr

Codex

Prerequisites: Codex running inside tmux, tuicr installed.

Installation:

# Copy the shared skill into the local agents skills directory
mkdir -p ~/.agents/skills
cp -r /path/to/tuicr/skills/tuicr ~/.agents/skills/tuicr