How to Use tuicr with Jujutsu (jj) as the VCS Backend

tuicr automatically detects Jujutsu repositories and delegates all VCS operations to the jj backend without requiring manual configuration.

The open-source code review tool tuicr (agavra/tuicr) includes first-class support for Jujutsu, a Git-compatible version control system. When you run tuicr inside a Jujutsu workspace, the application automatically selects the appropriate backend to handle diff loading, context fetching, and commit-range operations. This seamless integration allows developers to use tuicr's TUI interface with Jujutsu's advanced features while maintaining full Git compatibility.

Automatic Detection of Jujutsu Repositories

tuicr prioritizes Jujutsu over other version control systems during repository detection. In src/vcs/mod.rs, the detect_vcs function implements a cascading check that attempts Jujutsu first, followed by Git, then Mercurial (lines 24-34).

When the function discovers a .jj directory—indicating a Jujutsu workspace—it invokes JjBackend::discover to create a backend instance. This automatic detection requires no flags or configuration files; tuicr simply needs to find the jj executable on your PATH.

JjBackend Implementation and CLI Delegation

The Jujutsu backend implementation resides in src/vcs/jj.rs, where the JjBackend struct wraps the Jujutsu CLI to perform all version control operations. This backend implements the VcsBackend trait defined in src/vcs/traits.rs, which standardizes methods such as get_working_tree_diff, fetch_context_lines, and commit-range handling across different VCS providers.

Because Jujutsu repositories remain Git-backed, the JjBackend preserves Git compatibility (including sparse checkout support) while exposing Jujutsu-specific capabilities. Internally, tuicr delegates to commands like jj file show and jj diff to retrieve file contents and differences, ensuring consistent behavior with your local Jujutsu configuration.

Forcing the Jujutsu Backend

While automatic detection works for pure Jujutsu repositories, hybrid environments containing both .jj and .git directories may require explicit backend selection. You can force tuicr to use the Jujutsu backend using either an environment variable or a command-line flag (parsed in src/main.rs).

Use the TUICR_VCS environment variable:

TUICR_VCS=jj tuicr

Or pass the --vcs flag directly:

tuicr --vcs jj

This override ensures tuicr uses JjBackend even when Git detection would normally take precedence.

Practical Usage Examples

Initialize a new Jujutsu repository and launch tuicr:

# Create and enter a new Jujutsu repository

jj init myproject
cd myproject

# Launch tuicr - automatically detects the jj backend

tuicr

Execute subcommands that interact with the VCS layer:

# List active review sessions

tuicr review list

# Add a code review comment

tuicr review add --input '{"file":"src/main.rs","line":10,"text":"Consider refactoring"}'

Force the Jujutsu backend in a mixed environment:

# Override auto-detection when both .jj and .git exist

tuicr --vcs jj review list

Summary

• Automatic detection: tuicr checks for Jujutsu first in src/vcs/mod.rs via the detect_vcs function, activating JjBackend when a .jj directory is present.
• CLI delegation: The backend in src/vcs/jj.rs wraps jj commands like jj diff and jj file show to handle all VCS operations.
• Zero configuration: No setup required beyond installing jj and ensuring it is on your PATH.
• Explicit control: Use TUICR_VCS=jj or --vcs jj to force the backend when working in repositories with multiple VCS markers.

Frequently Asked Questions

Does tuicr require manual configuration to work with Jujutsu?

No. tuicr automatically detects Jujutsu repositories by looking for the .jj directory and immediately delegates all operations to the JjBackend implementation. As long as the jj executable is available on your system PATH, tuicr will function without additional flags or configuration files.

What happens if a repository has both .jj and .git directories?

By default, tuicr's detect_vcs function prioritizes Jujutsu over Git, so it will select the jj backend automatically. However, if you need to guarantee Jujutsu mode or override this priority, set the environment variable TUICR_VCS=jj or use the --vcs jj command-line flag when launching tuicr.

Which jj CLI commands does tuicr use internally?

According to the source code in src/vcs/jj.rs, the JjBackend implementation delegates to several Jujutsu CLI commands including jj file show for retrieving file contents and jj diff for generating working tree comparisons. These commands power the diff views and context fetching within the tuicr interface.

Is Git compatibility preserved when using tuicr with Jujutsu?

Yes. Because Jujutsu uses a Git-backed storage model, the JjBackend maintains full Git compatibility—including support for sparse checkouts—while still exposing Jujutsu-specific features such as bookmarks and patch queues. This allows tuicr to work correctly with existing Git infrastructure even when operating through the Jujutsu abstraction layer.

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