sessions

Synopsis

$ phrony sessions <subcommand> [args] [flags]

Description

Inspect runtime sessions and attach to an existing session by id.

While a session is running, awaiting_tool, awaiting_approval, or awaiting_input, the daemon keeps a single background driver per session. sessions attach (and phrony run --attach after start) subscribes to that driver’s event stream. Closing the attach view with Ctrl+C only unsubscribes; execution continues until the session reaches a terminal status or you sessions cancel. More than one client may attach to the same active session and receive live events.

sessions ls

List sessions, optionally filtered by agent, bundle, or status.

$ phrony sessions ls [TARGET] [flags]

When TARGET is omitted, lists sessions across all agents and bundles. When set:

• Agent filter (default): TARGET is namespace/name (same as phrony run).
• Bundle filter: pass --kind bundle and TARGET is a bundle reference (namespace/name, optional @version or lock hash).

By default, the listing shows root sessions only—runs started directly with phrony run or phrony bundles run. Sessions created by agent delegation (nested child runs linked via parent_session_id) are omitted unless you pass --include-children.

Flags

Examples

$ phrony sessions ls
$ phrony sessions ls demo/echo-agent
$ phrony sessions ls demo/echo-agent --status awaiting_input
$ phrony sessions ls --status awaiting_approval
$ phrony sessions ls --include-children
$ phrony sessions ls demo/orchestrator --include-children --status running
$ phrony sessions ls --kind bundle demo/delegation-assistant
$ phrony sessions ls demo/my-bundle --kind bundle --status completed

Output

Table columns: ID, KIND, TARGET, STATUS, UPDATED_AT, RESUMABLE (yes when status is awaiting_input).

• KIND — agent for direct runs, bundle for runs started with phrony bundles run.
• TARGET — the agent or bundle the session belongs to, as namespace/name@version (bundle ref when KIND is bundle, otherwise the executing agent ref). Delegated child sessions show the specialist agent they run under.

Sessions in awaiting_approval are waiting on an operator decision. Use phrony approvals to list and decide pending approvals; see Human-in-the-loop approvals.

sessions inspect

Dump the full persisted state for one session: input, output, conversation history, token usage, ordered audit timeline, tool invocations (with queue and execution delays), approvals, agent context, and delegated child sessions.

$ phrony sessions inspect SESSION_ID [flags]

Flags

Examples

$ phrony sessions inspect run_abc123
$ phrony sessions inspect run_abc123 --json

Human output includes a unified timeline (session events, invocation milestones, and approvals sorted chronologically with inter-step gaps), per-turn usage from history, and nested child sessions when the run delegated to sub-agents.

sessions attach

Connect to an existing session by id.

$ phrony sessions attach SESSION_ID [flags]

Use a session id from sessions ls.

When the stored status is running or another non-terminal state and the background driver is active, attach subscribes to live events (text deltas, tools, approvals) and replays persisted history. Ctrl+C detaches; the session keeps running.

When the stored status is awaiting_input, the CLI resumes the interactive prompt so you can send further turns (unless input is blocked by a run limit).

When the status is awaiting_approval, attach replays history and shows the pending approval on the stream. Decide with phrony approvals in another terminal (or tool_approval on the stream if your client supports it).

When the status is completed or failed, attach is read-only: you cannot send new messages. With --no-tui, the CLI prints history and the stored result, then exits. With the default TUI, the transcript stays on screen so you can scroll and review; press Ctrl+C to quit.

Flags

Example

$ phrony sessions attach run_abc123

sessions cancel

Cancel an in-progress session.

$ phrony sessions cancel SESSION_ID

Sets status to cancelled and stops the background driver (and any attached views stop receiving new events).

Example

$ phrony sessions cancel run_abc123