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

> Integrate RTK with GitHub CLI to efficiently manage pull requests and issues. RTK optimizes GitHub CLI output, saving tokens and improving readability for developers.

- Repository: [rtk-ai/rtk](https://github.com/rtk-ai/rtk)
- Tags: how-to-guide
- Published: 2026-04-24

---

**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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/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:

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

```

View detailed PR information with cleaned Markdown bodies:

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

```

Generate ultra-compact output ideal for LLM prompts:

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

```

Access raw JSON when you need complete data:

```bash
rtk gh pr view 123 --json

```

Manage issues with filtered output:

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

```

Check workflow run status:

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

```

View repository summaries:

```bash
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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/src/core/tracking.rs)**: Persists token-saving statistics to SQLite, supporting the `rtk gain` reporting functionality.
- **[`src/core/utils.rs`](https://github.com/rtk-ai/rtk/blob/main/src/core/utils.rs)**: Provides helper utilities including `truncate()` for string shortening and `ok_confirmation()` for user prompts.
- **[`src/main.rs`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/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`](https://github.com/rtk-ai/rtk/blob/main/src/core/tracking.rs). The `rtk gain` command queries this database to display cumulative token savings across all operations, including filtered GitHub CLI outputs.