How RTK Integrates with GitHub CLI for Managing Pull Requests and Issues

RTK wraps the official GitHub CLI (gh) to rewrite JSON output into compact, human-readable summaries, reducing token consumption by 30% or more while maintaining full passthrough compatibility for raw data access.

The RTK (Rust Token Killer) project provides a drop-in integration layer for the GitHub CLI that automatically filters and formats gh output. By intercepting subcommands like pr, issue, and run, RTK deserializes JSON responses and applies custom formatters to strip unnecessary content before displaying results. This RTK GitHub CLI integration ensures that developers receive only the most relevant information, dramatically reducing context window usage when working with LLMs.

Architecture of the GitHub CLI Integration

The integration logic resides primarily in src/cmds/git/gh_cmd.rs, where the run() function acts as the central dispatcher. When you execute rtk gh, the command flow proceeds through several specialized stages that balance intelligent filtering with zero-risk compatibility.

Command Dispatch and Routing

The entry point run(subcommand, args, ...) matches the first argument against supported GitHub CLI commands including pr, issue, run, repo, and api. Located at lines 82-99 of gh_cmd.rs, this router forwards command arguments to dedicated handlers that implement subcommand-specific formatting logic.

Passthrough Detection for Raw Output

RTK respects explicit requests for unfiltered data through the has_json_flag() utility (lines 10-15). When it detects flags like --json, --web, or other raw-output indicators, the system routes the request through run_passthrough() (lines 44-48). This guarantees that developers retain full access to the native gh functionality when needed, ensuring zero-risk compatibility with the underlying CLI.

Argument Parsing and Identifier Extraction

Before executing GitHub CLI calls, extract_identifier_and_extra_args() (lines 15-38) isolates PR numbers, issue IDs, and run identifiers from flag arguments like -R or --repo. This parser respects flags that consume subsequent values, ensuring that repository contexts and numeric identifiers are correctly separated from general flags before building the final command.

JSON Filtering and Token Optimization

The core value of the integration lies in its ability to request compact JSON payloads from GitHub and transform them into dense, readable output.

Structured Data Processing

For each supported subcommand, RTK constructs gh … --json … calls via run_gh_json() (lines 64-79). These requests ask the GitHub CLI to return specific fields in JSON format, which RTK then deserializes into serde_json::Value structures. Dedicated formatter functions like format_pr_list() and format_pr_view() map these structures to concise strings optimized for LLM consumption.

Markdown Body Cleaning

PR and issue descriptions often contain verbose Markdown that consumes excessive tokens. The filter_markdown_body() function (lines 25-45) processes these bodies to strip HTML comments, badge lines, image-only lines, and horizontal rules while preserving code blocks intact. According to the repository's internal tests, this process achieves 30% or greater token savings compared to raw output.

Compact List Rendering

When displaying collections, RTK implements aggressive truncation to minimize noise. The format_pr_list() and format_issue_list() functions limit output to the first 20 items and truncate titles to 60 characters. With the --ultra-compact flag, the formatters replace verbose status text with tiny icons like O (open), M (merged), and C (closed), further reducing token count.

Execution Flow and Telemetry

Beyond formatting, the integration tracks performance metrics to quantify token savings.

The filtered execution path flows through crate::core::runner::run_filtered in src/core/runner.rs, which captures stdout, applies the appropriate formatter closure, and handles error conditions. Each successful filtered execution records metrics to an SQLite database via src/core/tracking.rs, enabling the rtk gain command to report exact token savings per operation.

Common Usage Examples

The following examples demonstrate practical workflows using RTK's GitHub CLI integration.

List recent pull requests with default compact formatting:

rtk gh pr list --repo rtk-ai/rtk

View detailed PR information with cleaned Markdown bodies:

rtk gh pr view 123 --repo rtk-ai/rtk

Generate ultra-compact output ideal for LLM prompts:

rtk gh pr list --repo rtk-ai/rtk --ultra-compact

Access raw JSON when you need complete data:

rtk gh pr view 123 --json

Manage issues with filtered output:

rtk gh issue list --repo rtk-ai/rtk
rtk gh issue view 45

Check workflow run status:

rtk gh run list --repo rtk-ai/rtk --ultra-compact

View repository summaries:

rtk gh repo view --repo rtk-ai/rtk

Key Source Files

Understanding the implementation requires familiarity with these core files:

• src/cmds/git/gh_cmd.rs: Contains the main integration logic including run(), filter_markdown_body(), and all formatter functions. This file handles argument parsing, passthrough detection, and JSON-to-text conversion.
• src/core/runner.rs: Implements run_filtered() to execute external commands, capture output, and apply formatting closures before returning results to the user.
• src/core/tracking.rs: Persists token-saving statistics to SQLite, supporting the rtk gain reporting functionality.
• src/core/utils.rs: Provides helper utilities including truncate() for string shortening and ok_confirmation() for user prompts.
• src/main.rs: The top-level CLI dispatcher that routes gh commands to the gh_cmd module.

Summary

• RTK acts as an intelligent wrapper around the GitHub CLI, intercepting pr, issue, run, repo, and api subcommands to apply token-efficient formatting.
• The system automatically detects raw-output flags like --json and routes requests through run_passthrough() to maintain full compatibility with native gh behavior.
• Markdown cleaning via filter_markdown_body() removes boilerplate content while preserving code blocks, achieving 30%+ token reduction.
• Compact list formatters limit output to 20 items and support --ultra-compact mode with single-character status indicators.
• All token savings are tracked in SQLite via src/core/tracking.rs, measurable through the rtk gain command.

Frequently Asked Questions

Does RTK replace the GitHub CLI completely?

No, RTK wraps the existing gh installation and delegates actual GitHub API calls to it. When RTK detects flags like --json or --web, it passes commands through unchanged via run_passthrough() in src/cmds/git/gh_cmd.rs. This ensures you never lose access to native GitHub CLI functionality.

How much token savings can I expect when using RTK with GitHub CLI?

The repository's internal tests demonstrate 30% or greater token savings when processing pull requests and issues. The filter_markdown_body() function strips HTML comments, badges, and image links from Markdown bodies, while compact list formatters truncate titles to 60 characters and limit output to 20 items.

What happens if RTK encounters an unknown GitHub CLI subcommand?

RTK falls back to run_passthrough() for any unrecognized subcommands or arguments, executing the raw gh command without modification. This zero-risk compatibility approach ensures that edge cases and new GitHub CLI features remain accessible even if RTK lacks specific filtering logic for them.

Where does RTK store token savings metrics?

Metrics are persisted to a local SQLite database through the tracking module at src/core/tracking.rs. The rtk gain command queries this database to display cumulative token savings across all operations, including filtered GitHub CLI outputs.

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