Whatever you can read, your agent can read: any repo you have access to (organization or open source). A repo belongs in a session because the agent needs to read it for context, because the agent needs to change it, or both.
Start narrow when you know the work area. You or your agent can expand it as the work crosses repo boundaries.
The repos in a session behave like one. Your agent reads and changes across all of them in a single session, so 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
Section titled “How Polygraph connects all repos”Polygraph indexes every repo you have access to and stitches them into one graph. Hence the name. For each repo it extracts what projects exist, what they depend on, what they publish, and what APIs they define and consume.
When a relationship matters but Polygraph can't extract it automatically, add it as a manual dependency in the Polygraph web app.
What is a Polygraph session
Section titled “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
Section titled “Select repos when you start a session”When you run polygraph session start, Polygraph asks how you want to choose repos:
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 the main repo
Section titled “Choose the main repo”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)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.
Add repos during a session
Section titled “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
Section titled “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.