Cross-repo runs

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.

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

The flag takes three forms:

FormMeaning
--xrepoThe 10 most recently active repositories the triggering user can access, always including the triggering repository
--xrepo=api,sharedThe named repositories, with no count limit; the owner is implied
--no-xrepoCancel a cross-repo default set at a more general level

Like every flag, --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:

ToolUse
list_reposLists the repositories in scope
checkout_repoClones another repository
repo: "<name>" on the git and pull-request toolsWorks 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 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:

`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.

© 2026 Pullfrog, Inc.

On this page