DocsWorkflowsComponentsMachinemachine:agent:session:list

machine:agent:session:list

Lists the sessions coding agents keep on the machine the run happens on, each with its tokens, cost, models and tool calls, the subagents it spawned included. A session whose agent recorded no cost is priced from the run's price table, and stays uncosted with an empty cost_source when a model it ran is not in that table.

Options

Name	Type	Description
`agent`	`string`	The coding agent whose sessions to list, one of claude-code, codex or opencode; empty lists every one of them
`home`	`string`	The agent's state directory, such as ~/.claude; empty reads the agent's own default, and it needs an agent
`dir`	`string`	Keeps the sessions that ran in this directory or below it; a relative one is read against the pipeline cwd
`since`	`string`	Keeps the sessions active at or after this time, RFC 3339 or a YYYY-MM-DD date
`until`	`string`	Keeps the sessions that started before this time, RFC 3339 or a YYYY-MM-DD date
`limit`	`int`	The most sessions to answer, the most recently active first

Outputs

Name	Type	Description
`sessions`	`[]Session`	The matching sessions, the most recently active first
↳ `id`	`string`	The session id, which the agent resumes the session by
↳ `agent`	`string`	The coding agent that ran the session
↳ `title`	`string`	The session's title, where the agent named it
↳ `dir`	`string`	The working directory the session started in
↳ `git_branch`	`string`	The git branch checked out when the session started
↳ `version`	`string`	The version of the agent CLI that wrote the session
↳ `started_at`	`string`	When the session's first record was written, RFC 3339 in UTC
↳ `ended_at`	`string`	When the session's last record was written, RFC 3339 in UTC
↳ `messages`	`int`	How many user and assistant text messages the session holds
↳ `tools`	`[]ToolUse`	How many times the agent and its subagents called each tool
↳ `name`	`string`	The tool the agent called, as the agent names it
↳ `calls`	`int`	How many times the agent called it
↳ `models`	`[]ModelUsage`	What each model spent across the session and its subagents
↳ `model`	`string`	The model as the agent's provider names it
↳ `usage`	`Usage`	The tokens the model spent and what they cost
↳ `input_tokens`	`int64`	Prompt tokens the provider did not serve from its cache
↳ `output_tokens`	`int64`	Completion tokens, reasoning included
↳ `cache_read_tokens`	`int64`	Prompt tokens served from the provider's prompt cache
↳ `cache_write_tokens`	`int64`	Prompt tokens written into the provider's prompt cache
↳ `reasoning_tokens`	`int64`	The part of the output tokens the model spent thinking
↳ `cost_usd`	`float64`	What the tokens cost in US dollars, zero where nothing recorded or priced it
↳ `usage`	`Usage`	What the session and its subagents spent in total
↳ `input_tokens`	`int64`	Prompt tokens the provider did not serve from its cache
↳ `output_tokens`	`int64`	Completion tokens, reasoning included
↳ `cache_read_tokens`	`int64`	Prompt tokens served from the provider's prompt cache
↳ `cache_write_tokens`	`int64`	Prompt tokens written into the provider's prompt cache
↳ `reasoning_tokens`	`int64`	The part of the output tokens the model spent thinking
↳ `cost_usd`	`float64`	What the tokens cost in US dollars, zero where nothing recorded or priced it
↳ `cost_source`	`string`	Where the cost came from, reported by the agent, priced from the tokens, or empty when unknown
↳ `path`	`string`	The file or directory the session was read from

Example

name: What the agents spent this week
actions:
  - name: recent
    component: machine:agent:session:list
    vars:
      dir: ./project
      since: "2026-10-14"
      limit: 50

outputs:
  sessions: "{{ recent.sessions }}"

Edit or read the source on GitHub