Using multiple agents

Although a Polygraph session can be one agent in one repo, many sessions use multiple agents: different agents handling different repos, agents handling adversarial reviews, and so on. All of them work as a team. The agents message each other, ask for permissions, and coordinate through the agent-to-agent protocol, so from your side it still feels like a single conversation.

One parent, many children

Every session has a parent agent. The parent keeps the overall task context, plans across the selected repos, and delegates repo-specific work to child agents. Each child agent runs in its own repo with its own working copy, a git worktree or a clone, so changes in one repo never step on changes in another.

Delegation usually happens on its own: describe the task, and the parent spawns children as the work crosses repo boundaries. You can also delegate explicitly from the terminal:

polygraph agent spawn --repo <repo> "Update the client to the new API"

Mix agent runtimes

Polygraph is agent-agnostic, so one session can be shared between different AI agents. Each child can run a different agent runtime. Pass --agent with claude, codex, or opencode:

polygraph agent spawn --repo <repo> "Update the client to the new API" --agent codex

Changing agents during handoff

The same applies over time: a session started with one agent can be resumed with another. Different team members can use different agents. You can switch agents if you hit limits.

Run several agents in one repo

A repo can host more than one agent at a time, distinguished by role. Each (repo, role) pair runs its own agent, so independent streams of work can proceed concurrently: the default agent implements a feature while a reviewer or ci-investigator (you can use any role name) works alongside it.

polygraph agent spawn --repo <repo> "Review the changes on this branch" --role reviewer --agent opencode

This is how adversarial reviews work: the adversarial-review skill spawns a second reviewer agent with the reviewer role next to each repo's default agent. You can also run different types of agents in the same repo: implement with Claude, review with OpenCode.

Omitting --role targets the default agent. Only the default agent's logs are uploaded to the cloud and displayed in the terminal by default. View a non-default agent locally with polygraph agent attach --repo <repo> --role <role>, or simply run polygraph agent attach to select an agent from a list.