rctx - Review Context Tool for AI Agents

A command-line tool that extracts and structures GitHub Pull Request review data for AI agents, making it easy to understand review feedback and implement required changes.

Features

📋 Complete PR Overview - Metadata, status, and file changes
💬 Structured Review Comments - All comments with code context and line numbers
🤖 AI-Optimized Output - Formatted for easy consumption by AI agents
🔍 Code Context - Shows surrounding code for each review comment
💾 Persistent Storage - Save review context to files for later use
🔗 GitHub Integration - Works seamlessly with GitHub CLI

Prerequisites

GitHub CLI (gh) - Install from cli.github.com
Authentication - Run gh auth login to authenticate with GitHub

Installation

Download the tool and place it in your local bin directory:

# Make the directory if it doesn't exist
mkdir -p ~/.local/bin

# Copy rctx to your local bin (adjust path as needed)
cp rctx ~/.local/bin/
chmod +x ~/.local/bin/rctx

Add to PATH (if not already):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Quick Start

Set default repository (one-time setup):

cd /path/to/your/repo
gh repo set-default https://github.com/org/repo

Generate AI-optimized review context (replace 1883 with your PR number):
```
rctx -p org/repo/YOUR_PR_NUMBER -s -a
```

This creates a pr_YOUR_PR_NUMBER_review/ folder with structured files ready for AI consumption.

Usage

Basic Commands

# View PR overview and comments (replace 1883 with your PR number)
rctx -p org/repo/YOUR_PR_NUMBER

# Generate AI-optimized output
rctx -p org/repo/YOUR_PR_NUMBER -a

# Save output to files
rctx -p org/repo/YOUR_PR_NUMBER -s -a

# Show full diff with more context
rctx -p org/repo/YOUR_PR_NUMBER -d -x 20

# List only changed files
rctx -p org/repo/YOUR_PR_NUMBER -f

Command Options

Option	Description	Example
`-p, --process`	Process PR (format: org/repo/pr-number)	`-p llvm/clangir/YOUR_PR_NUMBER`
`-a, --agent`	Agent-optimized output (structured for AI)	`-a`
`-s, --save`	Save output to files	`-s`
`-d, --diff`	Show full diff	`-d`
`-f, --files`	List files only	`-f`
`-c, --checkout`	Also checkout the PR locally	`-c`
`-x, --context N`	Lines of context around changes (default: 10)	`-x 20`
`-h, --help`	Show help message	`-h`

Output Structure

When using -s -a (save + agent mode), rctx creates a folder with these files:

pr_YOUR_PR_NUMBER_review/
├── agent_context.md      # AI-friendly overview and instructions
├── agent_tasks.json      # Structured task list for required changes
├── pr_data.json         # Raw PR data (metadata, comments, reviews)
└── review_comments.json # Detailed review comments with context

File Descriptions

agent_context.md - Human-readable overview with color-coded sections, perfect for AI agents to understand the PR context and required changes
agent_tasks.json - Machine-readable task list with specific file locations and reviewer comments
pr_data.json - Complete PR metadata including commits, files changed, and review decisions
review_comments.json - Detailed review comments with code context and line numbers

Workflow Examples

For AI Code Review Assistant

# 1. Generate review context (replace with your PR number)
rctx -p org/clangir/YOUR_PR_NUMBER -s -a

# 2. AI agent reads the context files
# 3. AI implements required changes
# 4. AI can reference specific line numbers and comments from the structured data

For Manual Review

# Quick overview (replace with your PR number)
rctx -p org/clangir/YOUR_PR_NUMBER

# Detailed analysis with full diff
rctx -p org/clangir/YOUR_PR_NUMBER -d -x 15

# Save for later reference
rctx -p org/clangir/YOUR_PR_NUMBER -s

For Local Development

# Checkout PR and generate context (replace with your PR number)
rctx -p org/clangir/YOUR_PR_NUMBER -c -s -a

# Now you have:
# - Local branch checked out
# - Review context saved
# - Ready to implement changes

Integration with AI Agents

The tool is specifically designed for AI agents working on code reviews:

Structured Data - JSON files provide machine-readable task lists
Code Context - Each comment includes surrounding code for better understanding
Line Numbers - Precise locations for implementing changes
Color-Coded Output - Easy visual parsing of different sections
Complete History - Full conversation thread between reviewers

Understanding Unclear Comments

There will be cases where you don't understand a reviewer's comment or the context isn't immediately clear. Instead of waiting for clarification from the reviewer, you can use AI agents to help interpret the feedback:

Feed the structured context to an AI agent along with the unclear comment
Ask for interpretation based on the code context and review history
Get suggestions for what the reviewer likely means
Implement changes based on the AI's interpretation
Iterate if the interpretation seems incorrect

This approach helps maintain development velocity while ensuring reviewer feedback is properly addressed.

Example AI Agent Usage

import json

# Load structured tasks (replace with your PR number)
with open('pr_YOUR_PR_NUMBER_review/agent_tasks.json') as f:
    tasks = json.load(f)

# Process each required change
for comment in tasks['comments_to_address']:
    file_path = comment['file']
    line_number = comment['line']
    reviewer_comment = comment['comment']
    
    # AI implements the change...

Troubleshooting

Common Issues

"gh: command not found"
- Install GitHub CLI: brew install gh (macOS) or visit cli.github.com
Authentication errors
- Run: gh auth login
Repository not found
- Ensure you have access to the repository
- Check the org/repo/pr-number format
No default repository
- Run: gh repo set-default https://github.com/org/repo

Debug Mode

Add verbose output to see what's happening:

# Enable debug output (if supported) - replace with your PR number
rctx -p org/clangir/YOUR_PR_NUMBER -a --verbose

Advanced Usage

Working with Multiple PRs

# Process multiple PRs in sequence (replace with your PR numbers)
for pr in YOUR_PR_1 YOUR_PR_2 YOUR_PR_3; do
  rctx -p org/clangir/$pr -s -a
done

Custom Context Lines

# More context for complex changes (replace with your PR number)
rctx -p org/clangir/YOUR_PR_NUMBER -x 25 -s -a

# Minimal context for simple changes
rctx -p org/clangir/YOUR_PR_NUMBER -x 5 -s -a

Integration with Build Systems

#!/bin/bash
# Script to process PR and run tests

PR_NUM=$1
rctx -p org/clangir/$PR_NUM -c -s -a

# Now work with the checked out PR
cd pr_${PR_NUM}_review
# ... implement changes based on agent_context.md
# ... run tests

Best Practices

Always use -s -a for AI agent workflows
Set appropriate context lines (-x) based on change complexity
Use -c when you need to make local changes
Review agent_context.md first for human-readable overview
Parse agent_tasks.json for programmatic processing

Real-World Example

Here's how this tool was used to address PR #1883 in the ClangIR project:

# 1. Generate review context
rctx -p llvm/clangir/1883 -s -a

# 2. AI agent analyzed the structured output:
#    - 21 review comments to address
#    - Issues in CIRGenBuiltinX86.cpp and test files
#    - Need to "wire up input-output" for tests

# 3. AI agent implemented changes:
#    - Added comprehensive documentation
#    - Fixed implementation issues
#    - Created proper input-output verification tests
#    - Used real compilation results instead of assumptions

# 4. Result: All tests passing, all review comments addressed

Contributing

This tool is designed to work with any GitHub repository and PR. Feel free to:

Report issues with specific repositories or PR formats
Suggest additional output formats
Contribute improvements for better AI agent integration

wizardengineer / rctx