Session management
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI
Start a new session
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --namestringSession name --repoarray<string>Repository IDs or org/repo names --initiatorstring|booleanRepository ID or org/repo name that should host the parent agent. Use "none" or --no-initiator for symmetric mode. --multiplexer, -m"auto"|"none"|"tmux"|"iterm2"|"kitty"|"ghostty"|"cmux"|"zellij"Terminal multiplexer to use for delegated child agents. Defaults to auto-detect. --launchstringLaunch the given agent after the session is created. One of: claude, codex, opencode, skip. When omitted, falls back to the interactive prompt (or 'skip' under --json). --promptstringInitial 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.
List sessions
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --sincestringOnly return sessions created on or after this date (YYYY-MM-DD, UTC). Defaults to the last 30 days. Example: --since=2025-01-01 --limitnumber100Maximum number of sessions to return (1-500, default 100). --filterobjectFilter sessions under a single object option --filter.statusstringMatch session status using exact values, glob, or CSV patterns. Quote globs, for example 'comp*'. --filter.authorstringMatch session authors using case-insensitive substring, glob, or CSV patterns. Defaults to @me, the current user; use '*' to include all authors. --filter.initiatorstringMatch the initiator repository using case-insensitive substring, glob, or CSV patterns. Supports @current. --filter.repostringMatch repositories included in a session using case-insensitive substring, glob, or CSV patterns. Supports @current. --filter.hasPrsbooleanFilter by whether sessions have at least one linked pull request.
Show session details
polygraph session show [session]
Name Type Description sessionstringSession ID (auto-detects from cwd if omitted)
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --detailsbooleanfalseInclude a per-repo summary with PR id, url, and description.
Print the session welcome card
polygraph session intro [session]
Name Type Description sessionstringSession ID (auto-detects from cwd if omitted)
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --session, -sstringSession ID (auto-detects from cwd if omitted)
Open a shell in a session repository
polygraph session dir [session] [repo]
Name Type Description sessionstringSession ID (auto-detects from cwd if omitted) repostringRepository (ID, full name, or short name)
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --session, -sstringSession ID (auto-detects from cwd if omitted) --repo, -rstringRepository (ID, full name, or short name) --rootbooleanfalseOpen the session root instead of a repo --printbooleanfalsePrint the selected directory instead of launching a shell --commandstringRun a shell command in the selected directory instead of launching a shell
Resume a session
polygraph session resume [session]
Name Type Description sessionstringSession ID (auto-detects from cwd if omitted)
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --multiplexer, -m"auto"|"none"|"tmux"|"iterm2"|"kitty"|"ghostty"|"cmux"|"zellij"autoTerminal multiplexer to use for delegated child agents.
Archive a session
polygraph session archive [session]
Name Type Description sessionstringSession ID (auto-detects from cwd if omitted)
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --cleanbooleanfalseRemove cloned repos after archiving
Link an external reference to a session
polygraph session link-reference
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --session, -sstringSession ID (auto-detects from cwd if omitted) --typestringReference type (e.g. session, url) --urlstringURL of the external reference --labelstringLabel for the reference --referenceSessionIdstringRequired when --type=session
Add repositories to a session
polygraph session add-repo [repo]
Name Type Description repoarray<string>Repositories to add (ID, full name, or short name)
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --session, -sstringSession ID (auto-detects from cwd if omitted) --repo, -rarray<string>Repositories to add (ID, full name, or short name)
Update the description of a session
polygraph session update-description
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --session, -sstringSession ID (auto-detects from cwd if omitted) --descriptionstringNew description for the session
Prune old sessions
Flag Type Default Description --help, -hbooleanShow help for the current command --versionbooleanShow the version number for the CLI --sessionarray<string>Session IDs to prune --yes, -ybooleanSkip confirmation prompt --statusstringFilter sessions by status --authorstringFilter sessions by author --hasPrsbooleanFilter by whether sessions have linked PRs --older-thannumber30Prune sessions older than this many days (default 30)