# Polygraph - full documentation

Concatenated Markdown source of every page on the Polygraph docs site, intended for AI agents that need the full knowledge base in one fetch.

---
Title: See everything, forget nothing
Description: Polygraph is a meta-harness for maximum agentic autonomy. It works with the agents you already use and connects every repo and every session in your organization.
URL: https://docs.trypolygraph.com/
---

Polygraph is an agent-agnostic [meta-harness](https://metaharness.tools?utm_source=docs.trypolygraph.com) for maximum agentic autonomy. It doesn't replace the agent you already use (Claude Code, Codex, OpenCode), it adds the components agents need to work effectively in real organizations.

In a real organization, agents hit two walls:
* **Space**: An agent is stuck in one repo. It can't see how a change fits the wider system, and it can only write to one repo at a time.
* **Time**: An agent forgets. Every session starts from a blank slate, so a human carries the context.

Polygraph lifts both:

* It connects all your repos (private and public) into a unified dependency graph without moving any code, so your agent reads and writes across every repo you have access to and orchestrates the PRs and CI as one change. **Think of it as a synthetic monorepo: monorepo ergonomics, no migration.**
* It records every agent session, so you can resume, reference, or build on work done by anyone, on any machine, even with a different agent.

{% youtube id="_F92ZJWWzb8" title="Polygraph demo" /%}

## What's next

Use the [Quickstart](/getting-started/quickstart) guide to get up and running.

### Explore our features

{% cardsection %}

{% cardgrid %}

{% linkcard title="Cross-repo agent sessions" description="Choose the repos a session should use and expand the working set as the task crosses repo boundaries." href="/features/cross-repo-agent-sessions" /%}

{% linkcard title="Cross-repo PR and CI coordination" description="Open, link, track, and verify related PRs across repos from one session." href="/features/cross-repo-pr-and-ci-coordination" /%}

{% linkcard title="OSS repo integration" description="Bring public OSS repos into a session for repros, upstream debugging, and integration validation." href="/features/oss-repo-integration" /%}

{% linkcard title="Institutional memory" description="Search past sessions, reference them as context, and debrief them into structured summaries." href="/features/institutional-memory" /%}

{% linkcard title="Background session capture" description="Record agent sessions run outside Polygraph, so the work behind a pull request stays reviewable." href="/features/background-session-capture" /%}

{% linkcard title="Resuming and handoff" description="Resume a session tomorrow, continue it on another machine or with a different agent, or hand it to a teammate." href="/features/resuming-and-handoff" /%}

{% linkcard title="Code reviews" description="Review the session behind a change, ask about the decisions, and run adversarial reviews." href="/features/code-reviews" /%}

{% linkcard title="Using multiple agents" description="A parent agent plans the work, child agents execute it per repo, and roles let several agents share a repo." href="/features/using-multiple-agents" /%}

{% linkcard title="Account insights" description="Break down agent token spend across the account by repo, session, person, model, and harness." href="/features/account-insights" /%}

{% /cardgrid %}

{% /cardsection %}

### Explore use cases

{% cardgrid %}

{% taggedcard title="Migrate a library" tag="Platform Team" description="Move every repo that uses a library to a new version, with the library's source in the session for context." href="/use-cases/migrate-a-library" /%}

{% taggedcard title="Patch a CVE" tag="Platform Team" description="Find every affected repo, open patch PRs, and hand each to the owning team with the audit trail intact." href="/use-cases/patch-a-cve" /%}

{% taggedcard title="Update backend and frontend" tag="Dev Team" description="Ship one feature across a backend API and the frontend that calls it." href="/use-cases/update-backend-and-frontend" /%}

{% taggedcard title="Update multiple microservices" tag="Dev Team" description="Change a shared contract, verify every consumer, and coordinate the merge order." href="/use-cases/update-multiple-microservices" /%}

{% taggedcard title="Update a design system component" tag="Design System Team" description="Validate the change against every consumer, then PR the clean ones and flag the rest." href="/use-cases/update-a-design-system-component" /%}

{% taggedcard title="Review code with full context" tag="Senior Eng on Dev Team" description="Review the reasoning behind an agent-written PR by asking the session, not just reading the diff." href="/use-cases/review-code-with-full-context" /%}

{% taggedcard title="Find and reuse prior work" tag="Everyone" description="Search past sessions, trace a commit back to its session, and anchor new work to settled approaches." href="/use-cases/find-and-reuse-prior-work" /%}

{% taggedcard title="Set up a software factory" tag="Everyone" description="Run agent-driven development as a repeatable pipeline that improves with every session." href="/use-cases/set-up-a-software-factory" /%}

{% taggedcard title="For OSS developers" description="Triage contributor repros and validate fixes against the consuming repo." href="/oss/for-oss-developers" /%}

{% /cardgrid %}

---
Title: CLI
Description: Polygraph CLI for cross-repo coordination
URL: https://docs.trypolygraph.com/cli
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

{% aside type="note" %}
This page is generated from the Polygraph CLI source. Edit the CLI in ocean and run `pnpm sync:cli-ref` to regenerate.
{% /aside %}

Polygraph CLI for cross-repo coordination

## Commands

- [`polygraph auth`](/cli/auth) - Authentication and environment selection
- [`polygraph whoami`](/cli/whoami) - Show current auth status + account
- [`polygraph graph`](/cli/graph) - Explore the repository dependency graph
- [`polygraph account`](/cli/account) - Account management
- [`polygraph repo`](/cli/repo) - Repository management
- [`polygraph session`](/cli/session) - Session management
- [`polygraph agent`](/cli/agent) - Child agent controls
- [`polygraph config`](/cli/config) - Local Polygraph CLI configuration
- [`polygraph git`](/cli/git) - Git workflows
- [`polygraph doctor`](/cli/doctor) - Diagnose bundle verification, download, cache, and load issues

## Global options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version`, `-v` | `boolean` |  | Show the version number for the CLI |
| `--url` | `string` | `https://snapshot.app.trypolygraph.com` | Polygraph environment URL |
| `--account`, `--acct` | `string` |  | Account ID to operate on |
| `--json` | `boolean` | `false` | Output machine-readable JSON. AI agents should always pass this flag when running polygraph CLI commands. |

---
Title: polygraph account
Description: Account management
URL: https://docs.trypolygraph.com/cli/account
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Account management

```sh
polygraph account
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph account list`

List accounts

```sh
polygraph account list
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph account select`

Select an account

```sh
polygraph account select [account]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `account` | `string` | Account ID or name to select directly |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

---
Title: polygraph agent
Description: Child agent controls
URL: https://docs.trypolygraph.com/cli/agent
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Child agent controls

```sh
polygraph agent
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph agent list`

List child agents for a session

```sh
polygraph agent list
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |

## `polygraph agent spawn`

Delegate work to a child agent

```sh
polygraph agent spawn [repo] [instruction]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |
| `instruction` | `string` | Instruction to execute |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--role` | `string` |  | Agent role within the repo (e.g. 'reviewer'). Omitted = the default role. Each role runs its own agent; only the default role's logs are uploaded to the cloud. |
| `--context` | `string` |  | Additional context for the delegated task |
| `--agent` | `"claude"` \| `"opencode"` \| `"codex"` \| `"auto"` |  | Agent runtime to use |

## `polygraph agent show`

Show child agent status for a repository (repo required)

```sh
polygraph agent show [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--role` | `string` |  | Agent role within the repo (e.g. 'reviewer'). Omitted = the default role. Each role runs its own agent; only the default role's logs are uploaded to the cloud. |
| `--tail` | `number` |  | Number of trailing log lines to include |
| `--wait-for-transition-ms` | `number` |  | Block up to this many milliseconds (capped at 50000) until the child leaves its current in-progress state, then print the status. 0 or absent returns immediately. When set, output is always JSON; omit this flag for default human-readable format. |

## `polygraph agent attach`

Attach a TUI to a child agent

```sh
polygraph agent attach [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--repo`, `-r` | `string` |  | Repository (ID, full name, or short name) — optional; the picker resolves it when omitted. |
| `--role` | `string` |  | Agent role within the repo (e.g. 'reviewer'). Omitted = the default role. Each role runs its own agent; only the default role's logs are uploaded to the cloud. |

## `polygraph agent stop`

Stop a child agent

```sh
polygraph agent stop [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--role` | `string` |  | Agent role within the repo (e.g. 'reviewer'). Omitted = the default role. Each role runs its own agent; only the default role's logs are uploaded to the cloud. |

## `polygraph agent allow`

Grant a child agent's pending permission-required request

```sh
polygraph agent allow [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--role` | `string` |  | Agent role within the repo (e.g. 'reviewer'). Omitted = the default role. Each role runs its own agent; only the default role's logs are uploaded to the cloud. |
| `--scope` | `"one-time"` \| `"session"` | `one-time` | Grant scope — 'one-time' applies only to this request; 'session' remembers it for equivalent later requests within the child's session |
| `--reason` | `string` |  | Optional reason for the grant |

## `polygraph agent deny`

Deny a child agent's pending permission-required request

```sh
polygraph agent deny [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--role` | `string` |  | Agent role within the repo (e.g. 'reviewer'). Omitted = the default role. Each role runs its own agent; only the default role's logs are uploaded to the cloud. |
| `--reason` | `string` |  | Optional reason for the denial |

## `polygraph agent events`

Stream a session's child permission-gate transitions as NDJSON (machine-only)

```sh
polygraph agent events
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--follow` | `boolean` | `false` | Stay alive and stream new permission-gate transitions (tail -f). Without it, dump current pending gates and exit. |

---
Title: polygraph auth
Description: Authentication and environment selection
URL: https://docs.trypolygraph.com/cli/auth
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Authentication and environment selection

```sh
polygraph auth
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph auth login`

Authenticate with Polygraph

```sh
polygraph auth login
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--insecure-storage` | `boolean` | `false` | Store OAuth credentials in the legacy 0600 INI file when no OS keychain is available |

## `polygraph auth logout`

Remove stored credentials for the effective URL

```sh
polygraph auth logout
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph auth select`

Switch the active Polygraph environment. Runs interactively by default; pass --url <url> to set the active environment non-interactively. Use `polygraph auth list` to see configured environments.

```sh
polygraph auth select
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph auth list`

List configured Polygraph environments

```sh
polygraph auth list
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph auth whoami`

Show current auth status + account

```sh
polygraph auth whoami
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

---
Title: polygraph config
Description: Interactive configuration editor and config file reference for Polygraph.
URL: https://docs.trypolygraph.com/cli/config
---

<!-- Hand-authored page. Excluded from scripts/sync-cli-ref.mjs (HAND_AUTHORED); edit this file directly. -->

```sh
polygraph config
```

`polygraph config` opens an interactive two-pane editor for `~/.polygraph/config.json`.
The editor covers the most commonly configured settings: general settings, per-agent
options, and per-repo options. The config file itself supports more than the editor
exposes; see the [config file reference](#config-file-reference) below.

`polygraph config` is interactive and does not support `--json`.

**Left pane** — the editable tree, organized into three groups:

- **General** — session-wide settings: [default agent](#agenttype),
  [multiplexer](#multiplexer), [git protocol](#gitprotocol), and [theme](#theme).
- **Agents** — one row per agent (Claude, Codex, OpenCode). The first item under
  each agent is the plugin item, which shows a status chip (plugin installed, plugin
  outdated, plugin not found, checking plugin..., installing plugin..., or plugin
  install failed). Press `Enter` (or `i`) on the plugin item to install or update the
  agent's plugin. Below it are the agent's `trust`, `sandbox`, and
  [`auto mode`](#auto-mode) fields.
- **Repositories** — one row per configured repository, rendered as flat aligned
  rows: `Create using`, `Trust`, and `Sandbox`. Unset `Trust` and `Sandbox` values
  show `(inherit)`; a worktree strategy shows its base inline
  (`worktree · base: /path/to/clone`). Press `a` to add a repo from your account and
  `d` to remove one. Before any repo is configured, the section is a single hint
  line: `Press a to configure a repo`.

**Right pane** — contextual help for the focused property.
As you move the selection, the right pane updates to explain the focused field or plugin item,
including its install location.

### Keys

| Key | Action |
| --- | ------ |
| `↑`/`k`, `↓`/`j` | Move the selection |
| `Enter` | The focused row's primary action: install or update the plugin on a plugin item, cycle the value everywhere else |
| `Space` | Cycle the value |
| `←`/`h`, `→`/`l` | Cycle the value backward / forward |
| `c` | Clear the field back to its default (unset) |
| `i` | Install or update the plugin (plugin items) |
| `a` | Add a repo from your account |
| `d`, `Backspace` | Remove the focused repo |
| `s` | Save and exit |
| `q`, `Esc`, `Ctrl+C` | Exit |

### Edits are staged until you save

Every change you make in the editor is staged in memory. Nothing is written to
`~/.polygraph/config.json` until you save. Saving only touches the keys you
edited: clearing a value (`c`) deletes that key from the file, and keys you
didn't touch in the editor are never modified by a save.

`s` saves and exits. `q`, `Esc`, and `Ctrl+C` exit, and when you have staged
changes they first ask what to do with them: **Save and exit** (selected by
default), **Continue editing**, or **Exit without saving**. With nothing staged,
they exit right away.

### General settings

| Setting | Config key | Values | Unset behavior |
| ------- | ---------- | ------ | -------------- |
| Default agent | [`agentType`](#agenttype) | `claude`, `codex`, `opencode` | Each session prompts for an agent |
| Multiplexer | [`multiplexer`](#multiplexer) | `auto`, `none`, `tmux`, `iterm2`, `kitty`, `ghostty`, `cmux`, `zellij`, `herdr`, `windows-terminal` | Session start asks before opening panes |
| Git protocol | [`gitProtocol`](#gitprotocol) | `ssh`, `https` | Auto-detected from your git and gh setup |
| Theme | [`theme`](#theme) | `auto`, `light`, `dark` | — (`auto` is the default) |

- **Default agent** — the agent launched for new sessions. When set, commands that
  would prompt for an agent (`polygraph session start`, session reconstruction on
  resume) use it without asking; explicit agent flags still override it. When unset,
  each session prompts for an agent.
- **Multiplexer** — how Polygraph opens child agent panes. `auto` picks the first
  available multiplexer; `none` keeps everything in one terminal. When unset, session
  start asks before opening panes. The editor probes your terminal and notes which
  multiplexers it detects; if you stage one that isn't detected, session start will
  unset it and ask again.
- **Git protocol** — the protocol used to clone session repositories. When unset,
  Polygraph auto-detects it from your git and gh setup. The `POLYGRAPH_GIT_PROTOCOL`
  environment variable overrides this for a single run.
- **Theme** — the color theme for the Polygraph terminal UI. `auto` detects the
  terminal background; `light` or `dark` force it.

## `polygraph config validate`

Validate the local Polygraph config file.

```sh
polygraph config validate
```

Schema violations are reported as warnings and don't fail the command. Invalid JSON is
fatal: if the file can't be parsed, the command errors out.

### Options

| Flag | Type | Description |
| ---- | ---- | ----------- |
| `--help`, `-h` | `boolean` | Show help for the current command |
| `--version` | `boolean` | Show the version number for the CLI |

---

## Config file reference

All Polygraph settings live in `~/.polygraph/config.json`. The interactive editor
manages the most commonly configured keys: the General settings (`agentType`,
`multiplexer`, `gitProtocol`, `theme`), `agentOptions`, and `repoOptions`.
Everything else is edited directly in the file. The complete schema is written to
`~/.polygraph/schema.json` and referenced from the file's `$schema` key, so editors with
JSON-schema support can provide completion and validation for every setting.

| Key | Managed by | Description |
| --- | ---------- | ----------- |
| [`agentType`](#agenttype) | `polygraph config` | Default agent for new sessions. |
| [`multiplexer`](#multiplexer) | `polygraph config` | Terminal multiplexer used for session panes. |
| [`gitProtocol`](#gitprotocol) | `polygraph config` | Preferred clone protocol (`ssh` or `https`). |
| [`theme`](#theme) | `polygraph config` | Color theme for the Polygraph terminal UI. |
| [`agentOptions`](#agentoptions) | `polygraph config` | Per-agent settings: `trust`, `sandbox`, `autoMode`, `extraArgs`, `env`. |
| [`repoOptions`](#repooptions) | `polygraph config` | Per-repo settings: `createUsing`, `trust`, `sandbox`. |
| [`repoStrategy`](#repostrategy) | hand-edited | Default creation strategy and per-repo overrides. |
| [`setupScripts`](#setupscripts) | hand-edited | Local overrides for repo setup scripts. |
| [`globalRoot`](#globalroot) | hand-edited | Where session folders are created. |
| `selectedUrl` | Polygraph CLI | Selected Polygraph environment URL. |
| `$schema` | Polygraph CLI | Points at the generated `schema.json`. |

### Annotated sample

```json
{
  "agentType": "claude",   // Default agent for new sessions. Unset: prompt each session.
  "multiplexer": "tmux",   // Multiplexer for session panes. Unset: ask at session start.
  "gitProtocol": "ssh",    // Clone protocol. Unset: auto-detect from git/gh.
  "theme": "auto",         // TUI color theme: auto, light, or dark.
  "agentOptions": {
    // Per-agent settings. Valid keys: "claude", "codex", "opencode".
    "claude": {
      "trust": true,      // Skips per-action permission gating for this agent.
      "sandbox": true,    // Runs the agent inside a sandbox.
      "extraArgs": ["--verbose"],  // Extra CLI args for the agent process.
      "env": {
        "HTTP_PROXY": "http://localhost:8080"  // Extra env vars injected into the agent process.
      }
    },
    "codex": {
      "trust": true,
      "sandbox": true
    },
    "opencode": {
      "trust": false,
      "autoMode": true    // Uses the agent's own approval automation instead of trust.
    }
  },
  "repoOptions": {
    // Per-repo settings. Keyed by full repo name (org/repo).
    "acme/api": {
      "createUsing": "worktree",  // How Polygraph creates the working copy.
      "trust": false,             // Per-repo trust override (overrides agentOptions value).
      "sandbox": true             // Per-repo sandbox override.
    },
    "acme/frontend": {
      "createUsing": "clone"
    }
  }
}
```

### `agentOptions`

Keyed by agent name. Valid keys are `claude`, `codex`, and `opencode`.

| Field | Type | Description |
| ----- | ---- | ----------- |
| `trust` | `boolean` | Whether the agent runs trusted (skips per-action permission gating) by default. |
| `sandbox` | `boolean` | Whether the agent runs inside a sandbox by default. |
| `autoMode` | `boolean` | Whether the agent uses its own approval automation. See [auto mode](#auto-mode). |
| `extraArgs` | `string[]` | Extra command-line arguments passed to the agent process. |
| `env` | `object` (string → string) | Extra environment variables injected into the agent process. |

`extraArgs` and `env` are not exposed in the interactive editor and have to be edited
directly in the file.

#### Per-agent defaults

When an agent has no entry in `agentOptions` (or omits a field), its effective `trust`,
`sandbox`, and `autoMode` fall back to these built-in defaults:

| Agent | Default `trust` | Default `sandbox` | Default `autoMode` |
| ----- | --------------- | ----------------- | ------------------ |
| Claude | ✓ on | ✓ on | ✗ off |
| Codex | ✓ on | ✓ on | ✗ off |
| OpenCode | ✗ off | not supported | ✗ off |

#### Auto mode

`autoMode` hands approval decisions to the agent's own automation instead of
Polygraph's trust setting. Each agent has its own name for it: Claude and OpenCode
call it Auto mode, and Codex calls it Approve for me, which routes on-request
approvals to automatic review. OpenCode approves any request it does not explicitly
deny.

`trust` and `autoMode` are two answers to the same question, so the editor keeps
them mutually exclusive: turning one on turns the other off. Auto mode is available
for every agent on every platform.

The sandbox is configured separately and is unaffected by `autoMode`. An agent can
run in auto mode inside the sandbox.

#### Sandbox

Claude and Codex agents run inside an OS-level filesystem sandbox by default.
The sandbox belongs to the agent harness — Claude Code uses Seatbelt on
macOS or bubblewrap on Linux; Codex uses its own `workspace-write` sandbox.
Polygraph configures the sandbox through each harness's settings.

Platform support differs by harness:

- **Claude Code** — macOS, Linux, and WSL2. The sandbox cannot engage on
  native Windows, so Polygraph disables it there.
- **Codex** — macOS, Linux, and Windows. Codex's sandbox works on Windows
  using a restricted-token boundary.

The sandbox restricts where the agent can write. Only these paths are writable:

- `~/.npm`
- `~/.polygraph/logs`
- `~/.polygraph/bundles`
- The system temp directory
- The current session root (`~/.polygraph/sessions/<session-id>/`)
- The repository working tree

The repository working tree is in the allowlist, so the agent can edit source
files, run builds, run tests, and run git commands normally. But the sandbox
keeps the agent's own configuration directory read-only — `.claude/` for
Claude, `.codex/` for Codex.

This means a `git rebase` or `git checkout` can fail if it needs to update
files under the agent's configuration directory (for example, `.claude/skills/`
checked into the repo). In practice this is rare — the agent can still
commit, push, and create branches normally.

{% aside type="note" %}
Polygraph's own push-time `git pull --rebase` runs outside the agent
sandbox, so pushing a branch still works. The limitation is only when the
agent itself runs a rebase or checkout inside the session.
{% /aside %}

##### Configuration

Disable the sandbox globally for an agent type:

```json
{
  "agentOptions": {
    "claude": {
      "sandbox": false
    }
  }
}
```

Disable it for a single repository:

```json
{
  "repoOptions": {
    "nrwl/ocean": {
      "sandbox": false
    }
  }
}
```

With the sandbox on (the default), the agent is more constrained but you get
maximum isolation. Polygraph's push command handles pre-push pull-rebase for
you, so pushes still work even with the sandbox enabled.

##### Configuring the sandbox through the agent harness

The `sandbox` boolean above is a convenience on/off toggle. Because the
sandbox belongs to the agent harness, you can also configure it in detail
through each harness's own settings. Polygraph generates its own settings
on every launch (Claude's `--settings` flag, or Codex's `-c` overrides and
`--sandbox`/`--add-dir` flags) that enable the sandbox and set the writable
roots.

**Claude Code**

Sandbox settings live in Claude Code's settings files:
`~/.claude/settings.json` (user), or the project's
`.claude/settings.json` / `.claude/settings.local.json`. The relevant keys
are under the `sandbox` object:

| Key | Type | Description |
| --- | ---- | ----------- |
| `sandbox.enabled` | `boolean` | Whether the sandbox is enabled (macOS, Linux, WSL2) |
| `sandbox.filesystem.allowWrite` | `string[]` | Additional writable paths |
| `sandbox.filesystem.denyWrite` | `string[]` | Paths denied for writes |
| `sandbox.filesystem.denyRead` | `string[]` | Paths denied for reads |

```json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.cache"],
      "denyWrite": ["./secrets"]
    }
  }
}
```

Array settings (`allowWrite`, `denyWrite`, `denyRead`) are merged across all
settings scopes — paths you add are combined with Polygraph's generated list,
not replaced. Scalar values like `sandbox.enabled` follow normal precedence,
where Polygraph's `--settings` takes priority. See Claude Code's
[sandbox settings](https://code.claude.com/docs/en/settings#sandbox-settings)
documentation for the full schema.

**Codex**

Codex sandbox is configured in `~/.codex/config.toml` (or the project's
`.codex/config.toml`) and via CLI flags (`--sandbox`, `--add-dir`). The
sandbox mode is set with `sandbox_mode`; Polygraph uses `workspace-write`
when the sandbox is on. The available modes are `read-only`,
`workspace-write`, and `danger-full-access`. The relevant config keys
are under the `[sandbox_workspace_write]` table:

| Key | Type | Description |
| --- | ---- | ----------- |
| `sandbox_mode` | `string` | Sandbox mode: `read-only`, `workspace-write`, or `danger-full-access` |
| `sandbox_workspace_write.writable_roots` | `string[]` | Additional writable paths |
| `sandbox_workspace_write.network_access` | `boolean` | Whether outbound network access is allowed |

```toml
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = ["/Users/YOU/.cache"]
```

In `workspace-write` mode, `.codex/` is kept read-only even when the rest of
the workspace is writable. See Codex's
[advanced configuration](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes)
documentation for the full schema.

{% aside type="caution" title="Turning the sandbox off removes filesystem isolation" %}
Without the sandbox, the agent can write anywhere its OS user can. Only
disable it when you understand and accept the risk.
{% /aside %}

#### Environment inheritance

Child agents inherit the environment of the shell where you started the Polygraph session.
Provider-routing variables like `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` reach child agents this way.

`agentOptions.<agent>.env` entries override inherited values with the same key.
Use `env` to pin a value for a specific agent type regardless of what the shell provides.

#### `extraArgs` semantics

`extraArgs` are appended to the child agent's command line after Polygraph's own flags.
Repeated flags resolve last-wins, so `extraArgs` can override Polygraph's defaults.
For example, adding `["--model", "claude-opus-4-5"]` to a Claude entry overrides the model Polygraph would otherwise use.

#### Model selection

Polygraph never forces a model on child agents.
Each child resolves its model from that agent's own configuration, as if you launched the agent yourself.

Default resolution by agent:

- `claude`: its own settings, the `ANTHROPIC_MODEL` environment variable, or the CLI default.
- `codex`: the `model` setting in `~/.codex/config.toml`.
- `opencode`: the `model` setting in `opencode.json` (provider/model format).

To pin a model for all children of a given agent type, add it to `agentOptions`:

- `claude`: `"extraArgs": ["--model", "<model-id>"]` (repeated flags resolve last-wins) or `"env": {"ANTHROPIC_MODEL": "<model-id>"}`.
- `codex`: `"extraArgs": ["-c", "model=<model-id>"]` (Codex accepts `-c key=value` config overrides on the command line).
- `opencode`: set the model in your OpenCode configuration file.

#### Proxy-backed environments

When Claude is routed through an Anthropic-compatible proxy, such as a GitHub Copilot-backed endpoint, set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` in your shell.
Child agents inherit those variables automatically.
No `env` entry is needed for them.

