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

> Integrate tuicr with coding agents like Claude Code or Codex. Use wrapper scripts to launch TUI in a terminal multiplexer and drive the app programmatically via CLI API and stdin/stdout.

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

---

**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](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs) defined in [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```bash
./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:

```bash
./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:

```bash
./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`](https://github.com/agavra/tuicr/blob/main/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:

```bash
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:

```bash

# 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](https://github.com/agavra/tuicr/blob/main/src/review_store.rs) in [`src/review_store.rs`](https://github.com/agavra/tuicr/blob/main/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](https://github.com/agavra/tuicr/blob/main/src/forge/submit.rs) in [`src/forge/submit.rs`](https://github.com/agavra/tuicr/blob/main/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:

```bash
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`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs) manages application state and VCS integration
- **ReviewStore** in [`src/review_store.rs`](https://github.com/agavra/tuicr/blob/main/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](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs) reads this file during startup and filters matching paths from the diff view, ensuring your agent only processes relevant source files.