Skip to content

polygraph agent

Child agent controls

Terminal window
polygraph agent
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI

List child agents for a session

Terminal window
polygraph agent list
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)

Delegate work to a child agent

Terminal window
polygraph agent spawn [repo] [instruction]
NameTypeDescription
repostringRepository (ID, full name, or short name)
instructionstringInstruction to execute
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)
--rolestringAgent 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.
--contextstringAdditional context for the delegated task
--agent"claude" | "opencode" | "codex" | "auto"Agent runtime to use

Show child agent status for a repository (repo required)

Terminal window
polygraph agent show [repo]
NameTypeDescription
repostringRepository (ID, full name, or short name)
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)
--rolestringAgent 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.
--tailnumberNumber of trailing log lines to include
--wait-for-transition-msnumberBlock 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.

Attach a TUI to a child agent

Terminal window
polygraph agent attach [session]
NameTypeDescription
sessionstringSession ID (auto-detects from cwd if omitted)
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--repo, -rstringRepository (ID, full name, or short name) — optional; the picker resolves it when omitted.
--rolestringAgent 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.

Stop a child agent

Terminal window
polygraph agent stop [repo]
NameTypeDescription
repostringRepository (ID, full name, or short name)
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)
--rolestringAgent 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.

Grant a child agent's pending permission-required request

Terminal window
polygraph agent allow [repo]
NameTypeDescription
repostringRepository (ID, full name, or short name)
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)
--rolestringAgent 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-timeGrant scope — 'one-time' applies only to this request; 'session' remembers it for equivalent later requests within the child's session
--reasonstringOptional reason for the grant

Deny a child agent's pending permission-required request

Terminal window
polygraph agent deny [repo]
NameTypeDescription
repostringRepository (ID, full name, or short name)
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)
--rolestringAgent 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.
--reasonstringOptional reason for the denial

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

Terminal window
polygraph agent events
FlagTypeDefaultDescription
--help, -hbooleanShow help for the current command
--versionbooleanShow the version number for the CLI
--session, -sstringSession ID (auto-detects from cwd if omitted)
--followbooleanfalseStay alive and stream new permission-gate transitions (tail -f). Without it, dump current pending gates and exit.