# Cross-repo runs

> Let one run read, and open pull requests in, other repositories in the same organization.

By default a run works only in the repository that triggered it. The `--xrepo` flag lets one run read, and open PRs in, a bounded set of other repositories in the same organization.

```text
@pullfrog rename the `plan` field to `tier` here and in its consumers --xrepo=api,web
```

The flag takes three forms:

| Form | Meaning |
| --- | --- |
| `--xrepo` | The 10 most recently active repositories the triggering user can access, always including the triggering repository |
| `--xrepo=api,shared` | The named repositories, with no count limit; the owner is implied |
| `--no-xrepo` | Cancel a cross-repo default set at a more general level |

Like every [flag](https://pullfrog.com/docs/flags), `--xrepo` can be a standing default in org or repo instructions. Prefer the value form there, which names exactly the repositories a run may reach.

## Access

The triggering user's own GitHub permissions bound every cross-repo run, so a run never touches a repository that person could not already touch.

- A repository the user can only read is reference-only: the run can clone and inspect it but not open PRs.
- A repository the user can write to accepts branches and pull requests.
- A run started by a bot gets no cross-repo access.
- The run cannot push to the default branch of any repository other than the one that triggered it.

## Tools

During a cross-repo run, the agent has three ways to reach another repository:

| Tool | Use |
| --- | --- |
| `list_repos` | Lists the repositories in scope |
| `checkout_repo` | Clones another repository |
| `repo: "<name>"` on the git and pull-request tools | Works in that repository |

## Brief and learnings

Two settings in the organization console, under **Advanced**, describe how your repositories relate, so a cross-repo run does not rediscover the structure each time.

- **Cross-repo brief** is text you write, and the agent never edits it.
- **Cross-repo learnings** are maintained by the agent, like [repo-level learnings](https://pullfrog.com/docs/learnings) but for the organization. When the brief leaves the structure unstated, the agent works it out once and records it.

State relationships in the brief directly:

```text
`api` consumes types from `shared`.
`web` and `mobile` both depend on `design-system`.
Run `pnpm -r build` in `platform` before changing downstream repos.
```

Keep both structural: dependency direction, where shared code and types live, and each repository's build and test entry points. Facts about a single repository belong in that repository's own learnings.
