How to Integrate Tuicr with GitHub: A Complete Setup Guide

Tuicr integrates with GitHub through the official GitHub CLI (gh), implementing the ForgeBackend trait in src/forge/github/gh.rs to fetch pull requests, render diffs, and submit reviews directly from your terminal.

Tuicr is a terminal-based code review tool that streamlines GitHub workflows without leaving the command line. To integrate Tuicr with GitHub, you must install and authenticate the GitHub CLI, which serves as the underlying backend for all repository operations. This integration lives in the src/forge/github package and enables you to browse PRs, view diffs, and submit reviews using Tuicr's TUI interface.

Prerequisites: Install the GitHub CLI

Tuicr requires the gh binary to be present in your system PATH. According to the source code in src/forge/github/gh.rs, Tuicr checks for the CLI's presence during initialization and aborts with a clear error message—GitHub integration requires gh``—if the binary is missing.

Install the GitHub CLI using your package manager:

# macOS

brew install gh

# Linux (Debian/Ubuntu)

sudo apt install gh

# Linux (Fedora)

sudo dnf install gh

Authenticate with GitHub

Before using Tuicr, authenticate the GitHub CLI to store your OAuth token. Tuicr reuses this authentication context rather than managing tokens independently.

Run the following command and follow the interactive prompts:

gh auth login

For GitHub Enterprise Server, specify your hostname:

gh auth login --hostname github.company.com

The authentication state is shared between gh and Tuicr, so you only need to complete this step once per environment.

Open and Review Pull Requests

Fetching PR Metadata

To open a PR in Tuicr, use the command tuicr pr open <pr-url>. Internally, Tuicr parses the URL to create a PrSessionKey, then calls GitHubGhBackend::get_pull_request() to fetch metadata.

In src/forge/github/pr_info.rs, Tuicr executes gh pr view --json to retrieve extended PR details including the title, description, author, and review status:

tuicr pr open https://github.com/agavra/tuicr/pull/42

Loading the Diff

Tuicr retrieves the diff text using GitHubGhBackend::get_pull_request_diff() in src/forge/github/gh.rs. This method executes gh pr diff without the --patch flag (a behavior verified by the regression test should_not_pass_patch_flag_to_gh_pr_diff), ensuring the raw diff text serves as the source of truth for rendering and comment anchoring.

Adding Inline Comments

While reviewing in the TUI:

1. Navigate to a specific line using arrow keys
2. Press a (or your configured keybinding) to add a line comment
3. Type your comment in the popup dialog
4. Press Ctrl-S to save the comment locally

Tuicr stores comments in src/model/comment.rs and maps each to a GitHub-style anchor using path, line number, and side (left/right) before submission.

Submit Reviews to GitHub

When ready to submit, press : to enter command mode, type submit, and press Enter. For draft reviews, use :submit draft.

The submission logic resides in src/forge/github/submit.rs. Tuicr builds a CreateReviewRequest payload and passes it to GitHubGhBackend::create_review(). To avoid CLI-argument length limits, the backend pipes the JSON payload via stdin using gh api ... --input -:

# Inside Tuicr TUI

:submit

This POSTs the review to the GitHub API endpoint /repos/{owner}/{repo}/pulls/{number}/reviews with all your inline comments attached.

Error Handling and Troubleshooting

Errors from the GitHub CLI are translated in the map_gh_error function within src/forge/github/gh.rs. Common failure modes include:

• Missing CLI: Tuicr displays "GitHub integration requires gh" and exits
• Authentication failures: Prompts direct users to run gh auth login again
• API errors: HTTP 422 responses are parsed and displayed in the status bar with friendly messaging

Summary

• Install gh: Tuicr requires the GitHub CLI binary available in your PATH, verified at runtime in src/forge/github/gh.rs
• Authenticate once: Run gh auth login to store credentials that Tuicr inherits automatically
• Open PRs: Use tuicr pr open <url> to parse the PR and launch the TUI, fetching metadata via src/forge/github/pr_info.rs
• Review locally: Navigate diffs and press a to add anchored comments stored in src/model/comment.rs
• Submit remotely: Execute :submit to POST reviews via src/forge/github/submit.rs using gh api with stdin piping

Frequently Asked Questions

Do I need to generate a personal access token for Tuicr?

No. Tuicr does not require manual token generation. It relies entirely on the GitHub CLI's authentication state. As long as you have run gh auth login, Tuicr can access the API using those stored credentials without additional configuration.

Can I use Tuicr with GitHub Enterprise Server?

Yes. Tuicr supports GitHub Enterprise through the gh CLI's multi-account authentication. Run gh auth login --hostname <your-enterprise-host> before launching Tuicr. The ForgeBackend trait implementation in src/forge/github/gh.rs respects the authentication context for the specified hostname.

Why does Tuicr use the GitHub CLI instead of calling the REST API directly?

Tuicr delegates to gh to avoid managing OAuth tokens, refresh logic, and enterprise configuration manually. By wrapping the CLI in src/forge/github/gh.rs, Tuicr inherits gh's robust authentication handling while focusing on the TUI experience. This approach also ensures that security updates to the CLI automatically benefit Tuicr users.

How do I view existing review comments in Tuicr?

Tuicr retrieves existing review threads via gh api graphql as implemented in src/forge/github/review_threads.rs. When you open a PR, the TUI fetches and displays existing comments alongside the diff, allowing you to see previous feedback before adding new comments or submitting your review.

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