Cross-repo agent sessions

Polygraph sessions can span repos connected to your account and public open source repos on GitHub. A repo can be part of the session because the agent needs to read it for context, because the agent needs to change it, or both.

You can start narrow when you know the work area. Let the agent add repos later when the task crosses a boundary you did not select upfront.

How Polygraph connects all repos

Polygraph indexes every repository it can access. It extracts metadata from those repositories to understand your organizational codebase and how it relates to public open source repos.

That metadata includes:

Dependencies between projects
External package dependencies
APIs that projects define
APIs that projects consume
Runtime dependencies
Manual dependencies added by your team

You can manage manual dependencies in the Polygraph web app when a relationship is important but Polygraph can't extract it automatically.

What is a Polygraph session

Every Polygraph session has a parent agent. The parent agent keeps the overall task context, plans across the selected repos, and can delegate repo-specific work to child agents.

Child agents run in the repos where work needs to happen. A repo does not need to be changed to belong in the session; it can be there so the agent can read an API, inspect a package, understand a bug report, or compare a downstream consumer.

That makes the session useful for both kinds of cross-repo work: reading across repos to get the right context, and making coordinated changes across several repos.

Repo selection does not need to be perfect at the start. Pick the repos you know are relevant, then expand the session when the work reveals another dependency, consumer, package, or API.

Select repos when you start a session

When you run polygraph session start, Polygraph asks how you want to choose repos:

Which repo(s) do you want to work on?
You can always add more repos during the session.

❋ Chat about it after starting session
  Select from list

Choose Select from list when you already know the repos involved.

Choose Chat about it after starting session when you do not know what repos are relevant. Describe the work in plain language, and the agent can add repos as it narrows the scope.

For non-interactive workflows, pass repo names or IDs to the --repo option on polygraph session start.

Choose where the parent agent runs

After you select repos, Polygraph asks which repo should host the parent agent:

Which repo should host the parent agent?

❋ Polygraph-Demo-Snapshot/poly-design-17deabd1
  Polygraph-Demo-Snapshot/poly-frontend-17deabd1
  Polygraph-Demo-Snapshot/poly-backend-17deabd1
  None (host in session folder)

For feature work, pick the repo where most of the parent-agent work will happen. The parent agent starts in that repo, so file selection, local commands, and editor context line up with the main workspace.

Choose None (host in session folder) when no repo should be treated as the primary workspace. This is useful for coordination-heavy work, such as updating every repo that uses a package version.

Add repos during a session

You can add more repos after the session starts. Mention a repo by name:

Please add vitejs/vite repo to this session.

Or describe the relationship you want Polygraph to find:

Please add all repos that depend on `@opentui/core`.

The agent can use Polygraph repo metadata to resolve those requests and attach the relevant repos to the active session.

You can also use the CLI directly: polygraph session add-repo.

Inspect available repos

Use polygraph graph to explore the repository dependency graph before you start a session. Use polygraph repo list when you need a terminal-friendly list of candidate repos and filters.