If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/The-PR-Agent/pr-agent shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4d ago
• 29+ active contributors
• Distributed ownership (top contributor 29% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live The-PR-Agent/pr-agent repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/The-PR-Agent/pr-agent.

What it runs against: a local clone of The-PR-Agent/pr-agent — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in The-PR-Agent/pr-agent | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of The-PR-Agent/pr-agent. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/The-PR-Agent/pr-agent.git
#   cd pr-agent
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of The-PR-Agent/pr-agent and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "The-PR-Agent/pr-agent(\\.git)?\\b" \\
  && ok "origin remote is The-PR-Agent/pr-agent" \\
  || miss "origin remote is not The-PR-Agent/pr-agent (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "pr_agent/agent/pr_agent.py" \\
  && ok "pr_agent/agent/pr_agent.py" \\
  || miss "missing critical file: pr_agent/agent/pr_agent.py"
test -f "pr_agent/algo/ai_handlers/base_ai_handler.py" \\
  && ok "pr_agent/algo/ai_handlers/base_ai_handler.py" \\
  || miss "missing critical file: pr_agent/algo/ai_handlers/base_ai_handler.py"
test -f ".pr_agent.toml" \\
  && ok ".pr_agent.toml" \\
  || miss "missing critical file: .pr_agent.toml"
test -f "pr_agent/__init__.py" \\
  && ok "pr_agent/__init__.py" \\
  || miss "missing critical file: pr_agent/__init__.py"
test -f "pr_agent/algo/git_patch_processing.py" \\
  && ok "pr_agent/algo/git_patch_processing.py" \\
  || miss "missing critical file: pr_agent/algo/git_patch_processing.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/The-PR-Agent/pr-agent"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PR-Agent is an open-source AI-powered code review agent that automatically analyzes pull requests using LLMs (OpenAI, Claude, Gemini, etc.) to provide detailed reviews, suggestions, and metadata. It integrates directly with GitHub, GitLab, Bitbucket, and Azure DevOps as a GitHub Action, webhook, or CLI tool, replacing manual code review bottlenecks with intelligent, contextual feedback on changes. Monolithic Python package structure: core logic likely in pr_agent/ (inferred from entrypoints), providers/ for LLM adapters (OpenAI, Claude, Gemini, Anthropic), integrations/ for GitHub/GitLab/Bitbucket/Azure webhooks, and CLI/GitHub Action wrappers in action.yaml and docker/. Configuration via dynaconf (.pr_agent.toml), deployment via Dockerfile.github_action, Dockerfile (standard), and Dockerfile.lambda for AWS.

DevOps engineers, tech leads, and development teams who want to automate code quality checks and speed up PR reviews without expensive external services. Specifically, maintainers of open-source and private repositories who need scalable, self-hosted code review automation with support for multiple LLM providers.

Production-ready and actively maintained. The project has significant commit history (1.1M+ lines of Python code), comprehensive CI/CD pipelines (.github/workflows with build-and-test, e2e_tests, codeql, code_coverage), recent Docker Hub migration (v0.34.2+), and is now community-owned under the PR-Agent GitHub org after being donated by Qodo. Last commits and workflows indicate active development.

Moderate risk: 30+ external dependencies (openai, anthropic, litellm, boto3, google-cloud-*, azure-devops, FastAPI) create a large attack surface and maintenance burden. LLM API keys (OPENAI_KEY, etc.) must be carefully managed as secrets. The project recently migrated Docker Hub namespaces (codiumai → pragent), which could cause deployment confusion. Single release team or limited maintainer visibility could slow security patches.

Active development with recent Docker Hub namespace consolidation (0.34.2+), GitHub Action refinement (action.yaml present), e2e test expansion (.github/workflows/e2e_tests.yaml), and code coverage tracking (code_coverage.yaml). Release drafter is configured (release-drafter.yml), suggesting regular version bumps. Security scans (codeql.yml) are enabled, indicating security-first maintenance.

git clone https://github.com/the-pr-agent/pr-agent.git && cd pr-agent && pip install -r requirements.txt && export OPENAI_KEY='your-key' && python -m pr_agent.main (or docker run pragent/pr-agent:latest for containerized deployment).

Daily commands: For CLI: export OPENAI_KEY=sk-... && python -m pr_agent.main. For webhook server: uvicorn pr_agent.main:app --host 0.0.0.0 --port 8000 (inferred from FastAPI presence). For GitHub Action: add .github/workflows/pr-agent.yml with action.yaml template. For Docker: docker run -e OPENAI_KEY=$OPENAI_KEY pragent/pr-agent:latest.

• pr_agent/agent/pr_agent.py — Main entry point orchestrating the PR review workflow; all custom logic flows through this agent coordinator.
• pr_agent/algo/ai_handlers/base_ai_handler.py — Abstract base for all LLM integrations (OpenAI, Anthropic, LiteLLM); extending this is required for new model support.
• .pr_agent.toml — Configuration schema defining all runtime settings for providers, models, and tool behavior; every deployment relies on this.
• pr_agent/__init__.py — Package initialization and version exports; critical for dependency resolution and module discovery.
• pr_agent/algo/git_patch_processing.py — Parses git diffs into structured format for LLM analysis; core to the diff-to-review pipeline.
• pr_agent/algo/file_filter.py — Filters and prioritizes files for analysis based on patterns and rules; directly affects review scope and performance.
• github_action/entrypoint.sh — GitHub Actions bootstrap script; defines how the agent runs in CI/CD environments.

Add Support for a New LLM Provider

1. Create a new handler class inheriting from base_ai_handler.py (pr_agent/algo/ai_handlers/new_provider_handler.py)
2. Implement required methods: call_model(), call_model_async(), and relevant retry/token logic (pr_agent/algo/ai_handlers/new_provider_handler.py)
3. Register the handler in the AI handler factory/router (typically in base_ai_handler.py or a dispatch module) (pr_agent/algo/ai_handlers/base_ai_handler.py)
4. Add configuration schema for the new provider in .pr_agent.toml (.pr_agent.toml)
5. Document the new provider in the configuration guide (docs/docs/usage-guide/changing_a_model.md)

Add a New PR Review Tool or Capability

1. Create a new tool module in pr_agent/tools/ (or extend existing tool file) (pr_agent/tools/new_tool.py)
2. Implement the tool with an async run() method that takes git_patch and relevant context (pr_agent/tools/new_tool.py)
3. Register the tool in pr_agent/agent/pr_agent.py and map it to a CLI/webhook command (pr_agent/agent/pr_agent.py)
4. Add configuration keys for the tool in .pr_agent.toml (.pr_agent.toml)
5. Add documentation for the new tool (docs/docs/tools/new_tool.md)

Add Support for a New Git Hosting Platform

1. Create a new provider handler in pr_agent/vcs_providers/ (typically inheriting from base provider) (pr_agent/vcs_providers/new_platform_provider.py)
2. Implement required methods: get_pr_diff(), post_comment(), get_pr_info(), etc. (pr_agent/vcs_providers/new_platform_provider.py)
3. Update the provider router/factory to instantiate the new provider based on environment or config (pr_agent/vcs_providers/__init__.py)
4. Add credentials and endpoint configuration in .pr_agent.toml (.pr_agent.toml)
5. Create installation and setup documentation (docs/docs/installation/new_platform.md)

Customize File Filtering and Priority Logic

1. Review current filter patterns and logic (pr_agent/algo/file_filter.py)
2. Modify extension exclusions, directory patterns, or size thresholds in file_filter.py (pr_agent/algo/file_filter.py)
3. Add corresponding configuration keys for the new filter rules (.pr_agent.toml)
4. Test with pr_agent/algo/tests/test_file_filter.py (if present) or create integration test (pr_agent/algo/file_filter.py)

• Python async/await + FastAPI — Handles concurrent webhook events and LLM API calls without thread overhead; FastAPI provides automatic OpenAPI schema and built-in async support.
• LiteLLM + Anthropic + OpenAI SDKs — Abstracts multiple LLM providers (OpenAI, Claude, Cohere, local) behind a unified interface; supports fallback chains and retry logic without vendor lock-in.
• Dynaconf for configuration — Merges TOML, environment variables, and CLI args seamlessly; enables zero-code provider/model switching across dev/prod without code changes.
• PyGithub, python-gitlab, azure-devops SDKs — Native client libraries for GitHub, GitLab, Azure DevOps; avoids re-implementing auth, pagination, and API quirks.
• Jinja2 templating — Generates structured LLM prompts with dynamic context injection; separates prompt engineering from code logic.

• Single-process async agent vs. distributed queue workers

  • Why: Simpler deployment model; GitHub Actions and self-hosted runners don't require Celery/RabbitMQ infrastructure.
  • Consequence: Limited horizontal scaling; high LLM latency (8–15s per PR) blocks webhook thread. Suitable for small–medium teams; enterprise deployments may need worker pools.

• Unified AI handler abstraction vs. provider-specific code

  • Why: Allows rapid provider switching and A/B testing without code duplication.
  • Consequence: Common denominator API (call_model, token counting) may not expose all provider features (e.g., vision, function calling); custom features require handler subclasses.

• File-level diff filtering vs. semantic code analysis

  • Why: Fast, deterministic filtering on file patterns and size; avoids expensive AST parsing.
  • Consequence: May exclude important small files or include voluminous generated code; requires manual configuration tuning per project.

• Synchronous git patch processing vs. streaming

  • Why: undefined
  • Consequence: undefined

1. LLM API keys (OPENAI_KEY, ANTHROPIC_API_KEY) must be set as GitHub Secrets for Action; they will not be exposed in logs but missing keys silently fail. 2) Docker Hub migration: old codiumai/pr-agent images (v0.31 and earlier) are frozen; v0.34.2+ use pragent/pr-agent. Pinned image references in existing deployments will break. 3) dynaconf config merges .pr_agent.toml + environment variables + defaults; precedence is non-obvious (env vars override TOML). 4) token limits: tiktoken-based counting may differ per LLM (OpenAI vs Claude vs Gemini); model context windows require tuning for large diffs. 5) Rate limiting on LLM providers is not explicitly handled — high-volume PR reviews can hit API quotas.

