Cross-repo agent sessions

Although agents like Claude Code and Codex can operate on multiple repos in the same session, they are limited. Agents don't have the notion of a repository. They work on folders and files. Polygraph deeply understands how repositories are structured and how they relate. With Polygraph, you no longer think in terms of repositories. You simply describe the change in a logical way, and the relevant repositories are added to your session so your agent can gather context and make the necessary changes.

In other words, you get monorepo-like ergonomics without moving any code into a monorepo. Think of it as a synthetic monorepo, one working set spanning repos that stay where they are.

How Polygraph connects all repos

Polygraph indexes every repo you have access to and stitches them into one graph. For each repo it extracts what projects exist, what they depend on, what they publish, and what APIs they define and consume, and more.

When a relationship matters but Polygraph can't extract it automatically, add it as a manual dependency in the Polygraph web app.

Most importantly: by analyzing sessions, Polygraph learns which repos tend to go together, so over time new edges appear in the graph based on how your developers actually work. These are the most accurate edges: if two repos are always added to the same session, that's what really matters, not whether they share a package dependency.

What is a Polygraph session

Polygraph itself isn't an agent. It's a meta-harness: infrastructure and tooling around the agent you already use. It sets up a swarm of agents and uses the agent-to-agent protocol so they work as a team.

Every session has a parent agent. The parent agent keeps the overall task context, plans across the selected repos, and delegates repo-specific work to child agents. The parent agent can reside in one of the selected repos or exist outside of them. The other repos are auxiliary, worked on by child agents that message each other, ask for permissions, and coordinate.

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.

Select repos when you start a session

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

polygraph session start

❯

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.

Choose the main repo

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

polygraph session start

❯ polygraph session start

* * \ / * ────── * - * Polygraph / \ * *

Which repo should host the parent agent?

Polygraph-Demo-Snapshot/poly-frontend

❋ Polygraph-Demo-Snapshot/poly-backend

None (host in session folder)

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)

Pick the repo where most of the work will happen. The parent agent starts in that repo, so file selection, local commands, and editor context line up with the main workspace. The other repos become auxiliary.

Choose None (host in session folder) when the parent agent should not run in any of the selected repos. This is useful for coordination-heavy work, such as updating every repo that uses a package version.

Workspaces and worktrees

Polygraph creates a working copy for each repo in the session, using one of three strategies:

• clone clones the repo into the session folder. This is the default.
• worktree creates a git worktree from a local clone you already have.
• superset uses a single working copy shared across several repos.

Choose a strategy in ~/.polygraph/config.json:

{
  "repoStrategy": {
    "default": "worktree",
    "overrides": {
      "acme/api": "clone"
    }
  }
}

The repo you started the session from is always used in place and ignores these settings. See polygraph config for the rest of the options.

Apart from the repo you started in, these working copies are separate from your everyday checkouts, so a session leaves the branch you have open in your editor alone. Run polygraph session prune to clean up the working copies of old and archived sessions.

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 uses Polygraph repo metadata to resolve those requests and attach the relevant repos to the active session.

You can also use the CLI directly with 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.