PR-Agent

PR-Agent provides a comprehensive code review experience through several specialized core abilities. These mechanisms allow the agent to handle context, reasoning, and data retrieval efficiently:

• Agent skills: The specific tasks and capabilities the agent can perform.
• Compression strategy: Methods used to manage and condense information for LLM processing.
• Dynamic context: How the agent gathers and adapts context during a session.
• Fetching ticket context: Integration with issue tracking systems to bring relevant ticket data into the PR review.
• Local and global metadata: Use of repository-level and file-level metadata to inform the agent.
• Self-reflection: The agent's ability to review its own reasoning and outputs to improve accuracy.

PR-Agent is an AI-powered code review agent that supports multiple git providers and AI models.

Supported Git Providers:

• GitHub
• GitLab
• Bitbucket
• Azure DevOps
• Gitea

Supported AI Models: Supports OpenAI GPT, Anthropic Claude, Google Gemini, DeepSeek, Mistral, and any model reachable through LiteLLM (including Azure OpenAI, AWS Bedrock, Vertex AI, Databricks, OpenRouter, and Ollama).

Core Tools:

• /describe: Generates PR descriptions.
• /review: Performs code reviews.
• /improve: Suggests improvements.
• /ask: Allows asking questions about the code (including specific lines).
• /update_changelog: Updates the project changelog.

After installation, PR-Agent can be used in three primary modes:

1. Locally via CLI: Run commands directly from your terminal using a pre-built Docker image or by running from a locally cloned repository.
2. Online via PR Comments: Interact with PR-Agent by posting specific comments on a Pull Request (GitHub, GitLab, or BitBucket).
3. Automated Workflows: Configure PR-Agent to run automatically when a new PR is opened or when new code is pushed to a branch.

To use the online or automated modes, you must set up an integration specific to your platform (e.g., a GitHub App, GitLab webhook, or BitBucket App).

The PR-Agent usage guide provides comprehensive instructions for setting up and customizing the agent. Key topics include:

• Configuration: How to adjust settings and define which tools run automatically via the Configuration File.
• Deployment & Automation: Instructions for different environments including:
  • Local Repo (CLI): Running the agent locally via command line.
  • Online Usage: Integrating with hosted platforms.
  • Platform-Specific Integrations: Setting up GitHub Apps, GitHub Actions, GitLab Webhooks, Gitea Webhooks, BitBucket Apps, and Azure DevOps Providers.
• Advanced Customization:
  • Changing the LLM model used for analysis.
  • Managing mail notifications.
  • Ignoring specific files from analysis.
  • Providing extra instructions to the agent.
  • Strategies for working with large Pull Requests.

When configuring CI, production webhooks, or pinned Action steps, understand the difference between versioned and rolling tags:

Immutable Version Tags

Version-numbered tags (e.g., 0.40.0, 0.40.0-github_app) are immutable. Once pushed, they cannot be overwritten. Use these for production environments to ensure stability.

Mutable Rolling Tags

The following tags are designed to move to the newest build on every release. They are useful for testing but are not recommended for production because they can change unexpectedly:

• latest
• github_action
• github_lambda
• gitlab_lambda
• gitlab_webhook
• gitea_app
• mosaico_agent
• bitbucket_server_webhook

By setting pr_description.use_description_markers=true, you can use a template-like mechanism to integrate user content and auto-generated content using specific markers. The tool will replace these markers with the actual generated content.

Available Markers:

• pr_agent:type: Replaced by the PR type.
• pr_agent:summary: Replaced by the PR summary.
• pr_agent:walkthrough: Replaced by the PR walkthrough.
• pr_agent:diagram: Replaced by the sequence diagram (if enabled).

Additional Marker Configs:

• include_generated_by_header: If true, adds 'Generated by PR Agent at ...' to auto-content. Default: true.

## PR Type:
pr_agent:type

## PR Description:
pr_agent:summary

## PR Walkthrough:
pr_agent:walkthrough

## PR Diagram:
pr_agent:diagram

PR-Agent supports text-only bundled resources within a skill directory. When a skill is loaded, the following rules apply:

• Markdown Files: All *.md files in the skill directory tree (including references/ subdirectories) are appended after the SKILL.md body. Files larger than 256 KB are skipped.
• Skipped Directories: scripts/ and assets/ subdirectories are ignored. PR-Agent cannot execute scripts or load binary assets.
• Nested Skills: A directory containing its own SKILL.md is treated as a separate, independent skill and is not inlined into the parent skill.

Limitation: Because PR-Agent uses single-shot model calls, all enabled skill text is loaded into every PR's prompt (up to the max_skills_tokens limit), rather than being loaded on-demand.

To gain maximal control over where specific parts of the generated description appear, you can use Markers. When markers are enabled, PR-Agent will search the existing PR description for specific tokens and replace them with generated content.

Important: If markers are enabled but the original PR description does not contain any marker tokens, the tool will not modify the description at all.

To enable this mode, add the --pr_description.use_description_markers=true flag to your /describe command.

pr_commands = ["/describe --pr_description.use_description_markers=true", ...]

PR-Agent uses an asymmetric and dynamic context strategy to improve AI analysis of pull request changes. Instead of providing a fixed number of lines around a code change, it optimizes the context window to prevent 'needle-in-the-haystack' information overload and token limit issues.

Asymmetric Context

PR-Agent recognizes that the code preceding a change is usually more important for understanding the modification than the code following it. It decouples the context window into two segments, allowing for different amounts of context before and after a change.

Dynamic Context

Rather than using a fixed line count, PR-Agent attempts to include the entire enclosing code component (such as a function or a class) to provide structural relevance. To maintain efficiency, it imposes a limit on how many lines it will search to find these enclosing components.

When a PR is too large for a single prompt, PR-Agent applies a compression strategy to maximize relevant information density using tiktoken for token-aware fitting.

Compression Steps

1. Prioritize Additions over Deletions:
   • All deleted files are collapsed into a single list called deleted files.
   • In file patches, all 'deletion-only' hunks are removed to save space.
2. Adaptive Patch Fitting:
   • Files are grouped by language and sorted by token count (descending).
   • Patches are added to the prompt sequentially until a token buffer limit is reached.
   • Overflow Handling:
     • Remaining patches are added as a list called other modified files until the hard token limit is reached.
     • If space remains, deleted files are added last until the hard limit is reached.

PR-Agent uses a layered configuration system where more specific settings override more general ones. If multiple configuration sources are defined, they are applied in the following order of precedence (from lowest to highest priority):

1. Built-in defaults
2. External configuration URL (via --extra_config_url)
3. Global configuration (from pr-agent-settings repo)
4. Local configuration file (.pr_agent.toml in the repo's default branch)
5. Wiki configuration file (.pr_agent.toml in the repo's wiki)
6. Environment variables (formatted as PR_AGENT__SECTION__KEY)

To help with debugging, you can set config.output_relevant_configurations = true in your configuration to see which settings are being applied to each tool in a collapsible section in the PR output.