Add guidance for cloning multiple repositories

docs.json

@@ -52,7 +52,8 @@
           {
             "group": "Tips and Tricks",
             "pages": [
-              "openhands/usage/tips/prompting-best-practices"
+              "openhands/usage/tips/prompting-best-practices",
+              "openhands/usage/tips/working-with-multiple-repos"
             ]
           },
           {

openhands/usage/tips/working-with-multiple-repos.mdx

@@ -0,0 +1,56 @@
+---
+title: Working with Multiple Repos
+description: Learn how to instruct OpenHands to clone and work with multiple repositories in your project ecosystem.
+---
+
+When working on projects that span multiple repositories, you can instruct OpenHands to clone additional repositories using your Git provider token. This is particularly useful when you need OpenHands to be aware of code in related repositories.
+
+## Common Scenarios
+
+- **Frontend/Backend Split**: Starting in a `backend` repo but needing access to UI code in a `frontend` repo
+- **Microservices**: Working across multiple service repositories
+- **Shared Libraries**: Accessing common utilities or components from separate repositories
+
+## Methods for Cloning Additional Repos
+
+### 1. Repository Configuration Files
+
+You can include cloning instructions in your repository's configuration files:
+
+- **`repo.md`**: Add instructions for OpenHands to clone related repositories
+- **`agents.md`**: Include repository setup as part of agent initialization
+
+Example in `repo.md`:
+```markdown
+## Related Repositories
+
+Please clone the following related repositories for full context:
+
+```bash
+git clone https://github.com/your-org/frontend-repo.git ../frontend
+git clone https://github.com/your-org/shared-utils.git ../shared-utils
+```
+
+### 2. Ad-hoc Prompting
+
+During a conversation, you can directly instruct OpenHands to clone additional repositories:
+
+**Example prompts:**
+- "Please clone our frontend repository from `https://github.com/our-org/frontend-repo.git` so you can see the UI components that interact with this API."
+- "Clone the shared utilities repo at `https://github.com/our-org/utils.git` into a `../utils` directory so you can reference the helper functions."
+- "I need you to access our documentation repo. Please clone `https://github.com/our-org/docs.git` to understand the API specifications."
+
+## Best Practices for Multi-Repo Workflows
+
+- **Specify clone location**: Use relative paths like `../repo-name` to keep repositories organized
+- **Provide context**: Explain why the additional repository is needed
+- **Use your Git token**: OpenHands will automatically use your configured Git provider token for authentication
+- **Be explicit about relationships**: Describe how the repositories relate to each other
+
+## Example Multi-Repo Prompt
+
+```
+I'm working on the user authentication API in this backend repo, but I need to understand how the frontend handles login flows. Please clone our frontend repository from https://github.com/our-company/frontend-app.git into ../frontend so you can see the login components and help me ensure the API responses match what the frontend expects.
+```
+
+This approach allows OpenHands to have full context across your entire project ecosystem, leading to better suggestions and more accurate implementations.