• Retrieval-Augmented Generation (RAG) via similar-issues lookup — PR-Agent optionally uses Pinecone/Qdrant vector databases (commented-out in requirements.txt) to retrieve similar historical issues as context for smarter reviews; understanding embedding-based retrieval is key to enabling this feature.
• Token budget and context window management — PR-Agent uses tiktoken to count tokens and fit diffs into LLM context windows (e.g., OpenAI's 8k/16k/128k limits); incorrect token accounting breaks large PRs or causes API errors.
• Webhook-driven GitHub App integration pattern — PR-Agent receives GitHub webhook events (pull_request.opened, pull_request.synchronize) and authenticates via GitHub App or Personal Access Token; understanding webhook security and async event handling is essential for GitHub/GitLab/Bitbucket adapters.
• Multi-LLM provider abstraction via LiteLLM — PR-Agent supports OpenAI, Claude, Gemini, Vertex AI, and local models through a single litellm interface; learning this abstraction pattern helps add new LLM providers without refactoring core review logic.
• Dynaconf-based hierarchical configuration — PR-Agent uses dynaconf to merge TOML, environment variables, and defaults with clear precedence; misunderstanding config merge order leads to production bugs where settings are silently ignored.
• Async FastAPI webhook server with background job patterns — PR-Agent runs an async FastAPI endpoint to receive webhooks and queue LLM reviews as background tasks (using e.g., Celery or in-process workers); understanding async/await and task queuing prevents blocking webhook handlers.
• Compression strategies for large diffs (semantic vs. summarization) — PR-Agent compresses large PRs to fit token budgets via semantic diff folding or extractive summarization; this is documented in docs/docs/core-abilities/compression_strategy.md and is critical for handling enterprise-scale repos.

• github/codeql-action — Complementary security scanning; often runs alongside PR-Agent in CI/CD for multi-layer code quality
• openai/openai-python — Direct dependency; understanding OpenAI SDK internals helps debug LLM integration and token counting
• liteagi/litellm — Core abstraction layer in PR-Agent; LiteLLM handles multi-LLM routing, fallbacks, and cost tracking
• zapier/zapier-platform — Ecosystem companion for enterprise automation; PR-Agent reviews can trigger Zapier workflows for downstream tooling
• the-pr-agent/pr-agent-docs — Official documentation repository (moved to www.pr-agent.ai); reference for deployment, configuration, and troubleshooting

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for pr_agent/algo module with pytest coverage reporting

The repo has pytest and pytest-cov configured but the file structure doesn't show dedicated test files for core algorithm modules. Given the complexity of PR analysis (compression_strategy, dynamic_context, fetching_ticket_context), adding unit tests for these modules would improve reliability and help catch regressions. This aligns with the existing code_coverage.yaml workflow that tracks coverage metrics.

• [ ] Create tests/algo/ directory structure mirroring pr_agent/algo/
• [ ] Write unit tests for compression_strategy.py covering token limits and content prioritization
• [ ] Write unit tests for dynamic_context.py covering context window management
• [ ] Write unit tests for fetching_ticket_context.py with mocked ticket API responses
• [ ] Update codecov.yml to enforce minimum coverage thresholds for new code
• [ ] Verify pytest-cov integration captures all new test coverage in code_coverage.yaml workflow

Add integration tests for multi-platform provider adapters (GitHub, GitLab, Azure, Bitbucket)

The repo supports 5+ Git platforms (GitHub, GitLab, Azure, Bitbucket, Gitea) with provider adapters, but the workflows show no dedicated integration test job. The e2e_tests.yaml exists but likely focuses on end-to-end flows. Adding platform-specific integration tests (with mocked API responses) would ensure consistency across providers and catch breaking changes early.

• [ ] Create tests/integration/ directory with subdirectories for each provider (github, gitlab, azure, bitbucket, gitea)
• [ ] Write integration tests for GitHub provider using PyGithub mocking github API responses
• [ ] Write integration tests for GitLab provider using python-gitlab mocking
• [ ] Write integration tests for Azure DevOps provider using azure-devops client
• [ ] Create conftest.py with pytest fixtures for shared mock data and provider setup
• [ ] Add new 'integration-tests' job to build-and-test.yaml workflow that runs separately from unit tests

Create provider-specific installation and configuration guides in docs/docs/installation/

While installation docs exist for each platform, the docs/docs structure shows minimal content. The repo has complex provider-specific config requirements (API tokens, permissions, webhooks). Adding detailed setup guides for each provider with troubleshooting sections would reduce onboarding friction. Compare docs/docs/installation/*.md - they likely lack depth.

• [ ] Expand docs/docs/installation/github.md with webhook setup, required permissions, and token scoping
• [ ] Expand docs/docs/installation/gitlab.md with runner setup, webhook configuration, and CI/CD integration examples
• [ ] Expand docs/docs/installation/azure.md with service principal setup and Azure DevOps project-level permissions
• [ ] Expand docs/docs/installation/bitbucket.md with repository permissions and webhook registration
• [ ] Expand docs/docs/installation/gitea.md with self-hosted considerations and webhook setup
• [ ] Add docs/docs/installation/troubleshooting.md with common provider-specific errors and solutions
• [ ] Add provider comparison table to docs/docs/installation/index.md showing feature parity across platforms

• Add missing unit test coverage for pr_agent/integrations/bitbucket.py (referenced in file list but no test file visible) — start with clone and mock tests for webhook payload parsing.
• Document the 'similar issue' tool setup (see requirements.txt comments for pinecone, qdrant, lancedb) — create docs/docs/optional-features/similar-issues-setup.md with step-by-step Pinecone / Qdrant initialization and example queries.
• Add support for custom LLM endpoint via litellm (e.g., local Ollama, vLLM) — extend .pr_agent.toml schema to accept custom_llm_endpoint and base_url, then update litellm adapter in providers/ to pass through.

• High · Outdated and Vulnerable Dependencies — requirements.txt / dependencies. Multiple dependencies have known vulnerabilities or are significantly outdated. Notable issues include: aiohttp 3.12.15 (potential security issues), PyJWT 2.10.1 (older version with known JWT vulnerabilities), certifi 2024.8.30 (older certificate bundle), and msrest 0.7.1 (deprecated library). These should be audited and updated to latest patched versions. Fix: Run 'pip audit' to identify specific CVEs. Update all dependencies to latest versions, particularly aiohttp, PyJWT, boto3, and other cloud SDKs. Consider using 'pip-audit' in CI/CD pipeline to detect new vulnerabilities automatically.
• High · Unencrypted Secrets in Configuration — .pr_agent.toml. The file '.pr_agent.toml' is present in the repository root and may contain sensitive configuration including API keys, tokens, or credentials. Configuration files are commonly committed to version control, exposing secrets. Fix: Move all sensitive configuration to environment variables or a secrets management system. Add .pr_agent.toml to .gitignore. Use a tool like 'git-secrets' or 'detect-secrets' to prevent future secret commits. Rotate any exposed credentials immediately.
• High · Hardcoded API Keys Risk in LLM Integration — Various components handling: openai, anthropic, google-generativeai, azure-identity. The codebase integrates with multiple LLM providers (OpenAI, Anthropic, Google, Azure) via API keys. The dependency structure and documentation suggest API keys may be passed through configuration. Risk of accidental exposure in logs, error messages, or debugging output. Fix: Implement secure API key management: use environment variables exclusively, never log API keys, implement key rotation mechanisms, use restricted API keys with minimal required permissions, consider using OAuth where available. Scan logs and error outputs for potential key exposure.
• Medium · FastAPI Application Without Security Headers — FastAPI configuration / middleware setup. FastAPI application (version 0.118.0) is configured but typical security headers (HSTS, CSP, X-Frame-Options, etc.) are not visible in the file structure. This could lead to common web vulnerabilities. Fix: Add CORS middleware with restrictive settings, implement security headers middleware, use FastAPI's built-in security features, enable HTTPS only, implement rate limiting. Review Starlette-context usage (0.3.6) for proper context isolation.
• Medium · Insufficient Input Validation in PR Processing — Core PR processing modules (not directly visible but inferred from dependencies: PyGithub, python-gitlab, giteapy, azure-devops). PR Agent processes external input (pull request content, code diffs) from multiple Git platforms. Without proper input sanitization, this could lead to prompt injection attacks, XXE, or other code injection vulnerabilities when interfacing with LLM providers. Fix: Implement strict input validation and sanitization for all PR content before sending to LLM APIs. Use parameterized/templated prompts. Validate and escape special characters in diffs and code content. Implement rate limiting to prevent abuse.
• Medium · Overly Permissive Docker Configuration — Dockerfile.github_action, Dockerfile.github_action_dockerhub, docker/Dockerfile, docker/Dockerfile.lambda. Multiple Dockerfile variants present (Dockerfile.github_action, Dockerfile.lambda, etc.) without visible security scanning or minimal base image usage. Potential for supply chain attacks if base images are not regularly patched. Fix: Use minimal base images (python:3.x-slim or alpine), implement multi-stage builds, scan Docker images with Trivy or similar tools in CI/CD, use specific version tags (not 'latest'), implement container security scanning in GitHub Actions workflow, consider using distroless images.
• Medium · Insecure Deserialization with YAML — PyYAML dependency and configuration parsing. PyYAML 6.0.1 is used. While 6.0.1 includes safety improvements, YAML.load() without Loader parameter can execute arbitrary Python code. Configuration files are parsed from user inputs and external sources. Fix: Use yaml.safe_load() exclusively instead of yaml.load(). Never use Loader=yaml.Loader

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.