If the proxy's model catalog uses different identifiers than Anthropic's, pin the model in `agentOptions`.
A complete example combining `agentOptions` and `repoOptions`:

```json
{
  "$schema": "~/.polygraph/schema.json",
  "agentOptions": {
    "claude": {
      "trust": true,
      "sandbox": true,
      "env": {
        "ANTHROPIC_MODEL": "<provider-model-id>"
      }
    },
    "codex": {
      "trust": true,
      "sandbox": true
    }
  },
  "repoOptions": {
    "acme/api": {
      "trust": false
    },
    "acme/frontend": {
      "createUsing": "worktree"
    }
  }
}
```

`ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` are inherited from the shell and don't need to appear in `env`.
You'd only add them here to override what the shell provides for a specific agent type.
`env` and `extraArgs` are agent-level only.
There's no per-repo override for them.

### `repoOptions`

Keyed by repository full name (for example `acme/api`).

| Field | Type | Description |
| ----- | ---- | ----------- |
| `createUsing` | strategy | How Polygraph creates the repository working copy for the session. |
| `trust` | `boolean` | Per-repo override of the effective `trust` for any agent operating in this repo. |
| `sandbox` | `boolean` | Per-repo override of the effective `sandbox` for any agent operating in this repo. |

#### `createUsing` strategies

`createUsing` accepts one of three strategies as a bare string:

| Value | Description |
| ----- | ----------- |
| `clone` | Polygraph clones the repo into the session folder. |
| `worktree` | Polygraph creates a git worktree from an existing local clone. |
| `superset` | Polygraph uses a superset working copy shared across repos. |

Most repos only need the bare string form:

```json
{ "createUsing": "worktree" }
```

Each strategy also accepts an object form with a `type` discriminator and per-strategy options:

- `worktree` accepts an optional `base` (path to the local clone).
- `superset` accepts an optional `include` (string array of repos to group) and `sectionName`.

```json
{ "createUsing": { "type": "worktree", "base": "/path/to/local/clone" } }
```

#### Resolution rules

The effective `trust` and `sandbox` for an agent working in a repo is resolved along
this chain, where the most specific value wins:

```
built-in per-agent default  →  agentOptions[<agent>]  →  repoOptions[<repo>]
```

A `repoOptions[<repo>]` value overrides the agent-level value, which overrides the
built-in default. A field that isn't set inherits from the previous layer. An explicit
`false` does not fall through: setting `trust: false` at the repo or agent level turns
it off. `extraArgs` and `env` are agent-only and have no per-repo override.

Some examples:

- Claude's built-in `trust` default is `true`. In a repo with `"trust": false` under
  `repoOptions["acme/api"]`, Claude runs untrusted because the per-repo value wins.
- A repo with no `trust` field in `repoOptions` inherits the agent's value: `true` for
  Claude, and OpenCode's built-in default of `false` for OpenCode.
- Setting `agentOptions.opencode.trust = true` makes OpenCode trusted in every repo
  that doesn't override it, since the agent layer beats the built-in default.

### `repoStrategy`

The default creation strategy for repositories that do not set their own
`createUsing`, plus per-repo overrides:

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

