feat: Implement the documented "add_repo_metadata" functionality

pr_agent/git_providers/azuredevops_provider.py

@@ -174,6 +174,27 @@ def get_repo_settings(self):
                 get_logger().error(f"Failed to get repo settings, error: {e}")
             return ""
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            head_sha = self.pr.last_merge_commit
+            version = GitVersionDescriptor(
+                version=head_sha.commit_id, version_type="commit"
+            ) if head_sha else None
+            contents = self.azure_devops_client.get_item_content(
+                repository_id=self.repo_slug,
+                project=self.workspace_slug,
+                download=False,
+                include_content_metadata=False,
+                include_content=True,
+                path=file_path,
+                version_descriptor=version,
+            )
+            content = list(contents)[0]
+            return content.decode("utf-8") if isinstance(content, bytes) else content
+        except Exception as e:
+            get_logger().debug(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+
     def get_files(self):
         files = []
         for i in self.azure_devops_client.get_pull_request_commits(

pr_agent/git_providers/bitbucket_provider.py

@@ -89,6 +89,23 @@ def get_repo_settings(self):
         except Exception:
             return ""
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            # Read from the PR's source branch so metadata files reflect the branch under review
+            url = (f"https://api.bitbucket.org/2.0/repositories/{self.workspace_slug}/{self.repo_slug}/src/"
+                   f"{self.pr.source_branch}/{file_path}")
+            response = requests.request("GET", url, headers=self.headers)
+            if response.status_code == 404:
+                return ""
+            response.raise_for_status()
+            return response.text
+        except requests.exceptions.HTTPError as e:
+            get_logger().warning(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+        except requests.exceptions.ConnectionError as e:
+            get_logger().warning(f"Connection error getting repo file '{file_path}': {e}")
+            return ""
+
     def get_git_repo_url(self, pr_url: str=None) -> str: #bitbucket does not support issue url, so ignore param
         try:
             parsed_url = urlparse(self.pr_url)

pr_agent/git_providers/bitbucket_server_provider.py

@@ -116,6 +116,19 @@ def get_repo_settings(self):
             get_logger().error(f"Failed to load .pr_agent.toml file, error: {e}")
             return ""
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            head_sha = self.pr.fromRef['latestCommit']
+            content = self.get_file(file_path, head_sha)
+            return content.decode("utf-8") if isinstance(content, bytes) else (content or "")
+        except HTTPError as e:
+            if e.response.status_code != 404:
+                get_logger().error(f"Failed to load {file_path} file, error: {e}")
+            return ""
+        except Exception as e:
+            get_logger().error(f"Failed to load {file_path} file, error: {e}")
+            return ""
+
     def get_pr_id(self):
         return self.pr_num
 

pr_agent/git_providers/codecommit_provider.py

@@ -299,6 +299,14 @@ def get_repo_settings(self):
         settings_filename = ".pr_agent.toml"
         return self.codecommit_client.get_file(self.repo_name, settings_filename, self.pr.source_commit, optional=True)
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            content = self.codecommit_client.get_file(self.repo_name, file_path, self.pr.source_commit, optional=True)
+            return content.decode("utf-8") if isinstance(content, bytes) else (content or "")
+        except ValueError as e:
+            get_logger().debug(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+
     def add_eyes_reaction(self, issue_comment_id: int, disable_eyes: bool = False) -> Optional[int]:
         get_logger().info("CodeCommit provider does not support eyes reaction yet")
         return True

pr_agent/git_providers/gerrit_provider.py

@@ -231,6 +231,13 @@ def get_repo_settings(self):
         except OSError:
             return b""
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            with open(self.repo_path / file_path, 'r', encoding='utf-8') as f:
+                return f.read()
+        except OSError:
+            return ""
+
     def get_diff_files(self) -> list[FilePatchInfo]:
         diffs = self.repo.head.commit.diff(
             self.repo.head.commit.parents[0],  # previous commit

pr_agent/git_providers/git_provider.py

@@ -274,6 +274,19 @@ def _is_generated_by_pr_agent(self, description_lowercase: str) -> bool:
     def get_repo_settings(self):
         pass
 
+    def get_repo_file(self, file_path: str) -> str:
+        """
+        Read a text file from the PR's head branch root directory.
+
+        Args:
+            file_path: Relative path to the file from the repository root.
+
+        Returns:
+            The file content as a UTF-8 string, or "" if the file does not exist
+            or cannot be read.
+        """
+        return ""
+
     def get_workspace_name(self):
         return ""
 

pr_agent/git_providers/gitea_provider.py

@@ -623,6 +623,24 @@ def get_repo_settings(self) -> str:
 
         return response
 
+    def get_repo_file(self, file_path: str) -> str:
+        """Get a file from the repository root"""
+        try:
+            response = self.repo_api.get_file_content(
+                owner=self.owner,
+                repo=self.repo,
+                commit_sha=self.sha,
+                filepath=file_path
+            )
+            return response if response else ""
+        except ApiException as e:
+            if e.status != 404:
+                self.logger.warning(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+        except Exception as e:
+            self.logger.debug(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+
     def get_user_id(self) -> str:
         """Get the ID of the authenticated user"""
         return f"{self.pr.user.id}" if self.pr else ""

pr_agent/git_providers/github_provider.py

@@ -740,6 +740,19 @@ def get_repo_settings(self):
         except Exception:
             return ""
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            # Read from the PR's head branch so metadata files reflect the branch under review
+            contents = self.repo_obj.get_contents(file_path, ref=self.pr.head.sha).decoded_content
+            return contents.decode("utf-8") if isinstance(contents, bytes) else contents
+        except GithubException as e:
+            if e.status != 404:
+                get_logger().warning(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+        except Exception as e:
+            get_logger().debug(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+
     def get_workspace_name(self):
         return self.repo.split('/')[0]
 

pr_agent/git_providers/gitlab_provider.py

@@ -797,6 +797,19 @@ def get_repo_settings(self):
         except Exception:
             return ""
 
+    def get_repo_file(self, file_path: str) -> str:
+        try:
+            # Read from the MR's source branch so metadata files reflect the branch under review
+            contents = self.gl.projects.get(self.id_project).files.get(
+                file_path=file_path, ref=self.mr.source_branch).decode()
+            return contents.decode("utf-8") if isinstance(contents, bytes) else contents
+        except GitlabGetError:
+            # File not found or not accessible — expected when the metadata file doesn't exist
+            return ""
+        except Exception as e:
+            get_logger().debug(f"Failed to get repo file '{file_path}': {e}")
+            return ""
+
     def get_workspace_name(self):
         return self.id_project.split('/')[0]
 

pr_agent/git_providers/utils.py

@@ -1,5 +1,6 @@
 import copy
 import os
+import posixpath
 import tempfile
 import traceback
 
@@ -11,6 +12,28 @@
 from pr_agent.log import get_logger
 
 
+def _is_safe_repo_file_path(file_path: str) -> bool:
+    """
+    Validate that a file path is safe to read from a repository root.
+    Rejects absolute paths, paths with '..' traversal components, and backslashes.
+    """
+    if not file_path or not file_path.strip():
+        return False
+    # Reject absolute paths (Unix and Windows-style)
+    if os.path.isabs(file_path) or file_path.startswith("/") or file_path.startswith("\\"):
+        return False
+    if len(file_path) >= 2 and file_path[1] == ":":  # e.g. C:\...
+        return False
+    # Reject backslashes (non-standard on most git providers, potential traversal vector)
+    if "\\" in file_path:
+        return False
+    # Normalize and reject any ".." components
+    normalized = posixpath.normpath(file_path)
+    if normalized.startswith("..") or "/.." in normalized:
+        return False
+    return True
+
+
 def apply_repo_settings(pr_url):
     os.environ["AUTO_CAST_FOR_DYNACONF"] = "false"
     git_provider = get_git_provider_with_context(pr_url)
@@ -85,6 +108,66 @@ def apply_repo_settings(pr_url):
                 except Exception as e:
                     get_logger().error(f"Failed to remove temporary settings file {repo_settings_file}", e)
 
+    # Repository metadata: fetch well-known instruction files (AGENTS.md, QODO.md, CLAUDE.md, …)
+    # from the PR's head branch root and inject their contents into every tool's extra_instructions.
+    # See: https://qodo-merge-docs.qodo.ai/usage-guide/additional_configurations/#bringing-additional-repository-metadata-to-pr-agent
+    #
+    # Guard: apply_repo_settings() can be called multiple times per request (e.g. once in the
+    # server handler and again inside PRAgent.handle_request). The TOML settings are idempotent
+    # (set/overwrite), but metadata is *appended* to extra_instructions, so we must skip on
+    # repeated calls to avoid duplicating content in prompts.
+    repo_metadata_applied = False
+    try:
+        repo_metadata_applied = context.get("repo_metadata_applied", False)
+    except Exception:
+        # No request context (e.g. CLI mode) — fall back to a flag on the settings object
+        repo_metadata_applied = get_settings().get("config._repo_metadata_applied", False)
+    if not repo_metadata_applied and get_settings().config.get("add_repo_metadata", False):
+        try:
+            metadata_files = get_settings().config.get("add_repo_metadata_file_list",
+                                                        ["AGENTS.md", "QODO.md", "CLAUDE.md"])
+
+            # Collect contents of all metadata files that exist in the repo
+            metadata_content_parts = []
+            for file_name in metadata_files:
+                if not _is_safe_repo_file_path(file_name):
+                    get_logger().warning(f"Skipping unsafe metadata file path: '{file_name}'")
+                    continue
+                content = git_provider.get_repo_file(file_name)
+                if content and content.strip():
+                    metadata_content_parts.append(content.strip())
+                    get_logger().info(f"Loaded repository metadata file: {file_name}")
+
+            # Append combined metadata to extra_instructions for every tool that supports it.
+            if metadata_content_parts:
+                combined_metadata = "\n\n".join(metadata_content_parts)
+                tool_sections = [
+                    "pr_reviewer",
+                    "pr_description",
+                    "pr_code_suggestions",
+                    "pr_add_docs",
+                    "pr_update_changelog",
+                    "pr_test",
+                    "pr_improve_component",
+                ]
+                for section in tool_sections:
+                    section_obj = get_settings().get(section, None)
+                    if section_obj is not None and hasattr(section_obj, "extra_instructions"):
+                        existing = section_obj.extra_instructions or ""
+                        if existing:
+                            new_value = f"{existing}\n\n{combined_metadata}"
+                        else:
+                            new_value = combined_metadata
+                        get_settings().set(f"{section}.extra_instructions", new_value)
+            # Mark as applied so repeated calls within the same request don't re-append
+            try:
+                context["repo_metadata_applied"] = True
+            except Exception:
+                pass
+            get_settings().set("config._repo_metadata_applied", True)
+        except Exception as e:
+            get_logger().debug(f"Failed to load repository metadata files: {e}")
+
     # enable switching models with a short definition
     if get_settings().config.model.lower() == 'claude-3-5-sonnet':
         set_claude_model()

pr_agent/settings/configuration.toml

@@ -20,6 +20,8 @@ log_level="DEBUG"
 use_wiki_settings_file=true
 use_repo_settings_file=true
 use_global_settings_file=true
+add_repo_metadata=false # when true, searches the PR's head branch root for metadata files (by default: AGENTS.md, QODO.md, CLAUDE.md) and appends their content as extra instructions to all tools
+add_repo_metadata_file_list=["AGENTS.md", "QODO.md", "CLAUDE.md"] # override the default list of metadata filenames to search for when add_repo_metadata is true
 disable_auto_feedback = false
 ai_timeout=120 # 2 minutes
 skip_keys = []