How to Integrate tuicr with Coding Agents Like Claude Code or Codex

You can integrate tuicr with coding agents by using the wrapper scripts in skills/tuicr/ to launch the TUI inside a terminal multiplexer, then drive the application programmatically via the CLI API and stdin/stdout streams.

The tuicr repository provides a Rust-based terminal UI for code review that exposes both a library API and agent-friendly wrapper scripts. Coding agents like Claude Code or Codex can automate code review workflows by spawning tuicr in a controlled terminal environment and manipulating its state through command-line interfaces and persistent JSON storage. This integration allows agents to programmatically add comments, navigate diffs, and submit reviews without manual intervention.

Architecture Overview

The integration relies on three core components: the App struct that manages application state, the ReviewStore that persists session data, and the wrapper scripts that bridge the agent's process with the terminal UI.

The App struct defined in src/app/mod.rs serves as the central state machine. When initialized via App::new(), it detects the version control backend, loads configuration from src/config/mod.rs, applies .tuicrignore filtering rules, and constructs the initial diff view. Agents interact with this state either by sending input events through the wrapper's stdin pipe or by invoking non-interactive CLI commands that manipulate the ReviewStore directly.

Setting Up the Wrapper Scripts

The skills/tuicr/ directory contains shell wrappers that launch tuicr inside terminal multiplexers. These scripts isolate the TUI session while keeping I/O streams accessible to the parent agent process.

Zellij Integration for Claude Code

For agents running inside Zellij, use the dedicated wrapper to spawn tuicr in a new pane:

./skills/tuicr/tuicr-wrapper-zellij.sh

This script creates a Zellij pane, launches the tuicr binary, and forwards the agent's stdin/stdout streams so the agent can send keyboard commands and capture rendered output.

Generic tmux Wrapper

For tmux-based environments, the generic wrapper provides the same functionality:

./skills/tuicr/tuicr-wrapper.sh

Both wrappers handle terminal initialization and ensure the agent maintains a bidirectional communication channel with the running tuicr instance.

Herdr Integration

Alternative multiplexers are supported via specific wrappers:

./skills/tuicr/tuicr-wrapper-herdr.sh

The wrapper scripts are intentionally minimal—agents can customize the surrounding multiplexing environment while the core I/O forwarding remains consistent.

Programmatic Control via the CLI API

tuicr exposes non-interactive subcommands through src/cli.rs that allow agents to manipulate review sessions without opening the UI. The review subcommand supports adding, editing, and deleting comments programmatically.

To add a comment to the active session:

tuicr review add --repo . --input '{"file":"src/main.rs","line":42,"body":"Consider extracting this into a helper function"}'

Agents can query the current state or export results using the colon-prefixed commands:

# Export the review as Markdown to stdout

tuicr :export --stdout > review.md

# Copy the review to clipboard for pasting into other tools

tuicr :export --clipboard

Managing State with ReviewStore

The ReviewStore in src/review_store.rs handles persistence of review sessions as JSON files stored under $XDG_DATA_HOME/tuicr/reviews/. Agents can read or write these files directly to synchronize state across multiple tuicr instances or to pre-populate review data before launching the UI.

Key capabilities include:

• Reading session state: Parse the JSON files to extract existing comments and review progress
• Writing session state: Generate review data programmatically and save it to the store before launching tuicr
• Cross-instance sync: Multiple agents or tuicr instances can share state by accessing the same ReviewStore directory

Remote Review Submission

For agents needing to submit reviews to GitHub or GitLab, the forge module in src/forge/submit.rs provides the submission pipeline. The forge::submit function constructs the API payload, executes background network calls, and updates the UI once the review posts successfully.

Agents can trigger remote submission via:

tuicr forge submit --provider github --pr 123

This pipeline handles authentication, comment formatting, and error retry logic automatically.

Practical Integration Workflow

Follow these steps to integrate tuicr into your coding agent's workflow:

1. Initialize the session: Launch tuicr using the appropriate wrapper script for your terminal multiplexer (Zellij, tmux, or Herdr)
2. Load the repository: The App struct automatically detects Git repositories and loads the diff when started in a project directory
3. Inject comments: Use tuicr review add commands to programmatically add findings from static analysis or AI review
4. Navigate programmatically: Send keypresses to the wrapper's stdin to control the UI (e.g., printf "j" to move to the next file)
5. Export results: Capture the final review using :export --stdout and process the Markdown in your agent's downstream pipeline

Summary

• Wrapper scripts in skills/tuicr/ enable coding agents to launch tuicr inside terminal multiplexers while maintaining I/O control
• The App struct in src/app/mod.rs manages application state and VCS integration
• ReviewStore in src/review_store.rs provides JSON-based persistence for cross-instance state synchronization
• Non-interactive CLI commands allow agents to add comments and export reviews without manual UI interaction
• The forge module supports automated submission of reviews to GitHub and GitLab

Frequently Asked Questions

How do I send keyboard commands to tuicr from my coding agent?

Write the key characters to the stdin of the wrapper script process. For example, sending j moves to the next file, while Enter opens a comment box. The wrapper forwards these bytes directly to tuicr's crossterm event handler.

Can multiple agents access the same tuicr session simultaneously?

Yes. Multiple processes can read from the ReviewStore JSON files located at $XDG_DATA_HOME/tuicr/reviews/. However, only one process should write to the store at a time to avoid conflicts. Agents should coordinate writes or use file locking when updating session state.

What is the difference between using the wrapper scripts versus calling tuicr review directly?

The wrapper scripts launch the interactive TUI and maintain a live session, suitable for agents that need to capture rendered output or send real-time navigation commands. The tuicr review CLI commands operate non-interactively against the persistent store, making them ideal for headless automation that doesn't require the terminal interface.

How do I configure tuicr to ignore certain files when my agent scans the repository?

Create a .tuicrignore file in your repository root. The App initialization code reads this file during startup and filters matching paths from the diff view, ensuring your agent only processes relevant source files.

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