Both `default` and each override accept the same values as
[`createUsing`](#createusing-strategies). When a session creates a working copy for a repo, the
strategy resolves in this order:

```
repoOptions[<repo>].createUsing  →  repoStrategy.overrides[<repo>]  →  repoStrategy.default
```

The built-in default is `clone`. The repo a session is started from is always used
in place and ignores these settings.

### `setupScripts`

Local overrides for the setup script that runs after a repo working copy is created in a
session. Keyed by repo full name; `*` wildcards are supported:

```json
{
  "setupScripts": {
    "acme/api": "pnpm install",
    "acme/*": { "script": "./scripts/setup.sh", "mode": "replace" }
  }
}
```

A bare string is shorthand for `{ "script": "...", "mode": "after" }`.

- `after` runs after the repo's server-configured setup script.
- `replace` replaces the server-configured setup entirely. When several `replace`
  patterns match the same repo, the most specific one wins; a literal repo name beats
  a wildcard.

Malformed entries are skipped with a warning.

#### Running steps only during indexing runs

The repo's server-configured setup script also runs when Polygraph indexes the
repository in an ephemeral container. During an indexing run the
`POLYGRAPH_REPOSITORY_ID` environment variable is set. It is not set in
interactive sessions, so the script can check it to run steps only while
indexing, or invert the check (`-z`) to skip steps during indexing runs (for
example, skipping dev-server startup in the container):

```sh
if [ -n "${POLYGRAPH_REPOSITORY_ID:-}" ]; then
  # Indexing run: NPM_TOKEN is provided to the container's environment.
  npm config set -L project @scope:registry=https://npm.pkg.github.com
  npm config set -L project //npm.pkg.github.com/:_authToken="${NPM_TOKEN}"
fi
```

Local overrides from this key apply only to interactive sessions on your machine
and are never used during indexing, so indexing-only steps belong in the repo's
server-configured setup script.

### `agentType`

The default agent for new sessions: `claude`, `codex`, or `opencode`. When set,
commands that would prompt for an agent — `polygraph session start` and session
reconstruction on resume — use it without asking; explicit agent flags like
`--agent` still override it. When unset, each session prompts for an agent.

Values are matched case-insensitively and surrounding whitespace is ignored, so a
hand-edited `"Claude "` still resolves to `claude`.

### `multiplexer`

Which terminal multiplexer Polygraph uses to open session panes. One of `auto`, `none`,
`tmux`, `iterm2`, `kitty`, `ghostty`, `cmux`, `zellij`, `herdr`, or `windows-terminal`. `auto`
picks the first available multiplexer; `none` keeps everything in one terminal. When
unset, session start asks before opening panes.

### `gitProtocol`

Preferred git clone protocol for Polygraph repositories: `ssh` or `https`. Applies
everywhere Polygraph clones repos, including session reconstruction on resume. It
overrides git/gh auto-detection, and is itself overridden by the
`POLYGRAPH_GIT_PROTOCOL` environment variable. When unset, Polygraph auto-detects
the protocol from your git and gh setup.

### `theme`

The color theme for the Polygraph terminal UI: `auto`, `light`, or `dark`. `auto`
detects the terminal background; `light` and `dark` force it.

### `globalRoot`

The directory where Polygraph creates session folders. Defaults to
`~/.polygraph/sessions`. The `POLYGRAPH_ROOT` environment variable takes precedence.

### CLI-managed keys

Polygraph writes these itself and they rarely need to be edited by hand:

- `selectedUrl` is the Polygraph environment URL the CLI is signed into.
- `$schema` points at the generated `schema.json` next to the config file.

---
Title: polygraph doctor
Description: Diagnose bundle verification, download, cache, and load issues
URL: https://docs.trypolygraph.com/cli/doctor
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Diagnose bundle verification, download, cache, and load issues

```sh
polygraph doctor
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--runtime` | `boolean` | `false` | Also collect bundle-side process, sidecar, and session log diagnostics |
| `--processes` | `boolean` | `false` | Alias for --runtime; kept short for CPU/process investigations |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |

---
Title: polygraph git
Description: Git workflows
URL: https://docs.trypolygraph.com/cli/git
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Git workflows

```sh
polygraph git
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph git create-pr`

Create PRs from a spec file

```sh
polygraph git create-pr
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--description` | `string` |  | Session description for handoff context (required; pass "none" to skip the update) |
| `--agent-session-id` | `string` |  | Agent session ID to save with the session |
| `--spec-file` | `string` |  | Path to PR spec JSON file |

## `polygraph git update-pr`

Update metadata on a session pull request

```sh
polygraph git update-pr
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--pr-url` | `string` |  | Associated PR URL to update |
| `--title` | `string` |  | Replace the PR title |
| `--body` | `string` |  | Replace the PR body. Pass an empty string to clear it |
| `--set-label` | `array<string>` |  | Replace all labels. Repeat for multiple labels; use --clear-labels for none |
| `--clear-labels` | `boolean` |  | Remove all labels |
| `--add-label` | `array<string>` |  | Add a label. Repeat for multiple labels |
| `--remove-label` | `array<string>` |  | Remove a label. Repeat for multiple labels |
| `--set-assignee` | `array<string>` |  | Replace all assignees. Repeat for multiple assignees; use --clear-assignees for none |
| `--clear-assignees` | `boolean` |  | Remove all assignees |
| `--add-assignee` | `array<string>` |  | Add an assignee. Repeat for multiple assignees |
| `--remove-assignee` | `array<string>` |  | Remove an assignee. Repeat for multiple assignees |

## `polygraph git associate-pr`

Associate an existing PR with a session

```sh
polygraph git associate-pr
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--description` | `string` |  | Session description for handoff context (required; pass "none" to skip the update) |
| `--agent-session-id` | `string` |  | Agent session ID to save with the session |
| `--pr-url` | `string` |  | PR URL to associate |
| `--branch` | `string` |  | Branch name to associate by |
| `--repo`, `-r` | `string` |  | Repository (ID, full name, or short name) |

## `polygraph git mark-pr-ready`

Mark one or more PRs ready for review

```sh
polygraph git mark-pr-ready
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--agent-session-id` | `string` |  | Agent session ID to save with the session |
| `--pr-url` | `array<string>` |  | PR URL(s) to mark ready |

## `polygraph git push-branch`

Push the current branch for a session repository

```sh
polygraph git push-branch [repo] [branch]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |
| `branch` | `string` | Branch name to push |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--description` | `string` |  | Session description for handoff context (required; pass "none" to skip the update) |
| `--agent-session-id` | `string` |  | Agent session ID to save with the session |

## `polygraph git fetch`

Fetch more commit history for a session repository

```sh
polygraph git fetch [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--depth` | `number` |  | Fetch the newest N commits per ref instead of the full history |
| `--ref` | `array<string>` |  | Additional remote branch(es) to fetch (repeatable) |

## `polygraph git ci-logs`

Fetch and print the log for a CI job in a session

```sh
polygraph git ci-logs [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--job` | `number` |  |  |
| `--repo` | `string` |  |  |

---
Title: polygraph graph
Description: Explore the repository dependency graph
URL: https://docs.trypolygraph.com/cli/graph
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Explore the repository dependency graph

```sh
polygraph graph
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--static` | `string` \| `boolean` |  | Render a static text snapshot instead of opening the interactive TUI. Pass without a value to size to the terminal, or with dimensions like "200x100". |
| `--plain` | `boolean` | `false` | Disable ANSI color (also auto-disabled when piped). Applies to both interactive and --static output. |
| `--selectedRepos` | `string` |  | Pre-select these repos. CSV and globs (quote globs, e.g. 'nrwl/*'). Supports @current. In --static mode, the rendering shows only these and their direct neighbors. |
| `--include` | `string` |  | Whitelist of repos to include in the visualization. CSV and globs. Supports @current. Repos outside this set are hidden in both interactive and static mode. |
| `--exclude` | `string` |  | Repos to fully exclude from the visualization. CSV and globs. Supports @current. Excluded repos are hidden in both interactive and static mode. |

---
Title: polygraph repo
Description: Repository management
URL: https://docs.trypolygraph.com/cli/repo
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Repository management

```sh
polygraph repo
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph repo list`

List candidate repos in current org

```sh
polygraph repo list
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--filter`, `-f` | `object` |  | Filter repositories under a single object option |
| `--filter.name` | `string` |  | Repository name or full name (e.g. 'ocean', 'nrwl/ocean'). CSV for multiple values. Supports @current. |
| `--filter.connectedTo` | `string` |  | Repository ID, name, or full name (e.g. 'ocean', 'nrwl/ocean'); pair with connectionType. Supports @current. |
| `--filter.publishedPackages` | `string` |  | Package names a repo publishes. CSV for multiple values. |
| `--filter.consumedPackages` | `string` |  | Package names a repo consumes. CSV for multiple values. |
| `--filter.publishedApis` | `string` |  | API paths a repo serves. CSV for multiple values. |
| `--filter.consumedApis` | `string` |  | API paths a repo consumes. CSV for multiple values. |
| `--filter.connectionType` | `string` |  | Which connections to include relative to connectedTo: directly-upstream \| directly-downstream \| directly-both (default) \| upstream \| downstream \| both. |
| `--filter.semanticQuery` | `string` |  | Free-text description of the repositories you want. |

## `polygraph repo show`

Show details of a single repo

```sh
polygraph repo show [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--web` | `boolean` | `false` | Open the repository in the browser |

---
Title: polygraph session
Description: Session management
URL: https://docs.trypolygraph.com/cli/session
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Session management

```sh
polygraph session
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

## `polygraph session start`

Start a new session

```sh
polygraph session start [title]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `title` | `string` | Session title |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--repo`, `-r` | `array<string>` |  | Repositories (ID, full name, or short name) |
| `--primary` | `string` \| `boolean` |  | Repository ID or org/repo name that should host the main agent. Use "none" or --no-primary to start without a primary repo. |
| `--primary-checkout`, `--prc` | `string` |  | What to do with the primary repo: in-place (default, run in the current checkout), fresh-checkout (a fresh copy via the configured strategy), or fresh-checkout-with-changes (a fresh copy with your uncommitted changes applied). |
| `--multiplexer`, `-m` | `string` |  | Open delegated child agents in a terminal multiplexer. Defaults to auto. One of: auto, none, tmux, iterm2, kitty, ghostty, cmux, zellij, herdr, windows-terminal. |
| `--agent`, `-a` | `string` |  | Launch the given agent after the session is created. One of: claude, codex, opencode, auto, skip. When omitted, falls back to the interactive prompt (or 'skip' under --json). |
| `--prompt`, `-p` | `string` |  | Initial task instruction passed to the launched agent. Replaces the default "ask the user what to do" trailer in the agent's startup message. Ignored when --launch is skip or omitted. |

## `polygraph session list`

List sessions

```sh
polygraph session list
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--since` | `string` |  | Only return sessions created on or after this date (YYYY-MM-DD, UTC). Defaults to the last 30 days. Example: --since=2025-01-01 |
| `--limit` | `number` | `100` | Maximum number of sessions to return (1–500, default 100). |
| `--filter`, `-f` | `object` |  | Filter sessions under a single object option |
| `--filter.status` | `string` |  | Match session status (open, archived, stale) using exact values, glob, or CSV patterns. Defaults to active (open) sessions; use '*' to include archived and stale. Quote globs, for example 'arch*'. |
| `--filter.author` | `string` |  | Match session authors using case-insensitive substring, glob, or CSV patterns. Defaults to @me, the current user; use '*' to include all authors. |
| `--filter.initiator` | `string` |  | Match the initiator repository using case-insensitive substring, glob, or CSV patterns. Supports @current. |
| `--filter.repo` | `string` |  | Match repositories included in a session using case-insensitive substring, glob, or CSV patterns. Supports @current. |
| `--filter.hasPrs` | `boolean` |  | Filter by whether sessions have at least one linked pull request. |

## `polygraph session show`

Show session details

```sh
polygraph session show [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--details` | `boolean` | `false` | Include a per-repo summary with PR id, url, and description. |

## `polygraph session search`

Search sessions by free text or commit sha

```sh
polygraph session search [query]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `query` | `string` | Search query: free text, or a commit sha (7-40 hex chars) to also match the linked session |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--limit` | `number` |  | Maximum number of results (1–50, default 5). Ignored by the interactive browser. |
| `--sha` | `string` |  | Exact lookup of the session linked to a commit by full or partial (7+ hex chars) sha, without free-text matches. Mutually exclusive with a query. |

## `polygraph session logs`

Show agent transcripts for a session (parent by default)

```sh
polygraph session logs [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--tail` | `string` |  | Page size: show N transcript entries per page (default 20). Pass --tail none for the full log. --json returns the full transcript unless --tail or --page is set. |
| `--page` | `number` |  | 1-based page within the --tail-sized windows (default 1 = newest). Higher pages step backward through history. |
| `--repo`, `-r` | `string` |  | Show the child agent transcript for one repository (ID, full name, or short name) instead of the parent transcript |
| `--all` | `boolean` |  | Show the parent transcript plus every child agent transcript |

## `polygraph session dir`

Open a shell in a session repository

```sh
polygraph session dir [session] [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |
| `repo` | `string` | Repository (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--root` | `boolean` | `false` | Open the session root instead of a repo |
| `--print` | `boolean` | `false` | Print the selected directory instead of launching a shell |
| `--command` | `string` |  | Run a shell command in the selected directory instead of launching a shell |

## `polygraph session update`

Update the current session title and/or description

```sh
polygraph session update [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--title`, `-t` | `string` |  | Title text to save with the session |
| `--description` | `string` |  | Description text to save with the session |

## `polygraph session resume`

Resume a session and wait for explicit user instructions

```sh
polygraph session resume [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--multiplexer`, `-m` | `string` |  | Set the terminal multiplexer for this resume. Defaults to auto. Pass none for no multiplexer. One of: auto, none, tmux, iterm2, kitty, ghostty, cmux, zellij, herdr, windows-terminal. |
| `--agent`, `-a` | `string` \| `boolean` |  | Choose the agent to resume the session with. Pass claude, codex, opencode, or auto to switch directly, or pass --agent with no value to choose interactively. |

## `polygraph session review`

Resume a session for review — the agent answers questions instead of continuing the work

```sh
polygraph session review [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--multiplexer`, `-m` | `string` |  | Set the terminal multiplexer for this review. Defaults to auto. Pass none for no multiplexer. One of: auto, none, tmux, iterm2, kitty, ghostty, cmux, zellij, herdr, windows-terminal. |
| `--agent`, `-a` | `string` \| `boolean` |  | Choose the agent to review the session with. Pass claude, codex, opencode, or auto to switch directly, or pass --agent with no value to choose interactively. |
| `--adversarial` | `boolean` | `false` | Run an adversarial review: the agent loads the adversarial-review skill and spawns an independent reviewer agent per repository. |

## `polygraph session archive`

Archive a session

```sh
polygraph session archive [session]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `session` | `string` | Session ID (auto-detects from cwd if omitted) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--clean` | `boolean` | `false` | Remove cloned repos after archiving |

## `polygraph session prune`

Clean up local files for archived or old sessions

```sh
polygraph session prune
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session` | `array<string>` |  | Session ID(s) to prune directly. Repeat for multiple sessions. |
| `--yes`, `-y` | `boolean` | `false` | Clean up all matching sessions without prompting |
| `--status` | `string` |  | Filter selected sessions by status using substring, glob, or CSV patterns. |
| `--author` | `string` |  | Preselect sessions by author using substring, glob, or CSV patterns. |
| `--hasPrs` | `boolean` |  | Preselect sessions based on whether they have linked pull requests. |
| `--older-than` | `number` | `30` | Preselect open sessions with no movement for more than this many days. |

## `polygraph session link-reference`

Link an external reference to a session

```sh
polygraph session link-reference
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--type` | `string` |  | External reference type |
| `--reference-url`, `--ref` | `string` |  | Reference URL |
| `--label` | `string` |  | Display label for the reference |
| `--referenceSessionId` | `string` |  | Referenced Polygraph session ID. Required when --type=session. |

## `polygraph session add-repo`

Add repositories to a session

```sh
polygraph session add-repo [repo]
```

### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `repo` | `array<string>` | Repositories to add (ID, full name, or short name) |

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |

## `polygraph session artifacts`

Manage session artifacts

```sh
polygraph session artifacts
```

### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

### `polygraph session artifacts upload`

Attach a plan, image, or file to a session (from --file or stdin)

```sh
polygraph session artifacts upload
```

#### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--file` | `string` |  | Path to the file to upload. Omit to read content from stdin (requires --name). |
| `--name` | `string` |  | Artifact name (unique per session; re-uploading a name adds a version). Defaults to the file name. |
| `--kind` | `"plan"` \| `"image"` \| `"file"` |  | Artifact kind. Inferred from the name/content type when omitted. |
| `--format` | `"markdown"` \| `"html"` \| `"text"` |  | Plan rendering format (plan artifacts only). |

### `polygraph session artifacts list`

List a session’s artifacts

```sh
polygraph session artifacts list
```

#### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |

### `polygraph session artifacts download`

Download an artifact by name

```sh
polygraph session artifacts download [name]
```

#### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `name` | `string` | Artifact name to download |

#### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `number` |  | Version number to download. Defaults to the latest. |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |
| `--out` | `string` |  | Write to this path. Omit to stream bytes to stdout. |

### `polygraph session artifacts delete`

Delete an artifact and all of its versions by name

```sh
polygraph session artifacts delete [name]
```

#### Arguments

| Name | Type | Description |
| ---- | ---- | ----------- |
| `name` | `string` | Artifact name to delete |

#### Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |
| `--session`, `-s` | `string` |  | Session ID (auto-detects from cwd if omitted) |

---
Title: polygraph whoami
Description: Show current auth status + account
URL: https://docs.trypolygraph.com/cli/whoami
---

<!-- Generated by scripts/sync-cli-ref.mjs. Do not edit by hand. -->

Show current auth status + account

```sh
polygraph whoami
```

## Options

| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `--help`, `-h` | `boolean` |  | Show help for the current command |
| `--version` | `boolean` |  | Show the version number for the CLI |

---
Title: Account insights
Description: Break down agent token spend for the whole account by repository, session, person, model, and harness.
URL: https://docs.trypolygraph.com/features/account-insights
---

Your model provider's dashboard already tells you what you spent. It breaks that spend down by user
and by API key, which says very little about the work itself. It can't tell you what a repo costs to
work in, or what an average session costs, because a provider dashboard has no idea what a repo or a
session is.

Polygraph does. Every session it records carries the repo it ran in, the person who ran it, and the
agent and model behind it, so Account insights can group the same tokens by the things you actually
plan around.

![Account insights for an account: total tokens with the cached share, top repository, top model, and top harness, above a stacked area chart of daily usage split by model](./account-insights-overview-theme-light.avif)

![Account insights for an account: total tokens with the cached share, top repository, top model, and top harness, above a stacked area chart of daily usage split by model](./account-insights-overview-theme-dark.avif)

If you are an account admin, you can open the page from your account page with **Insights**.

You can filter the whole page to a custom time period (the last 30 days by default) and to a subset
of repos.

## Break daily usage down by model, harness, or token type

**Usage by day** starts as a single line covering every token in the window. Switching the split
regroups the same data to answer a different question.

| Split   | What each series is                                                      |
| ------- | ------------------------------------------------------------------------ |
| Total   | One series, every token in the window.                                   |
| In/out  | Cached input, input, output, and reasoning.                              |
| Harness | One series per coding agent: `claude`, `codex`, `opencode`.              |
| Model   | One series per model, the six heaviest, with the rest folded into Other. |

Lines are easier to read when you want to see which series is growing:

![Usage by day drawn as overlaid lines, one line per model, each model's trend readable on its own](./account-insights-lines-theme-light.avif)

![Usage by day drawn as overlaid lines, one line per model, each model's trend readable on its own](./account-insights-lines-theme-dark.avif)

Turn on **Stacked** to draw the same split as stacked areas, which is better when you want to know
what a particular day was made of:

![The same chart with Stacked turned on: the models stacked into bands, so the top edge of the stack is that day's total](./account-insights-stacked-theme-light.avif)

![The same chart with Stacked turned on: the models stacked into bands, so the top edge of the stack is that day's total](./account-insights-stacked-theme-dark.avif)

Each session counts entirely on the UTC day it started, so a session that begins on Monday evening
and runs past midnight lands on Monday.

## Usage per person

![Users panel: nine members ranked by tokens, each with a bar split by harness, the exact token count, the number of sessions, and the average tokens per session](./account-insights-users-theme-light.avif)

![Users panel: nine members ranked by tokens, each with a bar split by harness, the exact token count, the number of sessions, and the average tokens per session](./account-insights-users-theme-dark.avif)

**Users** ranks the people in the account by tokens, and shows how many sessions produced that total
along with the average tokens per session.

The average is usually more interesting than the total. Someone with a large total and a small
average is running a lot of short sessions, and the opposite pattern means fewer but longer ones,
which is worth knowing before you read a big number as overspending.

## Usage per repository

![Repositories panel: repositories ranked by tokens, each with sessions, average tokens per session, linked pull requests, and average tokens per pull request](./account-insights-repositories-theme-light.avif)

![Repositories panel: repositories ranked by tokens, each with sessions, average tokens per session, linked pull requests, and average tokens per pull request](./account-insights-repositories-theme-dark.avif)

**Repositories** ranks repos the same way, and adds the pull requests linked in the window along with
the average tokens per pull request.

Keep in mind that this average includes sessions that never opened a pull request, so a repo you
mostly use for exploration looks more expensive per pull request than one where most sessions ship.
Usage that could not be attributed to a repo is collected in the **No repository** row.

## What counts as usage

- Sessions that ran through the Polygraph CLI or the
  [Polygraph plugin](/getting-started/agent-plugin), including every child agent they delegated to.
- Background work you never started a session for, as long as
  [background session capture](/features/background-session-capture) is toggled on for the account.

{% aside type="note" %}
Only sessions on Claude Code, Codex, and OpenCode are tracked. Cursor does not report a counter that
could be used for tracking.
{% /aside %}

The numbers here are tokens rather than dollars, so turning them into money means applying your
provider's per-model rates, which the model split gives you. Dollar tracking is coming and will do
that conversion for you.

## Coming soon: Semantic classification

Breakdowns per repo, person, and model are useful, but the question that usually follows is what kind
of work is spending the most.

Polygraph already knows what each session was doing, from its description, its transcript, and the
results it produced, so it can classify each one and count it later. Bug fixes, feature work,
refactors, and one-off code questions each become another way to split the same totals.

That answers the question teams actually ask: what a fix costs next to what a feature costs, whether
either is climbing, and which repos spend more on repair than on new work. The classification runs
over the sessions you have already recorded, so the answer covers your history instead of starting
from the day it ships.

---
Title: Background session capture
Description: Record agent sessions run outside Polygraph so the work behind a pull request stays reviewable even when nobody started a session for it.
URL: https://docs.trypolygraph.com/features/background-session-capture
---

Most agent work doesn't start with a Polygraph session.
Someone runs `claude` in a repo, gets a fix, opens a pull request, and closes the terminal.
The reasoning behind that pull request is gone before anyone reviews it.

Background session capture records those sessions anyway.
When the pull request lands, Polygraph attaches the transcript to it, so the change arrives with the
work that produced it.

{% youtube id="PsaAF250TGQ" title="The session you never started" /%}

## Enable background session capture

Background session capture is opt-in. Until an organization admin turns it on, only transcripts from explicitly started/resumed Polygraph sessions will be uploaded.

Go to **Account settings** > **Agent logs** and turn on **Background session capture**, then select
**Save changes**.
The setting applies to the whole organization.

Each developer also needs the [Polygraph plugin](/getting-started/agent-plugin) installed and a
signed-in CLI with an account selected. **Only sessions from repositories that are connected to the Polygraph account are ever uploaded.**

## How captures match your work

A capture on its own is a transcript with no pull request attached.
Polygraph matches it to the work it produced using three keys plus a time window:

| Key | Rule |
| --- | ---- |
| Repository | The capture and the pull request are in the same repository. |
| Branch | The branch checked out during the session matches the pull request's head branch. |
| Author | The developer who ran the session opened the pull request. |
| Time | The session overlaps the pull request's life, with 14 days of slack on each side. |

The time window runs from when the pull request was opened until it merged or closed, or until now
while it's still open.
The slack on each side means a session that started well before the branch existed, or a pull
request opened later, still matches.

A capture goes unmatched when the branch never became a pull request, when someone else opened the
pull request, or when the work happened on a detached `HEAD`.
Unmatched captures don't appear anywhere in the UI, and nobody can read their transcript.

## What you get in review

A matched capture turns a pull request you can only read as a diff into a session you can question.

Open the session from the pull request and the transcript is there: the prompts, the tool calls, the
approaches that got tried and dropped.
From there it behaves like any other session, so you can ask the agent what the diff doesn't say:

```text
What alternatives were considered, and why were they rejected?
```

For the questions worth asking and how to run an independent second opinion, see
[code reviews](/features/code-reviews).
For a worked example, see [review code with full context](/use-cases/review-code-with-full-context).

## Capturing isn't sharing

Recording a session and letting your teammates read it are two different settings.

Background session capture decides whether a transcript is recorded.
[Session log sharing settings](/security/#session-log-sharing) decide who can read it, and they apply to
captured sessions exactly as they apply to sessions you start yourself.
Turning capture on doesn't widen who sees anything.

Secret redaction also runs on captured sessions.
Each line is scanned locally and secret-shaped values are replaced before anything leaves the
machine.
For what redaction covers and where its limits are, see [security](/security).

---
Title: Code reviews
Description: Review AI-generated pull requests by asking the session behind the change about its intent and decisions, and run an adversarial review for an independent second opinion.
URL: https://docs.trypolygraph.com/features/code-reviews
---

Traditional code review tools show you diffs, so you know _what_ changed but not _why_. Each Polygraph session records the decisions that shaped the result, so you can review the reasoning behind a change, not just the code.

That gap is widest on an AI-generated pull request, which can be very large. The reasoning and the
decisions behind it are gone by the time you read the diff.

## Review a session

Open a review from the session link on a PR, or start it from the terminal:

```sh
polygraph session review <session-id> # skip session-id to start with search
```

Review mode resumes the session with the agent answering questions instead of continuing the work. Ask anything the diff doesn't tell you:

```text
What alternatives were considered, and why were they rejected?
```

```text
Which parts of this PR are you least confident about?
What was done to address them?
```

The agent answers based on the recorded session history and can point at the moment where a test failed, a constraint surfaced, or an approach was dropped. See [Review code with full context](/use-cases/review-code-with-full-context) for the questions that work well in review mode.

## Adversarial review

{% youtube id="Y-OD7EaGuEk" title="The agent that wrote it is the worst reviewer of it." /%}

For an independent second opinion, run the review in adversarial mode:

```sh
polygraph session review <session-id> --adversarial
```

Polygraph spawns one independent reviewer agent per repo in the session, then merges their reviews into a single summary. The reviewers verify the session's assumptions against the current code instead of taking the session's word for it. Everything stays read-only.

Inside an agent session, you can invoke the same flow with the `/adversarial-review` skill from the [Polygraph plugin](/getting-started/agent-plugin).

## Pass the work back

When a review finds a problem, you can post the review as usual. You can also pass the work back to the author. Because the review happened in the same session, they resume with the full context of your findings:

```sh
polygraph session resume <session-id>
```

---
Title: Cross-repo agent sessions
Description: Run one agent session across multiple repos, using some repos for context and others for active changes.
URL: https://docs.trypolygraph.com/features/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.

{% youtube id="bMBhhdw3oiY" title="Connect your repositories" /%}

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](https://metaharness.tools?utm_source=docs.trypolygraph.com): 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`](/cli/session), Polygraph asks how you want to choose repos:

{% terminal name="repo-picker" /%}

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:

{% terminal name="host-picker" /%}

```sh
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`:

```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`](/cli/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:

```text
Please add vitejs/vite repo to this session.
```

Or describe the relationship you want Polygraph to find:

```text
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`](/cli/session).

## Inspect available repos

Use [`polygraph graph`](/cli/graph) to explore the repository dependency graph before you start a session. Use [`polygraph repo list`](/cli/repo) when you need a terminal-friendly list of candidate repos and filters.

---
Title: Cross-repo PR and CI coordination
Description: Open, link, track, and verify related pull requests across repos from one Polygraph session.
URL: https://docs.trypolygraph.com/features/cross-repo-pr-and-ci-coordination
---

Cross-repo work lands as several pull requests with separate CI runs. Polygraph ties those PRs and CI runs to one session, so a change touching five repos behaves as closely as possible to a change touching one.

{% youtube id="GErvEB-uwCk" title="One change across many repositories" /%}

## Create and link PRs

The agent can push branches and open draft PRs for each repo in the session. Ask an agent to do it:

```text
Push the changes and open PRs.
```

Or use [`polygraph git push-branch`](/cli/git) and [`polygraph git create-pr`](/cli/git) when you want to drive that flow from the CLI.

![Polygraph session view: the dependency graph above a Pull requests panel listing both repos' PRs with their branches and CI status](./linked-prs-session-view.avif)

Polygraph pushes branches and opens PRs through its own integration, not the GitHub CLI, for efficiency and security reasons.

Draft PRs keep related changes reviewable before the full cross-repo set is ready. Ask the agent to mark them ready for review:

```text
Mark the created PRs as ready for review.
```

Or use [`polygraph git mark-pr-ready`](/cli/git) from the CLI.

Polygraph syncs the status of each PR in the session, so you get the same view from the Polygraph web app or from an agent using the Polygraph CLI.

## Associate existing PRs

Not every PR has to be created by Polygraph. If a PR already exists, ask the agent to attach it to the session:

```text
Associate https://github.com/myorg/backend/pull/482 with this session.
```

Or use [`polygraph git associate-pr`](/cli/git) from the CLI. That keeps manual PRs, agent-created PRs, and follow-up PRs in the same cross-repo record.

## Update PR metadata

A PR must be associated with the session before you update its title, body, labels, or assignees.
Use the [`update_pr` MCP tool](/mcp-tools/update_pr) from an agent, or run [`polygraph git update-pr`](/cli/git) directly.
Provide at least one metadata field.
Polygraph leaves omitted fields unchanged.

This MCP request clears the user-authored body and adds a label without changing other labels:

```json
{
  "sessionId": "<session-id>",
  "prUrl": "https://github.com/myorg/backend/pull/482",
  "body": "",
  "labels": {
    "mode": "add",
    "values": ["ready-for-review"]
  }
}
```

An empty body clears the user-authored text, but Polygraph preserves its footer.
For labels and assignees, `set` replaces the whole collection, so it can remove values that another person added.
Use `add` or `remove` to preserve unrelated values.
An empty `set` collection clears all labels or assignees.

Run the CLI directly when you already know the session and PR URL:

```sh
polygraph git update-pr \
  --session <session-id> \
  --pr-url https://github.com/myorg/backend/pull/482 \
  --body '' \
  --add-label ready-for-review \
  --remove-assignee former-owner \
  --json
```

Repeat an add, remove, or set flag to pass more than one value.
Use `--clear-labels` or `--clear-assignees` to clear a collection.

## Track CI across repos

Ask the agent to get CI green and it treats the session's CI runs as one thing. When one repo fails, the agent decides whether the fix is local to that repo, whether the shared change breaks a downstream consumer, or whether the plan itself needs to change.

```text
Wait for CI for this Polygraph session and address any failures.
```

## Test downstream repos before release

{% youtube id="w_AO9jNh0lM" title="Test the unreleased package in the apps that use it" /%}

Many cross-repo changes involve an artifact published by one repo and consumed by another. Polygraph handles this automatically: you validate downstream before anything lands, with no registry round-trip.

For example, change a design system, install the unpublished version into an application that depends on it, and run the application's CI before the design-system PR merges. For package-based validation, the agent can use [`pack_and_copy`](/mcp-tools/pack_and_copy) to pack the publisher and install the tarball into the consumer repo inside the session.

```text
Can you pack and copy <package-name> package and update <app-name> to use it?
```

This is the validation loop a monorepo gives you, applied across separate repos.

## Review the whole change

Each linked PR carries session context. Reviewers can open the session to see the repos involved, a description of the work, sibling PRs, CI state, and the agent traces.

You can perform an adversarial review of the whole change to make sure the cross-repo work holds together:

```text
1. Search Polygraph sessions for relevant work and rank up to three useful past sessions.
2. Run polygraph:session-debrief on those sessions and wait for the consolidated debrief.
3. Run polygraph:adversarial-review on the current session. Pass the completed debrief, current session description, and repository plans to every reviewer. Have them verify the debrief's assumptions against the current code.
Keep everything read-only and return one consolidated review.
```

---
Title: Institutional memory
Description: Search past sessions, reference them as context for new work, and debrief them into structured summaries your agent can build on.
URL: https://docs.trypolygraph.com/features/institutional-memory
---

Agents have no episodic memory, so the reasoning and decisions behind a feature, worth more than the git history itself, vanish the moment the session that built it ends. It's like a coworker who built half the system, then left for another job, leaving you to reverse-engineer what they were thinking.

This means that agents used in real projects aren't aware of the larger context and the best practices, and as a result they create slop. This is because agents lack institutional memory. Whatever memory is available, however rudimentary, is local to each developer. A lot of the problems with agents in real organizations are the result of that.

Polygraph gives your agent episodic memory. Every code change, every session is a recorded episode: shared [agent transcripts](/security#session-log-sharing), session descriptions, repos, branches, pull requests, and linked issues. It creates a rich institutional memory that provides every agent with the context it needs to be effective.

## AGENTS.md and memory

The memory a coding agent has today is mostly semantic: facts about the codebase, distilled by hand.

| Mechanism | What it holds | Scope |
| --------- | ------------- | ----- |
| `CLAUDE.md`, `AGENTS.md` | conventions and standing instructions, maintained by hand | one repo, plus a personal global file |
| Built-in agent memory | facts and preferences the agent saves as you work | one developer, on one machine or account |
| A notes folder or an MCP notes server | whatever that developer decided to write down | one developer, for as long as they keep it current |

Distilled facts rot. Code doesn't. A note describing how this codebase handles timeouts is worth
less than the change that actually handled one, and it fails badly once it goes stale. The agent
doesn't get slightly worse, it goes the wrong way with full confidence.

Sessions record what happened rather than what someone summarized afterwards. Your agent references
or resumes the work itself and reads the ground truth from the repos, branches, and pull requests it
left behind.

## Session graph

You can view it visually by looking at the session graph on your org page.

![Polygraph session graph: a timeline of the organization's sessions grouped by day, with dashed edges linking a selected session to the earlier sessions it builds on, and a detail card showing the session name, author, and repo](./session-graph.avif)

## Search sessions

Ask your agent to find relevant sessions:

```text
Can you search for sessions that dealt with Stripe webhook retries?
```

The agent searches your organization's sessions and reports the matches, each with its PRs and a one-line summary. You can also search interactively from the terminal:

```sh
polygraph session search
```

Search also works backwards from the code: trace a change to the session that produced it. Find the commit with `git blame`, then ask:

```text
Can you search for the session that made this change? 4f9c21a
```

See [Find and reuse prior work](/use-cases/find-and-reuse-prior-work) for the full workflow.

{% youtube id="JsslL1LaEO8" title="Understand the why, not just the what" /%}

## Reference another session

You can skip the search when you know the session.

![Referencing a prior session in Claude Code: typing @ surfaces the Polygraph session resource, here the update-docs-before-launch session, to pull in as context](./reference-session.avif)

Use a reference when the original work is done, but its context still matters. For example, if an issue is discovered weeks after some work landed, start a new session and reference the original session. The new agent can inspect the prior plan, decisions, comments, pull requests, and repo state without re-deriving them from scratch.

To reference a session, attach it through MCP resources if your agent supports them (using the "@" symbol in Claude Code). You can also mention the session ID directly:

```text
Include the context of session <session-id> and figure out why this issue occurs.
```

Referencing extracts the relevant information for the new task:

- For a high-level question, the session summary may be enough.
- For a detailed investigation, Polygraph can inspect pull request descriptions, available agent logs, and code.

Polygraph records referenced sessions, which updates the session graph.

{% youtube id="Kv9jdGoIl3o" title="Build your work from previous sessions" /%}

## Debrief past sessions

Although the workflows above are useful, a lot of the time you simply don't know what to search for. You want Polygraph to find what is relevant and provide the needed information to your current agent.

The `session-debrief` skill analyzes the available raw logs of past sessions and produces a structured, rank-ordered debrief for the task at hand: what was attempted, what worked, what failed, and which assumptions to re-verify. You can trigger it with a prompt like this:

```text
1. Search Polygraph sessions for relevant work and rank up to three useful past sessions.
2. Run polygraph:session-debrief on those sessions and wait for the consolidated debrief.
3. Use the debrief to plan the change, and re-verify its assumptions against the current code.
```

The debrief runs read-only against the recorded sessions, so it never disturbs the original work.

## Learn more

You can learn more about why episodic memory works so well for code in [Agentic Memory: Why Code Is Fundamentally Different](https://nx.dev/blog/agentic-memory-why-code-is-fundamentally-different).

---
Title: OSS repo integration
Description: Bring public open source repos into Polygraph sessions for repros, upstream debugging, and integration validation.
URL: https://docs.trypolygraph.com/features/oss-repo-integration
---

Polygraph has access to every public repository on GitHub and knows how they relate to each other. Your private repos, plus the open source repos they depend on, form your Polygraph.

![Polygraph repository graph: the OSS repo vitest-dev/vitest linked to the owned repos that depend on it, with a detail panel showing it as an OSS repository, its stars, and how many repos use it](./oss-dependency-graph.avif)

Any public repo can join a session alongside the repos you own. That makes OSS repros, upstream libraries, and downstream consumers part of the same working context. This is something even a monorepo cannot give you. Open source code can never live inside it.

## When to use it

Use OSS repo integration when:

- A bug report includes a public reproduction repo
- You need to validate an unpublished fix against a public consumer
- Your code depends on a public project, and you need to provide more context to your agents

The last case is very common. You might be migrating your repositories from one version of a project to a newer one. Having the repo in place gives an agent a lot more context about what changed and can help make the migration autonomous. You might also hit an issue with a third-party library. Adding the repo can help your agent understand how it works (much better than the documentation can).

## Add an OSS repo to a session

{% youtube id="0sPWX2zMJVw" title="Your graph does not stop at your own repositories" /%}

Mention the repo by URL or by the package it publishes, and ask the agent to add it.

```text
Please add @opentui/core to this session and check if I use the API correctly.
```

For a full maintainer workflow, see [For OSS developers](/oss/for-oss-developers).

## Validate package changes

For publisher-consumer validation, the agent can use [`pack_and_copy`](/mcp-tools/pack_and_copy) to pack a changed package and install the tarball into a consumer repo inside the session, with no registry round-trip.

That gives you an end-to-end loop for OSS repros: reproduce the bug, change the publisher, install the unpublished package into the repro, rerun the failing command, and open the PR in the repo you own.

---
Title: Resuming and handoff
Description: Sessions are durable. Resume a Claude Code or Codex session tomorrow, continue it on another machine, hand it to a teammate, or finish it with a different agent.
URL: https://docs.trypolygraph.com/features/resuming-and-handoff
---

Picture a team working together. One member does some work, then hands it off to another.
Today people serialize that by hand. A `/handoff` skill writes a `HANDOFF.md`, and the next person
reads the markdown, checks out the branch, and reconstructs the rest from memory.

Polygraph captures the state of the world along with it. Resuming isn't a copy-paste into the agent's memory. It is a time machine that drops you exactly where the original author stopped. The agent can inspect the repos, follow the pull requests and issues, and run commands with the old context available.

This applies to any work done by anyone in the organization, no matter how cross-cutting. Every session feeds one shared memory, so your agent builds on what the whole team did.

{% youtube id="rgl2NXaU_sM" title="Start a session, allow to resume it by others" /%}

## Resume a session

Resume a session when you want to continue the same work, whether you started it in Claude Code,
Codex, or OpenCode.
You can resume a session you created or a session someone else handed to you.

```sh
polygraph session resume <session-id>
```

You can omit the ID and select a session from the list:

```sh
polygraph session resume
```

When you resume, Polygraph reconstructs the session state as closely as possible: the repos are set up at the relevant SHAs, along with the branches and available agent context.
Agent transcripts are included only when [session log sharing](/security#session-log-sharing) makes them visible.

## Share a session with someone else

A handoff is a resume done by someone else. Share the session ID or URL, and a teammate picks up exactly where you stopped, on their machine, with the context available to them.

Resuming someone else's session doesn't transfer authorship of it, and a session is visible only to
people who can read every repo it uses.
See [what sessions you can see](/security#what-sessions-you-can-see).

## Continue on another machine

Resuming works across machines and operating systems.
Start the work on one machine and pick it up on another, because Polygraph reconstructs the working
copies wherever you resume rather than reaching back to the machine you started on.

## Switch from Claude Code to Codex

A session isn't tied to the agent that started it.
Start the work in Claude Code and finish it in Codex, or the reverse, by choosing the agent when you
resume:

```sh
polygraph session resume <session-id> --agent codex
```

Different people on the same session can use different agents.

Resuming with the same agent continues its existing conversation. A different agent launches fresh with a startup prompt that re-establishes the session context. The choice applies to that resume only and doesn't change the session's stored agent.

### Which agent resumes the session

Sessions work across agents, so resuming has to pick one. Polygraph resolves the agent in this order:

1. **An explicit `--agent <type>` always wins.** Pass `claude`, `codex`, or `opencode` to switch directly, with no prompt.
2. **A bare `--agent` (no value) always opens the picker**, with the session's stored agent marked as current and pre-selected.
3. **Without the flag**, Polygraph compares the session's stored agent with your configured [default agent](/cli/config#agenttype):
   - If they match, the stored agent is used silently.
   - If they differ, the picker opens with the stored agent pre-selected, along with a note naming both (for example: "This session last ran under claude. Your configured default agent is codex.").
   - A stored agent with no configured default opens the picker with the stored agent pre-selected.
   - No stored agent uses the configured default silently. With no default either, Polygraph prompts.

The same rules apply when Polygraph reconstructs a session on another machine. `polygraph session start` follows the same idea: a configured default agent launches without asking, and no default means the session prompts for an agent.

---
Title: Using multiple agents
Description: A session is a team of agents. A parent agent plans the work, child agents execute it per repo, and roles let several agents work in the same repo at once.
URL: https://docs.trypolygraph.com/features/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:

```sh
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`:

```sh
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](/features/resuming-and-handoff) 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.

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

This is how [adversarial reviews](/features/code-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.

---
Title: Agent plugin and skills
Description: Install the Polygraph plugin for your agent and learn what skills it ships.
URL: https://docs.trypolygraph.com/getting-started/agent-plugin
---

Polygraph ships a plugin for Claude Code, Codex, and OpenCode (more in the works). The plugin gives your agent the Polygraph MCP tools and a set of skills for cross-repo work.

## Install

The easiest way to install it is the config editor:

```sh
polygraph config
```

Each agent row shows a plugin status chip. Press `Enter` (or `i`) on the plugin item to install or update the plugin for that agent — installing is the plugin row's primary action.

For Codex, you can also run the installer directly:

```sh
npx @polygraph/codex-plugin
```

## What the plugin provides

- The Polygraph MCP server, which exposes the [MCP tools](/mcp-tools) agents use to drive sessions.
- Skills that teach your agent Polygraph workflows.

## Skills

| Skill | What it does |
| ----- | ------------ |
| `polygraph` | Guidance for multi-repo coordination: sessions, child-agent delegation, branches, PRs, and CI. Triggers automatically on cross-repo work; invoke it directly with `/polygraph`. |
| `adversarial-review` | Independent second-opinion review of a session's work. Spawns one reviewer agent per repo under the `reviewer` role (via the `role` parameter / `--role` flag), then merges the reviews into a single summary. Invoke it with `/adversarial-review`. |
| `await-polygraph-ci` | Waits for CI to settle across all repos in a session, reports results, and investigates failures. |
| `get-latest-ci` | Fetches the latest CI pipeline execution for the current branch. |
| `pack-and-copy` | Packs a publisher package and installs the tarballs into consumer repos, so consumer CI can validate an unmerged change. |

---
Title: Install the Polygraph CLI
URL: https://docs.trypolygraph.com/getting-started/installation
---

The Polygraph CLI ships as a standalone binary for macOS and Linux.
Neither Node.js nor npm is required to run it.

## Install on macOS and Linux

```sh
curl -fsSL https://app.trypolygraph.com/install.sh | sh
```

The script downloads the binary for your platform, verifies its checksum, installs it under `~/.polygraph`,
and links `polygraph` into `~/.local/bin`.
It never asks for `sudo`.

## Install with Homebrew

```sh
brew install nrwl/tap/polygraph
```

The formula downloads the same standalone binary the script does.

## Install on Windows

Windows has no standalone binary yet.
Run the PowerShell installer:

```powershell
irm https://app.trypolygraph.com/install.ps1 | iex
```

The PowerShell installer uses npm under the hood, so Node.js 22.13.0 or newer is required on Windows
(npm 10 or newer ships with it).
To install by hand instead, run npm yourself:

```sh
npm install -g polygraph
```

## Upgrade the CLI

Rerun the install command to move to the current release:

```sh
curl -fsSL https://app.trypolygraph.com/install.sh | sh
```

If you installed with Homebrew, upgrade through brew instead:

```sh
brew upgrade polygraph
```

## Put the CLI on your PATH

The script links `polygraph` into `~/.local/bin`.
Most setups already have that directory on the PATH.
When it is missing, the script prints the line to add to your shell profile:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

## Install somewhere else

The script installs to `~/.polygraph`.
Set `POLYGRAPH_INSTALL_DIR` to relocate the install root:

```sh
curl -fsSL https://app.trypolygraph.com/install.sh | POLYGRAPH_INSTALL_DIR=/opt/polygraph sh
```

---
Title: Quickstart
URL: https://docs.trypolygraph.com/getting-started/quickstart
---

Install the CLI, sign in, and start your first session.

When you create a new Polygraph account, we recommend going through the built-in demo experience. It showcases the product and helps you get familiar with its features before you point it at your own repos.

## Install

On macOS and Linux, install the standalone binary:

```sh
curl -fsSL https://app.trypolygraph.com/install.sh | sh
```

For the Homebrew tap and for Windows, see [install the Polygraph CLI](/getting-started/installation).

## Run the CLI

Start with the interactive CLI. It guides you through sign-in, account selection, and session setup.

```sh
polygraph
```

Polygraph indexes every repo you have access to and stitches them into one graph. Your agent works against that graph instead of one repo at a time.

## Check your account

After sign-in, confirm the effective account before starting a session.

```sh
polygraph whoami
```

## Sign in manually

If you want to run the sign-in flow directly, use the auth command.

```sh
polygraph auth login
```

Polygraph uses an OAuth device flow for CLI sign-in. The CLI opens or prints a
browser approval URL and code:

```text
> polygraph auth login

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

Opening your browser to authorize Polygraph CLI...

If your browser does not open, visit:
  https://app.trypolygraph.com/profile/oauth?user_code=XXXX-YYYY
Code: XXXX-YYYY
```

Compare the code in your terminal with the code shown in the browser, then
approve the request while signed in to Polygraph.

## Start a session

Work happens in sessions. Start one by running the CLI:

```sh
polygraph session start
```

Or by invoking the Polygraph skill within your existing agent session:

```text
/polygraph create a session and add all repos that depend on this one
```

Pick the repos up front, or describe the task and let Polygraph find them.

## Add repos as you go

A session isn't locked to the repos you started with. Prompt the agent to pull in another repo:

```text
Please add vitejs/vite repo to this session.
```

Whatever you can read, your agent can read: any repo you have access to (organization or open source).

## Search and inspect sessions

```sh
polygraph session search
```

Show details such as URL, folder, and status for a session.

```sh
polygraph session show <session-id>
```

## Resume and review sessions

You can resume any session by any developer in your organization. When resuming, Polygraph reconstructs the state of the session on your machine: the repos are set up at the relevant SHAs, along with the relevant logs. You can start the work on one machine and continue on another, or start the work using Claude and finish it using Codex, without any friction.

```sh
polygraph session resume <session-id> # skip session-id to start with search
```

The exact same mechanism can be used to review other people's code.

```sh
polygraph session review <session-id> # skip session-id to start with search
```

You can also instruct Polygraph to perform an adversarial review.

```sh
polygraph session review <session-id> --adversarial
```

## What next

Pick a workflow that matches what you want to do.

{% cardgrid %}

{% linkcard title="Update backend and frontend" description="Ship one feature across a backend API and the frontend that calls it, as if they were one monorepo." href="/use-cases/update-backend-and-frontend" /%}

{% linkcard title="Review code with full context" description="Review the reasoning behind an agent-written PR by asking the session, not just reading the diff." href="/use-cases/review-code-with-full-context" /%}

{% /cardgrid %}

---
Title: Terminals
Description: Run Polygraph sessions in a terminal multiplexer to watch all child agent logs side by side.
URL: https://docs.trypolygraph.com/getting-started/terminals
---

Polygraph coordinates work across multiple repositories by spawning one child agent per repo. Running a session inside a modern terminal or terminal multiplexer opens each child agent in its own pane, so you can watch all of their live logs side by side.

Polygraph detects and configures your terminal automatically, but you can pass the `--multiplexer` flag to override the behavior.

## Supported multiplexers

Polygraph supports the following choices for `--multiplexer`:

| Choice | Description |
|--------|-------------|
| `auto` | Default. Detects the best available option for your environment. |
| `tmux` | tmux |
| `iterm2` | iTerm2 (macOS) |
| `kitty` | kitty terminal |
| `ghostty` | Ghostty terminal |
| `cmux` | cmux |
| `zellij` | Zellij |
| `herdr` | herdr |
| `windows-terminal` | Windows Terminal |
| `none` | Disable multiplexer support. |

## Enable a multiplexer

### On a new session

Pass `--multiplexer` (alias `-m`) when starting a session:

```sh
polygraph session start --multiplexer <choice>
```

### On an existing session

To bring an existing session into a multiplexer, resume it with the flag:

```sh
polygraph session resume --multiplexer <choice>
```

This is how you add multiplexer support to a session that was started without one.

### As a default

Set the default multiplexer in the [`polygraph config`](/cli/config) editor: the
**Multiplexer** setting lives in the General section, and `Enter` or `Space` cycles
through the choices. You can also set the key in `$HOME/.polygraph/config.json`
directly:

```json
{
  "multiplexer": "tmux"
}
```

When the setting is unset, Polygraph asks at session start. In general, you don't
need to set it — `auto` detects your terminal automatically.

## View child agent logs without a multiplexer

When no multiplexer is active, attach to a single child agent's live logs with:

```sh
polygraph agent attach -s <sessionId> -r <repo>
```

---
Title: MCP tools
Description: Reference for the MCP tools that Claude (and other agents) use to drive Polygraph sessions.
URL: https://docs.trypolygraph.com/mcp-tools
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

{% aside type="note" %}
These pages are generated from `data/mcp-tools.json`, a hand-maintained manifest of tool registrations in [nrwl/polygraph-mcp](https://github.com/nrwl/polygraph-mcp). To refresh, update the manifest from the tool registrations, then run `pnpm sync:mcp-ref`.
{% /aside %}

AI agents drive Polygraph through MCP tools. Each tool maps to one operation in the session lifecycle - discover workspaces, delegate work, push branches, monitor progress.

## Discovery

- [`list_accounts`](/mcp-tools/list_accounts) - List organizations the current user belongs to.
- [`list_repos`](/mcp-tools/list_repos) - Find candidate repositories for a Polygraph session.
- [`list_sessions`](/mcp-tools/list_sessions) - List Polygraph sessions.
- [`search_sessions`](/mcp-tools/search_sessions) - Search Polygraph sessions by free-text query, or resolve a commit sha (full or partial) to the session(s) linked to that commit.
- [`whoami`](/mcp-tools/whoami) - Show the current Polygraph authentication and selected organization state.

## Execution

- [`add_repo`](/mcp-tools/add_repo) - Directly add specific repositories to a running Polygraph session by slug, name, owner/repo full name, or repository id.
- [`allow_agent`](/mcp-tools/allow_agent) - Grant a child agent's pending permission-required request.
- [`deny_agent`](/mcp-tools/deny_agent) - Deny a child agent's pending permission-required request.
- [`git_fetch`](/mcp-tools/git_fetch) - Deepen a Polygraph session repository's git history.
- [`pack_and_copy`](/mcp-tools/pack_and_copy) - Pack publisher packages and install the tarballs into consumer repos.
- [`session_intro`](/mcp-tools/session_intro) - Render the Polygraph session welcome card (markdown) for a session.
- [`show_agent`](/mcp-tools/show_agent) - Get the status and recent output of the specified repo's child agent in a Polygraph session from the configured Polygraph URL.
- [`spawn_agent`](/mcp-tools/spawn_agent) - Delegate a task to a child AI agent in a dependent repository.
- [`start_session`](/mcp-tools/start_session) - Initialize Polygraph for the selected repos.
- [`stop_agent`](/mcp-tools/stop_agent) - Stop an in-progress child agent in a Polygraph session.

## Publishing

- [`associate_pr`](/mcp-tools/associate_pr) - Associate an existing pull request with a Polygraph session.
- [`create_pr`](/mcp-tools/create_pr) - Create draft pull requests for one or more repositories in a Polygraph session.
- [`delete_artifact`](/mcp-tools/delete_artifact) - Permanently delete an artifact from a Polygraph session by name.
- [`link_reference`](/mcp-tools/link_reference) - Link an external reference to a session.
- [`mark_pr_ready`](/mcp-tools/mark_pr_ready) - Mark specified draft pull requests in a Polygraph session as ready for review.
- [`push_branch`](/mcp-tools/push_branch) - Push a local git branch to the remote repository.
- [`update_pr`](/mcp-tools/update_pr) - Update a pull request's title, body, labels, or assignees through Polygraph.
- [`update_session`](/mcp-tools/update_session) - Update a Polygraph session title and/or user-facing description timeline.
- [`upload_artifact`](/mcp-tools/upload_artifact) - Attach an artifact (plan document, image, or file) to a Polygraph session.

## Monitoring

- [`get_ci_logs`](/mcp-tools/get_ci_logs) - Retrieves the plain-text log for a specific CI job and saves it to a local file.
- [`get_session_logs`](/mcp-tools/get_session_logs) - Retrieve the parent agent transcript for a Polygraph session as JSON.
- [`list_artifacts`](/mcp-tools/list_artifacts) - List the artifacts attached to a Polygraph session, including their names, kinds, and versions.
- [`show_session`](/mcp-tools/show_session) - Get the specified Polygraph session.

## Misc

- [`archive_session`](/mcp-tools/archive_session) - Archive a Polygraph session.
- [`login`](/mcp-tools/login) - Authenticate Polygraph by running the CLI login flow, which opens a browser.
- [`logout`](/mcp-tools/logout) - Remove stored Polygraph credentials from local config.
- [`select_account`](/mcp-tools/select_account) - Select an organization to operate on.

## Resources

Besides tools, the MCP server exposes resources that agents can attach as context:

- `polygraph://repos/<repoId>` - one resource per organization repo (JSON).
- `polygraph://sessions/<sessionId>` - sessions from the last 30 days (JSON), so a prior session can be attached as context for new work.

---
Title: add_repo
Description: Directly add specific repositories to a running Polygraph session by slug, name, owner/repo full name, or repository id.
URL: https://docs.trypolygraph.com/mcp-tools/add_repo
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Directly add specific repositories to a running Polygraph session by slug, name, owner/repo full name, or repository id.

Use list_repos only when you need to discover or choose repositories.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repoIds` | `array` | yes | Specific repository refs to add directly to the session. Accepts a slug, name, owner/repo full name, or repository id. Do not call list_repos when the user already provided the repository ref; use list_repos only when you need to discover or choose repositories. |

---
Title: allow_agent
Description: Grant a child agent's pending permission-required request.
URL: https://docs.trypolygraph.com/mcp-tools/allow_agent
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Grant a child agent's pending permission-required request.

Use this when show_agent reports a task in 'permission-required' state and you want to allow the requested action. 'one-time' applies to this single request; 'session' is remembered for equivalent later requests within the child's session.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID of the child agent holding the permission gate |
| `scope` | `enum` | yes | 'one-time' applies to this single request; 'session' is remembered for equivalent later requests within the child's session. |
| `reason` | `string` | no | Optional reason for allowing the request |
| `role` | `string` | no | Optional role identifying which of the repo's agents to target; omit for the default agent. |

---
Title: archive_session
Description: Archive a Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/archive_session
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Archive a Polygraph session.

Once archived, no further modifications, new PRs, or status changes can be made.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `clean` | `boolean` | no | Remove local session worktrees after archiving the session. |

---
Title: associate_pr
Description: Associate an existing pull request with a Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/associate_pr
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Associate an existing pull request with a Polygraph session.

Use this to link PRs that were created outside of Polygraph (e.g., manually or by CI) to the current session. Provide either a prUrl or a branch name.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `prUrl` | `string` | no | URL of an existing pull request to associate with the session |
| `branch` | `string` | no | Branch name to find and associate PRs for. Used when prUrl is not provided. In a multi-repo session, requires `repo` to disambiguate which repository the branch belongs to. |
| `repo` | `string` | no | Repository full name (owner/repo) or repository id identifying which session repository this PR belongs to. Required when using `branch` in a multi-repo session. Optional (and ignored) when `prUrl` is provided, since the repository is parsed from the URL. |
| `description` | `string` | yes | A session description is required. |
| `agentSessionId` | `string` | no | The AI agent session ID. Can be used to resume the session later. Resuming is reconnecting to restore context only. After you resume, do not make any changes until the user explicitly asks for changes. |

---
Title: create_pr
Description: Create draft pull requests for one or more repositories in a Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/create_pr
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Create draft pull requests for one or more repositories in a Polygraph session.

Each PR includes session metadata linking it to related PRs across repos. Branches must be pushed first using push_branch.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `prs` | `array` | yes | Array of PR specifications to create. Each PR object has: owner (string, required — GitHub repository owner), repo (string, required — GitHub repository name), title (string, required — PR title), body (string, required — PR description body; session metadata appended automatically), branch (string, required — branch name that was pushed), baseBranch (string, optional — target base branch for the pull request), targetRepository (string, optional — target repo identifier for fork PRs). |
| `description` | `string` | yes | A session description is required. |
| `agentSessionId` | `string` | no | The AI agent session ID. Can be used to resume the session later. Resuming is reconnecting to restore context only. After you resume, do not make any changes until the user explicitly asks for changes. |

---
Title: delete_artifact
Description: Permanently delete an artifact from a Polygraph session by name.
URL: https://docs.trypolygraph.com/mcp-tools/delete_artifact
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Permanently delete an artifact from a Polygraph session by name.

This removes the artifact and ALL of its versions, and cannot be undone. Returns the session's remaining artifacts. Use list_artifacts first if you are unsure of the exact name.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `name` | `string` | yes | The name of the artifact to delete. |

---
Title: deny_agent
Description: Deny a child agent's pending permission-required request.
URL: https://docs.trypolygraph.com/mcp-tools/deny_agent
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Deny a child agent's pending permission-required request.

Use this when show_agent reports a task in 'permission-required' state and you want to deny the requested action — the child continues without performing it.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID of the child agent holding the permission gate |
| `reason` | `string` | no | Optional reason for denying the request |
| `role` | `string` | no | Optional role identifying which of the repo's agents to target; omit for the default agent. |

---
Title: get_ci_logs
Description: Retrieves the plain-text log for a specific CI job and saves it to a local file.
URL: https://docs.trypolygraph.com/mcp-tools/get_ci_logs
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Retrieves the plain-text log for a specific CI job and saves it to a local file.

Use jobId from CI run data. Only call for jobs where the run has completed. Returns the file path; use the Read tool to examine the log content.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repoId` | `string` | yes | The repo ID (MongoDB ObjectId hex string) |
| `jobId` | `number` | yes | The GitHub Actions job ID (from the jobs array in CI run data) |

---
Title: get_session_logs
Description: Retrieve the parent agent transcript for a Polygraph session as JSON.
URL: https://docs.trypolygraph.com/mcp-tools/get_session_logs
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Retrieve the parent agent transcript for a Polygraph session as JSON.

This tool returns parent transcript entries only and never requests child repository logs. By default it preserves and returns the complete parent transcript; pass tail and/or page only when a paginated response is desired.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `tail` | `number` | no | Number of parent transcript entries per page. Omit both tail and page to return the complete parent transcript. |
| `page` | `number` | no | 1-based page of parent transcript entries, where page 1 is newest. Supplying page without tail uses the CLI page size default of 20; omit both for the complete transcript. |

---
Title: git_fetch
Description: Deepen a Polygraph session repository's git history.
URL: https://docs.trypolygraph.com/mcp-tools/git_fetch
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Deepen a Polygraph session repository's git history.

Session repos are cloned shallow (a single commit), so git operations that need older history fail with errors like "bad object", "fatal: ... shallow" or a missing commit — for example reverting an older commit, or running git log, git blame, or git merge-base beyond the newest commit. Call this tool to fetch the missing history, then retry the git operation. By default it fetches the full history of the repo's default branch (plus the current branch when it exists on the remote); pass depth to bound the fetch, or refs to add extra branches. Safe to call redundantly — a repository that already has complete history reports success without doing any work. Requires an active Polygraph session.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID whose session clone should be deepened |
| `depth` | `number` | no | Fetch only the newest N commits instead of full history |
| `refs` | `array` | no | Additional remote branch names to fetch |

---
Title: link_reference
Description: Link an external reference to a session.
URL: https://docs.trypolygraph.com/mcp-tools/link_reference
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Link an external reference to a session.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `reference` | `object` | yes | External reference to link to a session. Discriminated union on `type`: "session" (requires url, label, and sessionId — the linked Polygraph session ID or a supported Polygraph app session URL, normalized to the session ID before calling Ocean), "github_pr" (url, label), "github_issue" (url, label), or "linear_ticket" (url, label). |

---
Title: list_accounts
Description: List organizations the current user belongs to.
URL: https://docs.trypolygraph.com/mcp-tools/list_accounts
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

List organizations the current user belongs to.

Returns an array of organizations with their IDs and names. Use this to discover available accounts before calling select_account.

## Arguments

Arguments are not yet imported into this manifest. Refer to the Zod schema in the [polygraph-mcp repo](https://github.com/nrwl/polygraph-mcp) for the authoritative shape.

---
Title: list_artifacts
Description: List the artifacts attached to a Polygraph session, including their names, kinds, and versions.
URL: https://docs.trypolygraph.com/mcp-tools/list_artifacts
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

List the artifacts attached to a Polygraph session, including their names, kinds, and versions.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |

---
Title: list_repos
Description: Find candidate repositories for a Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/list_repos
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Find candidate repositories for a Polygraph session.

Use before start_session to see which repos are available and optionally select a subset via selectedRepoIds. Results are capped at 50 repos; pass force: true to return more.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `connectedTo` | `string` | no | Repository ID, name, or full name (e.g. "nrwl/ocean"). Pair with connectionType. |
| `connectionType` | `enum` | no | Which connections to include relative to connectedTo (requires connectedTo): directly-upstream, directly-downstream, directly-both (default), upstream, downstream, both. |
| `publishedPackages` | `array` | no | Package names a candidate repository publishes. |
| `consumedPackages` | `array` | no | Package names a candidate repository consumes. |
| `publishedApis` | `array` | no | API paths a candidate repository serves. |
| `consumedApis` | `array` | no | API paths a candidate repository consumes. |
| `nameFilter` | `array` | no | Repository name patterns (e.g. "ocean", "nrwl/*"). |
| `semanticQuery` | `string` | no | Free-text description of the repositories you want. |
| `force` | `boolean` | no | Bypass the 50-repo cap. By default, results above the cap are suppressed; set true to return them anyway. |

---
Title: list_sessions
Description: List Polygraph sessions.
URL: https://docs.trypolygraph.com/mcp-tools/list_sessions
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

List Polygraph sessions.

By default, applies recommended filters: only active (open) sessions created by you. Set recommendedFilters: false to return all sessions across every status and author.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `recommendedFilters` | `boolean` | no | When true (default), only shows active (open) sessions created by you. Set to false to return all sessions across every status and author. |

---
Title: login
Description: Authenticate Polygraph by running the CLI login flow, which opens a browser.
URL: https://docs.trypolygraph.com/mcp-tools/login
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Authenticate Polygraph by running the CLI login flow, which opens a browser.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `insecureStorage` | `boolean` | no | Store the OAuth refresh token in a file instead of the OS keychain. Only pass this when the user explicitly asks for it, on machines whose keychain is unavailable or locked. Never select it on the user behalf. |

---
Title: logout
Description: Remove stored Polygraph credentials from local config.
URL: https://docs.trypolygraph.com/mcp-tools/logout
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Remove stored Polygraph credentials from local config.

## Arguments

Arguments are not yet imported into this manifest. Refer to the Zod schema in the [polygraph-mcp repo](https://github.com/nrwl/polygraph-mcp) for the authoritative shape.

---
Title: mark_pr_ready
Description: Mark specified draft pull requests in a Polygraph session as ready for review.
URL: https://docs.trypolygraph.com/mcp-tools/mark_pr_ready
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Mark specified draft pull requests in a Polygraph session as ready for review.

Provide PR URLs to transition from DRAFT to OPEN status. Use after cross-repo changes are verified.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `prUrls` | `array` | yes | URLs of the pull requests to mark as ready for review |
| `agentSessionId` | `string` | no | The AI agent session ID. Can be used to resume the session later. Resuming is reconnecting to restore context only. After you resume, do not make any changes until the user explicitly asks for changes. |

---
Title: pack_and_copy
Description: Pack publisher packages and install the tarballs into consumer repos.
URL: https://docs.trypolygraph.com/mcp-tools/pack_and_copy
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Pack publisher packages and install the tarballs into consumer repos.

Wraps `polygraph _pack-and-copy` for pre-release validation of a publisher change against downstream consumers.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `pairs` | `array` | yes | Publisher-consumer path pairs. Each publisher tarball will be packed and installed into the corresponding consumer. Each pair is an object with publisherPath (path to the publisher package directory — the package to build and pack) and consumerPath (path to the consumer project directory where the packed tarball should be installed), both required strings. |
| `runScripts` | `boolean` | no | Enable npm lifecycle scripts during packing. Off by default for security. |

---
Title: push_branch
Description: Push a local git branch to the remote repository.
URL: https://docs.trypolygraph.com/mcp-tools/push_branch
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Push a local git branch to the remote repository.

Use this after making commits in a delegated repository, before creating a PR. Requires an active Polygraph session. A session description is required.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID to push from |
| `branch` | `string` | yes | Branch name to push to remote (e.g., "feature/my-changes") |
| `description` | `string` | yes | A session description is required. Pass the literal value 'none' to explicitly skip updating the session description. |

---
Title: search_sessions
Description: Search Polygraph sessions by free-text query, or resolve a commit sha (full or partial) to the session(s) linked to that commit.
URL: https://docs.trypolygraph.com/mcp-tools/search_sessions
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Search Polygraph sessions by free-text query, or resolve a commit sha (full or partial) to the session(s) linked to that commit.

Provide exactly one of query or sha. Returns the matching sessions as a JSON array.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `query` | `string` | no | Free-text query to match against Polygraph sessions (title, description, and other indexed fields). Mutually exclusive with sha. |
| `sha` | `string` | no | Exact lookup of sessions linked to a commit by full or partial (7-40 hex chars) sha. Mutually exclusive with query. |
| `limit` | `number` | no | Maximum number of matching sessions to return. |
| `details` | `boolean` | no | Return the full untrimmed session objects instead of lean picker rows. |

---
Title: select_account
Description: Select an organization to operate on.
URL: https://docs.trypolygraph.com/mcp-tools/select_account
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Select an organization to operate on.

This persists the selection for subsequent CLI commands. Use list_accounts first to discover available organizations.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `orgId` | `string` | yes | The organization ID to select. Use list_accounts to discover available org IDs. |

---
Title: session_intro
Description: Render the Polygraph session welcome card (markdown) for a session.
URL: https://docs.trypolygraph.com/mcp-tools/session_intro
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Render the Polygraph session welcome card (markdown) for a session.

Returns the same card the CLI prints at startup — logo, session URL, repositories, and how to view child agent logs. Display its output to the user verbatim as markdown; do not wrap it in a code block.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |

---
Title: show_agent
Description: Get the status and recent output of the specified repo's child agent in a Polygraph session from the configured Polygraph URL.
URL: https://docs.trypolygraph.com/mcp-tools/show_agent
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Get the status and recent output of the specified repo's child agent in a Polygraph session from the configured Polygraph URL.

Use this to monitor progress of a delegated task; `repo` is required (no session-wide listing) — call once per repo you are watching. Repos can run multiple agents under named roles: pass `role` to inspect a specific agent; omitted = the default role's agent. The child's status field uses ACP lifecycle values: created, in-progress, input-required, permission-required, completed, failed, or cancelled. When `status === 'permission-required'`, read `pendingPermission` (structured request from the child) and respond by calling `allow_agent` or `deny_agent` with the same `role` — unless your MCP client supports elicitation, in which case the dialog appears automatically. To monitor without sleeping, pass `waitForTransitionMs` (max 50000): the call then blocks up to that long and resolves immediately when a child's state changes, so poll by calling this tool in a loop with no sleeps in between.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID whose child agent to check. Required — `agent show` always targets a single repo's child; there is no session-wide listing. |
| `role` | `string` | no | Optional role identifying which of the repo's agents to target; omit for the default agent. |
| `tail` | `number` | no | Number of output lines to return (default 50) |
| `waitForTransitionMs` | `number` | no | Long-poll: block up to this many milliseconds (max 50000) until a watched child transitions out of a created/in-progress state, resolving immediately on the state change. Children already in a terminal, input-required, or permission-required state return immediately. Omitted or 0 = return current status immediately (previous behavior). To watch for completion, call this tool in a loop with waitForTransitionMs set and NO sleeps in between — each call blocks server-side until something changes or the timeout elapses. |

---
Title: show_session
Description: Get the specified Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/show_session
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Get the specified Polygraph session.

Returns session url, status, description timeline, agentSessionId, associated pull requests across repositories, and any artifacts (plan documents, images, files) attached to the session. The agentSessionId can be used to resume an AI agent session. Resuming is reconnecting to restore context only. After you resume, do not make any changes until the user explicitly asks for changes.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `details` | `boolean` | no | Return the full untrimmed session payload. |

---
Title: spawn_agent
Description: Delegate a task to a child AI agent in a dependent repository.
URL: https://docs.trypolygraph.com/mcp-tools/spawn_agent
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Delegate a task to a child AI agent in a dependent repository.

The child agent will execute the task in that repo and return the result. Use this after initializing a Polygraph session with start_session. Multiple agents per repo are supported via the optional `role` parameter (omitted = the default role, whose logs are the only ones uploaded to the cloud). Follow-up routing is automatic per agent: if the targeted repo+role already has an active task (in-progress or input-required), the instruction is delivered to that task as a follow-up message instead of starting a new run.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID to delegate to |
| `instruction` | `string` | yes | Task instruction for the child agent |
| `context` | `string` | no | Background context about the task |
| `agent` | `enum` | no | AI agent implementation to use for the delegated task. One of: claude, opencode, codex. |
| `role` | `string` | no | Optional role identifying which of the repo's agents to target; omit for the default agent. |

---
Title: start_session
Description: Initialize Polygraph for the selected repos.
URL: https://docs.trypolygraph.com/mcp-tools/start_session
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Initialize Polygraph for the selected repos.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `title` | `string` | yes | Required human-readable session title shown in the Polygraph UI. Derive a short descriptive title from the user's task or request (e.g. "Fix login redirect loop across web and api"). Do not invent placeholder names. |
| `selectedRepoIds` | `array` | yes | Required list of repo IDs to include in the session. Use list_repos to discover available repos first. |

---
Title: stop_agent
Description: Stop an in-progress child agent in a Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/stop_agent
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Stop an in-progress child agent in a Polygraph session.

Use this to cancel a delegated task that is still in-progress.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `repo` | `string` | yes | Repo name or ID to stop |
| `role` | `string` | no | Optional role identifying which of the repo's agents to target; omit for the default agent. |

---
Title: update_pr
Description: Update a pull request's title, body, labels, or assignees through Polygraph.
URL: https://docs.trypolygraph.com/mcp-tools/update_pr
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Update a pull request's title, body, labels, or assignees through Polygraph.

Collection mode 'set' replaces every value and accepts an empty list to clear the collection. Modes 'add' and 'remove' require at least one nonblank value and preserve unrelated values. Omitted fields remain unchanged. Provide at least one metadata field.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. The pull request must be associated with this session. |
| `prUrl` | `string` | yes | The nonblank pull request URL to update. |
| `title` | `string` | no | A nonblank replacement title. Omit it to leave the title unchanged. |
| `body` | `string` | no | A new user-authored pull request body. An empty string clears it. Omit it to leave the body unchanged; Polygraph manages its own footer. |
| `labels` | `{ mode: "set" \| "add" \| "remove"; values: string[] }` | no | Label changes. 'set' replaces the complete collection and 'set' with [] clears it. 'add' and 'remove' require at least one nonblank value and preserve unrelated values. Omit labels to leave them unchanged. |
| `assignees` | `{ mode: "set" \| "add" \| "remove"; values: string[] }` | no | Assignee changes. 'set' replaces the complete collection and 'set' with [] clears it. 'add' and 'remove' require at least one nonblank value and preserve unrelated values. Omit assignees to leave them unchanged. |

## Returns

Returns a result with `sessionId`, `prUrl`, `outcome`, and one `operations` entry per requested field. `outcome` is `complete`, `partial`, or `failed`. Every operation includes `field`, `mode`, and `status`. Failed operations also include `applied`, `errorCode`, and `retryable`, and can include `mutationEvidence` as `none`, `possible`, or `confirmed`. Updated and unchanged operations omit `mutationEvidence`.

---
Title: update_session
Description: Update a Polygraph session title and/or user-facing description timeline.
URL: https://docs.trypolygraph.com/mcp-tools/update_session
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Update a Polygraph session title and/or user-facing description timeline.

Provide at least one of title or description.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `title` | `string` | no | New session title. At least one of title or description is required. |
| `description` | `string` | no | A session description is required. |
| `details` | `boolean` | no | Return the full untrimmed update payload, including the echoed description timeline. |

---
Title: upload_artifact
Description: Attach an artifact (plan document, image, or file) to a Polygraph session.
URL: https://docs.trypolygraph.com/mcp-tools/upload_artifact
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Attach an artifact (plan document, image, or file) to a Polygraph session.

Provide the content inline via content, or point at a file on disk via filePath — exactly one of the two. Uploading with an existing name creates a new version. Uploaded artifacts appear in show_session output.

## Arguments

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `sessionId` | `string` | yes | The Polygraph session ID, or a supported Polygraph app session URL. Supported URL paths are /s/<session-id> and /orgs/<org-id>/sessions/<session-id>. URL inputs are normalized to the session ID; the MCP always uses the current Polygraph API configuration. |
| `name` | `string` | yes | The artifact name. Reusing an existing name uploads a new version of that artifact. |
| `kind` | `enum` | no | The artifact kind. One of: plan, image, file. Defaults to the CLI default when omitted. Use "plan" for plan documents, "image" for images, and "file" for other binaries. |
| `format` | `enum` | no | The content format for text artifacts. One of: markdown, html, text. Defaults to the CLI default when omitted. |
| `content` | `string` | no | Inline artifact content (e.g. a plan document authored as text). Provide exactly one of content or filePath. The content is written to a temporary file and uploaded. |
| `filePath` | `string` | no | Absolute or relative path to a file to upload. Provide exactly one of content or filePath. |

---
Title: whoami
Description: Show the current Polygraph authentication and selected organization state.
URL: https://docs.trypolygraph.com/mcp-tools/whoami
---

<!-- Generated by scripts/sync-mcp-ref.mjs from data/mcp-tools.json. Do not edit by hand. -->

Show the current Polygraph authentication and selected organization state.

## Arguments

Arguments are not yet imported into this manifest. Refer to the Zod schema in the [polygraph-mcp repo](https://github.com/nrwl/polygraph-mcp) for the authoritative shape.

---
Title: For OSS developers
Description: Triage a contributor's bug report against its reproduction repo, fix it in your library, confirm the fix in the repro, and open the PR, all in one session.
URL: https://docs.trypolygraph.com/oss/for-oss-developers
---

You maintain an open-source library. A bug report lands with a link to a reproduction repo. The usual routine is to clone both repos, wire them together by hand, and run `npm pack` in a loop until the bug reproduces and the fix holds.

One Polygraph session holds your library and the contributor's public repro at once. You reproduce the bug, fix it in the library, confirm the fix in the repro, and open a PR, without the back-and-forth. The repro is a public repo you don't own, so Polygraph never opens a PR against it. Only your library gets one.

## Scenario: A bug report with a reproduction

A contributor filed an issue with a repro repo. You want to confirm the bug, fix it, and verify the fix before you publish anything.

### Reproduce first

I run `polygraph session start` in my library and add the repro.

```text
Add github.com/jaysoo/acme-lib-repro to this session. It reproduces an
issue in github.com/acme/lib.

Read the issue at <issue-url> and the repro's README. Run the failing command
in the repro and confirm you can reproduce the bug before changing anything.
```

The repro is public, so the agent pulls it in on demand. The contributor doesn't install or register anything. Their job ended when they filed the report.

### Investigate and fix

Once the bug reproduces, point the agent at the library:

```text
Find the code path in acme/lib responsible for this. Make the smallest fix you
can justify. Don't run the library's own tests yet, I want to verify against
the repro first.
```

The agent has both repos in one workspace, so it can read the repro and edit the library in the same turn.

### Verify the fix in the repro

```text
Test the fixed library against the repro and rerun the failing command. If it
still breaks, keep iterating. Once the repro passes, run the library's unit
tests for the files you touched.
```

This is the step that used to be a multi-terminal dance. The agent builds your fixed library, puts it in front of the repro, and reruns the failing command, so "is it actually fixed" is one turn instead of a manual loop.

### Open the PR against your library

```text
Open a PR against acme/lib with the fix. Title it "fix: <one-line summary>"
and link the issue and the repro in the body.
```

The PR lands on your library, never on the repro. Share the session link on the issue so the reporter and your reviewers see how you got to the fix, not just the diff.

---
Title: Security
Description: How Polygraph protects your credentials and code across repos.
URL: https://docs.trypolygraph.com/security
---

Polygraph runs AI agents across your repositories and streams their logs to the web UI.
The first piece of that story is keeping secrets out of those logs.

## Token protection

CLI sign-in uses an OAuth device flow with browser approval. The CLI stores
short-lived access tokens and rotating refresh tokens locally, preferring secure
credential storage when it is available.

Refresh tokens are single-use and rotate as they are used. If an old refresh
token is presented again, Polygraph treats it as possible replay and invalidates
the related credentials or session. The CLI may require you to sign in again.
Server-side OAuth tokens and approval codes are stored as protected hashes, not
plaintext.

`polygraph auth logout` revokes credentials remotely when possible and clears
local credentials.

### Protect your refresh token with 1Password

Install the 1Password CLI (`op`) and sign in before you start.
Open and unlock the 1Password desktop app, then turn on SDK integration in
**1Password Settings > Developer**.

1. Run `polygraph auth login` and select **Protect with 1Password** when Polygraph detects your
   1Password account.

   ![Polygraph login offering 1Password token protection](./security/1password-images/token-protection-prompt.png)

1. Choose the 1Password account to use.

   ![The 1Password account picker with chau@nrwl.io selected](./security/1password-images/account-selection.png)

1. Choose the vault that should store the encryption key.
   The example selects **Chau Personal**.

   ![The 1Password vault picker with Chau Personal selected](./security/1password-images/vault-selection.png)

1. Continue with the normal OAuth login.

After login, Polygraph saves an encryption key in the selected vault and uses it to encrypt your
OAuth refresh token.
The encrypted refresh token remains in Polygraph's normal credential storage.

If 1Password is locked when Polygraph refreshes the token, unlock it and retry.

{% aside type="note" title="Already signed in?" %}
Run `polygraph auth logout`, then run `polygraph auth login` and select
**Protect with 1Password**.
{% /aside %}

### Frequently asked questions

#### How often does 1Password prompt you?

1Password prompts you each time Polygraph uses the refresh token to renew the access token.
It doesn't prompt while the cached access token remains usable.

## Secret redaction

Before any agent log leaves your machine, the CLI scans each line for values that look like secrets and replaces them with `[REDACTED]`.
Redaction runs locally and covers both the main agent and child agents.

It masks:

- Private keys, bearer tokens, and prefixed provider tokens (`pypi-`, `hf_`, `vercel_`, and similar).
- Credentials inside connection URLs like `postgres://user:password@host`.
- Values of secret and connection environment variables (names containing `SECRET`, `TOKEN`, `_KEY`, `_URL`, and similar).
- Email addresses.

Redaction matches known secret shapes, so treat it as a safety net rather than a guarantee.
Don't rely on it to catch a secret you paste into a prompt or print to stdout.

## Session log sharing

Session logs capture prompts, responses, and tool activity, so a teammate or an agent that resumes
a session can see how the work got done.
Two controls decide who else reads them: **Share main agent logs** covers the main agent transcript,
and **Share child agent logs** covers child agent and setup transcripts.

A third control, **Background session capture**, decides something different: whether sessions run
outside Polygraph are recorded at all.
It's off until an organization admin turns it on, and it doesn't change who can read anything.
For what it records and how those recordings reach a pull request, see
[background session capture](/features/background-session-capture).

You always see the logs of sessions you authored, and resuming someone else's session doesn't
transfer authorship.
For everyone else, both defaults have to be on: the organization default for that log type, and the
session author's profile default.
If neither default is set, then logs stay visible until someone turns them off.
Set your own in **Profile** > **Log sharing**.
Organization admins set the organization default in **Account settings** > **Agent logs**.

To change sharing for a single session, select **Share**, then use **Shared log visibility** to turn
**Main agent logs** or **Child agent and setup logs** on or off.
That choice overrides both defaults, whether they were on or off.

Turning sharing off hides transcript content.
It doesn't make the session private or turn off logging.
Teammates with session access still see metadata such as repositories and pull requests.

## Access control

Access in Polygraph follows access in your version control system: whatever you can read there, you can read in Polygraph, and nothing more.

### What repos you can see

Polygraph derives repository access from your VCS permissions. It syncs each repo's collaborators and matches them to Polygraph users, and reconciles your access when you connect a VCS account. Public open source repos are readable by everyone.

### What sessions you can see

A session is visible only when you can access **all** of the organization repositories it uses. The rule applies everywhere a session can surface: session lists, search, and opening or resuming a session directly.

A session you lack access to behaves as if it doesn't exist. It is filtered from lists and search, and a direct open returns not-found rather than access-denied, so the session's existence isn't leaked.

Public open source repos never restrict visibility. A session whose repos are all public is visible to any member of the organization.

### What you can change

Write operations are enforced server-side against the same repository access. For example, creating a PR from a session requires access to the target repository, and the check runs on the server, not just in the CLI.

---
Title: SAML authentication
Description: Configure SAML single sign-on and revoke access when a user is offboarded.
URL: https://docs.trypolygraph.com/security/saml
---

Use Security Assertion Markup Language (SAML) single sign-on (SSO) to authenticate users in a
private Polygraph deployment.
Your identity provider verifies the user's identity, then sends a signed SAML response to
Polygraph.

## Authentication and repository access

SAML controls who can sign in to Polygraph.
Repository access still follows the user's permissions in your version control system (VCS).
A user must pass both checks:

1. The identity provider must authenticate the user.
2. The user must have access to the repository through the VCS provider.

Disabling either source prevents new access, but it doesn't revoke credentials that Polygraph has
already issued.

## Offboard a user

A complete offboarding flow closes existing access and prevents the user from signing in again:

1. Deactivate or unassign the user in the identity provider.
2. Use Universal Logout to revoke the user's active Polygraph sessions and credentials.
3. Remove the user from the relevant VCS organizations and repositories.

Universal Logout is optional.
It sends a server-to-server request from the identity provider to Polygraph, so it doesn't depend on
the user's browser being open.
Polygraph revokes the user's browser sessions, CLI credentials, connector credentials, device
authorizations, and cloud agent access.

Universal Logout isn't a replacement for System for Cross-domain Identity Management (SCIM).
It doesn't provision users, synchronize groups, or delete user records and audit history.

## Configure an identity provider

Polygraph currently documents SAML authentication and Universal Logout with Okta.
See [Okta SAML authentication](/security/saml/okta) for the setup steps.

---
Title: Okta SAML authentication
Description: Configure SAML authentication and optional Universal Logout for Polygraph with Okta.
URL: https://docs.trypolygraph.com/security/saml/okta
---

Configure Polygraph as a separate Okta app integration from your Nx Cloud SAML app.
The SAML setup is the same except for the single sign-on URL and audience URI.
You can assign the same groups and users to both app integrations.

## Set up SAML

1.  In the Okta Admin Console, go to **Applications** > **Applications**, then select
    **Create App Integration**.

    ![Create an app integration from the Applications page in the Okta Admin Console](./okta-images/create-app-integration.avif)

1.  Select **SAML 2.0**, then select **Next**.

    ![Select SAML 2.0 as the sign-in method](./okta-images/select-saml.avif)

1.  Enter a name such as `Polygraph`, then select **Next**.

    ![Name the SAML app integration](./okta-images/name-app.avif)

1.  Configure the SAML settings:

    1. Set **Single sign-on URL** to `<POLYGRAPH_APP_URL>/auth-callback`.
       Your developer productivity engineer (DPE) provides `POLYGRAPH_APP_URL`.
    2. Select **Use this for Recipient URL and Destination URL**.
    3. Set **Audience URI (SP Entity ID)** to `polygraph-private-cloud`.
    4. Leave **Default RelayState** empty.

    ![Configure the Polygraph callback URL and audience URI](./okta-images/saml-settings.avif)

1.  Under **Advanced Settings**, configure the signatures:

    1. Set **Response** to **Signed**.
    2. Set **Assertion Signature** to **Signed**.
    3. Set **Signature Algorithm** to **RSA-SHA256**.
    4. Set **Digest Algorithm** to **SHA256**.

    ![Sign the SAML response and assertion with RSA-SHA256](./okta-images/signatures.avif)

1.  Under **Attribute Statements**, add these attributes:

    | Name    | Name format     | Value        |
    | ------- | --------------- | ------------ |
    | `id`    | **Unspecified** | `user.email` |
    | `email` | **Unspecified** | `user.email` |

    ![Map the id and email SAML attributes to the user's email address](./okta-images/attribute-statements.avif)

1.  Select **Next**, select **I'm an Okta customer adding an internal app**, then select **Finish**.

1.  Open the **Assignments** tab and assign the groups or users that can sign in to Polygraph.
    You can assign the same groups and users that use your Nx Cloud SAML app.

    ![Assign groups and users to the Polygraph SAML app](./okta-images/assignments.avif)

1.  Open the **Sign On** tab and find **SAML Signing Certificates**.
    From the certificate with the **Active** status, select **Actions** >
    **Download certificate**.

    ![Download the active SAML signing certificate](./okta-images/download-certificate.avif)

1.  Convert the downloaded certificate into the one-line value for
    `POLYGRAPH_SAML_CERT`:

    ```shell
    awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' okta.cert
    ```

1.  From the active certificate, select **Actions** > **View IdP metadata**.

    ![View the identity provider metadata for the active certificate](./okta-images/view-metadata.avif)

1.  Find the `SingleSignOnService` element that uses the HTTP-POST binding and copy its
    `Location` URL.
    This URL is the value for `POLYGRAPH_SAML_ENTRY_POINT`.

    ```html
    <md:SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://<your-okta-domain>/app/<your-polygraph-app>/<app-id>/sso/saml"
    />
    ```

    ![Copy the HTTP-POST SingleSignOnService location from the IdP metadata](./okta-images/copy-entry-point.avif)

1.  If you plan to configure Universal Logout, copy the `entityID` attribute from the
    `EntityDescriptor` element in the IdP metadata.

    ![Copy the entityID attribute from the EntityDescriptor element](./okta-images/entity-id.avif)

## Configure universal logout

Universal Logout is optional and lets Okta revoke a user's active Polygraph sessions and
credentials.

1. In the Okta Admin Console, go to **Applications and Resources** > **Applications** and select
   the Polygraph app.
2. Open the **General** tab.

   ![Open the General tab for the Polygraph app](./okta-images/universal-logout-general-tab.avif)

3. In the **Logout** section, select **Edit**.
4. Select **Okta system or admin initiates logout**.
5. Set **Endpoint URL** to `<POLYGRAPH_APP_URL>/saml/global-token-revocation`.
6. Keep **Endpoint authentication type** set to **Signed JWT**.
7. Set **Subject format** to **Email Identifier**.
8. Select **Save**.

   ![Configure the Polygraph endpoint and email identifier for Universal Logout](./okta-images/universal-logout-settings.avif)

## Information to exchange with your DPE

Your DPE provides the **Polygraph app URL** (`POLYGRAPH_APP_URL`) used for the single sign-on URL.

Send these values to your DPE after you configure SAML:

1. **SAML certificate**, the one-line certificate string from the active Okta signing certificate.
2. **SAML entry point**, the HTTP-POST `SingleSignOnService` URL from the IdP metadata.
3. **Okta entity ID**, the `entityID` from the `EntityDescriptor` element, if you configure Universal
   Logout.

---
Title: Find and reuse prior work
Description: Search past sessions for prior art, trace any commit back to the session that produced it, and anchor new work to how your organization already solved the problem.
URL: https://docs.trypolygraph.com/use-cases/find-and-reuse-prior-work
---

Use Polygraph to make past sessions the starting point for new work.

Run the same prompt three times and you get three different implementation styles. 
You need an anchor that provides the solution to the same or similar problems that 
already exists in your organization.

Each Polygraph session is searchable, so prior work is something you can find and build on.

## Start from prior art


Ask your agent to find relevant sessions:

```text
Can you search for sessions that dealt with Stripe webhook retries?
```

The agent searches your organization's sessions and reports the matches, each with its PRs and a one-line summary. You can also search interactively from the terminal:

```sh
polygraph session search
```

Once you've found the session that did it right, anchor the new work to it:

```text
Reference Polygraph session <session-id>. It added webhook retries to the
billing service. Apply the same approach here: same backoff strategy, same
error taxonomy, same test structure. Flag anywhere our service can't follow
that pattern and why.
```

The agent replicates the settled approach instead of improvising a new one.
The two sessions are also linked, so the next person who searches finds a pattern with two uses.

## Trace a change back to its session

A bug shows up in code that changed recently. Before you patch around it, find the session that
made the change and understand what it was trying to do. Find the commit with `git blame`, then ask:

```text
Can you search for the session that made this change? 4f9c21a
```

If you don't have a sha handy, describe the area instead:

```text
Can you search for sessions that touched the signup flow recently?
```

The result is the session that produced the change. You get the prompts, the reasoning, and the
constraints behind it. Reference it from your current session and ask:

```text
Reference Polygraph session <session-id>. Duplicate welcome emails started
going out this week. Summarize what this session changed and why, and
whether it could explain the duplicates.
```

## The more you record, the better it works

Each session adds to the searchable record, so over time "how do we do X here" is answered by a session instead of by whoever happens to remember. New engineers, and new agents, inherit that record.

---
Title: Migrate a library
Description: Move every repo that uses a library to a new version, with the library's source in the session so the agent knows exactly what changed.
URL: https://docs.trypolygraph.com/use-cases/migrate-a-library
---

Use Polygraph to migrate your repos from one version of a library to a newer one.

Major upgrades are rarely mechanical: APIs move, defaults change, and the migration guide never covers your exact usage. And the same migration has to happen in every repo that uses the library, so the work is repetitive on top of being tricky.

## Give the agent the library itself

Polygraph can add the library's public repo to the session, so the agent reads what actually changed between the versions instead of guessing from the changelog. See [OSS repo integration](/features/oss-repo-integration).

### Example prompt

I run `polygraph session start` and describe the migration:

```text
Add every repo in my account that depends on vitest, and add
vitest-dev/vitest itself for context.

Migrate every repo from vitest 1.x to 2.x. Read the vitest repo first and
summarize the changes between the versions that affect us. Then propose a
per-repo plan before you change anything.
```

The agent reads the library's source, maps the breaking changes to how each of your repos actually uses it, and proposes a plan you can review before anything moves.

## Fan out the migration

```text
Apply the plan repo by repo. Run each repo's tests and report a per-repo
pass/fail. Open a draft PR for every repo that passes; for the rest, report
what's blocking.
```

Each repo is handled by its own child agent, so the migration proceeds in parallel and a failure in one repo never blocks the others. Repos that pass get a reviewable PR. Repos that don't come back with a concrete blocker instead of a half-applied upgrade.

## Reuse the migration

The session becomes the record of how the migration was done. When another team migrates their repos, or the next major version lands, they search for and reference this session and apply the settled approach.

---
Title: Patch a CVE
Description: A CVE drops. Find every repo affected, open patch PRs, and hand each PR to the team that owns the repo, without losing the audit trail.
URL: https://docs.trypolygraph.com/use-cases/patch-a-cve
---

Use Polygraph to respond to an advisory across every repo it touches, in one session.

An advisory lands and the job is always the same shape. Find which of your repos are exposed, patch each one, and keep a record of what you did. You drive the whole thing from one session, then hand each PR to the team that owns the repo.

## Scenario: Patching a vulnerable dependency

### Triage, then find the blast radius

I run `polygraph session start` and point the agent at the advisory first.

```text
Read advisory <advisory-url> and summarize the affected versions and the
attack surface. Don't change anything yet.

Then add every repo in my account that depends on the affected package with the affected version.
For each one, report its installed version, whether the dependency is direct or
transitive, and where it's used.
```

Telling it to read and report first, before changing anything, keeps you in control. The agent treats the advisory page as untrusted input, and you decide the response before it touches a repo.

### Patch and verify

```text
For each affected repo, open a fix branch and bump the package to a safe
version (or pin it with an override if it's transitive). Run install and
tests. Change nothing else. Report a per-repo pass/fail.
```

Keeping the change to a version bump and lockfile makes each PR a small, reviewable diff. If a repo needs a real code change to adopt the safe version, let that be its own PR rather than hiding it inside the bump.

### Distribute to owning teams

```text
For every patched repo, open a draft PR titled
"fix(security): bump <package> (<advisory-id>)". In the body include the
advisory link, the change, the test output, and a link to this session.
```

Every PR starts as a draft, so a human reviews each diff before it merges.

## The session is the audit trail

For each repo, the session timeline records the version it read, whether the repo was affected, the patch, the test output, and the PR it opened.

It records what happened, in order. It isn't a formal compliance attestation on its own. Treat the session as the source and export it into whatever system already holds your audit evidence, and confirm retention and access details with your account team before citing it in an audit.

---
Title: Review code with full context
Description: Large AI-generated pull requests are hard to review from the diff alone. Open the session behind the PR and ask about the intent, the alternatives considered, and the decisions made.
URL: https://docs.trypolygraph.com/use-cases/review-code-with-full-context
---

Use Polygraph to review the reasoning behind an AI-generated pull request.

Traditional code review tools show you diffs, so you know _what_ has changed but not _why_.
With Polygraph, you can ask the agent about competing solutions that were considered, scope
that was cut, and surprises that came up in the session.

Each Polygraph session records the decisions that shaped the result. Previously, you'd have
to sit in a call with the PR author to ask questions. Now you ask the session and get
answers without a meeting.

## Ask the session about the change

From the PR, follow the session link, or open the session directly:

```sh
polygraph session review <session-id>
```

Review mode resumes the session with the agent answering questions instead of continuing the work.
Ask anything the diff doesn't tell you. The agent answers based on the recorded session history.

```text
What alternatives were considered, and why were they rejected?
```

```text
Which parts of this PR are you least confident about?
What was done to address them?
```

The agent can point at the moment in the session where a test failed, a constraint surfaced, or an approach was dropped.

## What to ask

Questions that work well in review mode:

- **Critical files**: which files require attention during the review and might be buried by noise.
- **Solution space**: what other designs were on the table, and what ruled them out.
- **Surprises**: what the agent learned mid-task that the spec didn't anticipate.
- **Risk**: which files it touched with the least surrounding context, and what tests cover them.
- **Scope**: what was deliberately left out, and where that's recorded.
- **Best practices**: compare the work to similar sessions to see whether the PR follows them.
- **Adversarial review**: run an adversarial review with a different agent and summarize the findings.

---
Title: Set up a software factory
Description: A software factory is a workflow, not a product. Compose one from your issue tracker, your agent, and Polygraph in about 20 minutes.
URL: https://docs.trypolygraph.com/use-cases/set-up-a-software-factory
---

Use Polygraph to run a software factory: a loop that picks up issues, implements them, reviews the work, and opens PRs, while humans define the intent and review the outcomes.

A software factory is a workflow, not a product. You don't buy one. You compose one from the tools you already use: your VCS, your CI, your issue tracker, your agent. Polygraph supplies the missing pieces: cross-repo orchestration, [per-session workspaces](/features/cross-repo-agent-sessions#workspaces-and-worktrees) that are cleaned up when the session is archived, institutional memory, PR and CI coordination, and adversarial reviews.

## The workflow

Every run follows the same shape:

1. **Find work**: query the issue tracker for tasks (e.g. issues labeled `factory`).
2. **Get debriefed**: read the issue and search past sessions for related context.
3. **Set up repos**: start a Polygraph session with the relevant repos.
4. **Implement**: make the changes across the repos.
5. **Review**: run an adversarial review on non-trivial changes.
6. **Open PRs**: push branches, open linked draft PRs, and verify CI passes.
7. **Record**: the session captures the decisions and design rationale.
8. **Complete**: close the issue and link the session.

## What to expect

A factory won't produce 100% of your code. It's a pattern: route the work agents can carry end to end through the factory, and keep everything else in normal sessions. Because every run is recorded, the [institutional memory](/features/institutional-memory) compounds and each run starts with more context than the last.

For the full walkthrough, including a reference script (about 400 lines) wiring GitHub, Linear, Claude, and Polygraph together, read [A software factory is a workflow, not a product](https://medium.com/nrwl/a-software-factory-is-a-workflow-not-a-product-build-one-in-20-minutes-7674e4135e98).

---
Title: Update a design system component
Description: Change a design system component, validate it against every consumer, open PRs where it lands cleanly, and tell the right team where it doesn't.
URL: https://docs.trypolygraph.com/use-cases/update-a-design-system-component
---

Use Polygraph to change a design system component and check every consumer before you release.

You own a design system, an API client, or an internal SDK, and many teams depend on it. You publish a new version, hoping nothing breaks. You checked a few repos, but missed some. It's common in such scenarios for downstream consumers to break when they try to upgrade weeks later.

At this point you and the downstream teams scramble to fix the issue. That's a lot of unnecessary context switching on both sides.

With Polygraph, one session fully understands your library and its consumers, you can test the change against each consumer first, then open PRs where it's safe and flag the teams where it isn't.

## Scenario: A change with downstream impact

You're removing a deprecated component from your design system and need to know which consumers break before you cut a release.

### Example prompt

I'm inside the library repo and run `polygraph session start`.

```text
Add acme/web-app, acme/admin-dashboard, and acme/mobile-shell to this
session.

In the design system, remove the deprecated <Modal> component. Consumers
should migrate to <Dialog>, which replaces it. Its API is different. There's
no closeOnOverlayClick, and focus trapping is built in.

Then check each consumer against my change. Build and test each one, and
report which pass, which break, and where they still use <Modal>.
Don't open any PRs yet.
```

The agent makes the change in your library, puts it in front of each consumer, and runs their build and tests. You get a per-consumer result before anything ships.

### Test with the new version

If you want to verify that the changes are safe, use the following prompt:

```text
Pack and copy the design system library into every application and verify
that the changes work.
```

This lets you test all the consumers against a version of the design system that hasn't been published yet.

### Route the outcomes

Once you have the results, ask the agent to act on them:

```text
For consumers that passed, open a draft PR bumping @acme/design-system to the
next version.

For consumers that break only on a straight <Modal> -> <Dialog> swap, apply
the swap, rerun their tests, and include it in the same PR.

For consumers that used <Modal> features <Dialog> handles differently (like
closeOnOverlayClick), open a draft PR with the failing output and @-mention
the owning team from CODEOWNERS. Link this session in the body.
```

Clean consumers get a ready-to-merge bump. Mechanical breaks get the fix applied and verified. Anything that needs human judgment lands on the owning team's desk with the failure and the context attached.

## Hand off to consumer teams

The consuming team can reference your Polygraph session from their own, which gives them your trace (the library change, the validation output, the failing commands) while keeping their verification on their own branches.

From the consumer team's side:

```text
Reference Polygraph session <session-id> and pull the @acme/design-system
changes from it. Tell me what's changed so I can understand and verify it.
```

Your session stays the record of what you shipped and who it affected. Theirs is their own verification and shipping timeline.

---
Title: Update backend and frontend
Description: Ship one feature across a backend API and the frontend that calls it, as if they were one monorepo.
URL: https://docs.trypolygraph.com/use-cases/update-backend-and-frontend
---

Use Polygraph to ship a feature that touches both an API and the UI that calls it.

A new endpoint needs to be coordinated with UI/UX changes. The repos sit on separate teams' release schedules, but the change has to land coherently or one side breaks the other. The work is a single feature (in a monorepo this would be one PR).

## Example prompt

I'm inside the backend repo and run `polygraph session start`.

```text
Add acme/frontend to this session.

Refer to my feature spec at <specification-file>.
This requires both API (backend) and UI/UX (frontend) changes.

Read both repos first. Confirm the auth contract and the shared response
type, then propose a plan with one bullet per repo before you write code.
```

Replace `acme/frontend` with the actual repo. The `<specification-file>` describes the feature so AI agents know what to build (e.g. `PRD.md`).

The agent reads both repos before writing code, so it understands the architecture and existing patterns. It then produces a plan for the current session that the child agents can execute on.

## Open the PRs

Once the work is complete, ask the agent to open PRs against both repos.

```text
Push both branches and open PRs.
```

For a change to a contract that several services share, see [Update multiple microservices](/use-cases/update-multiple-microservices).

---
Title: Update multiple microservices
Description: Change a contract that several microservices share, verify every consumer before the publisher ships, and coordinate the merge order.
URL: https://docs.trypolygraph.com/use-cases/update-multiple-microservices
---

Use Polygraph to change a contract that several services touch.

You're adding a field to an event or message shape that three services share (one publisher, two consumers). Before the publisher change can land, you need to be sure the consumers don't break. The work is a single change (in a monorepo this would be one PR).

## Example prompt

```text
Add `acme/orders-service`, `acme/billing-service`, and `acme/notifications-service`
to this session.

Add a `currency` field to the `OrderPlaced` event.
- `orders-service` publishes it
- `billing-service` and `notifications-service` consume it.
```

The agent reads every consumer before touching the publisher. That order prevents the "publisher ships, consumers explode" problem. Polygraph helps you detect which downstream consumers may break with the changes. Open PRs to consumer repos to gracefully handle the publisher changes prior to shipping them out.

Everything is tracked in a single session so you and your agents don't lose context.

## Coordinating merge order

For contract changes, merge order matters. Usually the publisher merges last and consumers first, so consumers tolerate the new field before it appears on the wire. Encode that in the session:

```text
Once both consumer PRs are reviewed and green in CI, mark them ready. Hold
the publisher PR as a draft.
```

Once the consumer changes are live, you can resume the session with `polygraph session resume <session-id>` and prompt:

```text
Mark the publisher PR as ready for review.
```