DocsWorkflowsComponentsMachinemachine:agent:session:read

machine:agent:session:read

Reads one session a coding agent keeps on the machine the run happens on, with its messages, its turns, the subagents it spawned and what each of them spent. Tool inputs and outputs are left out, since they are bulky and routinely carry whatever secrets the agent saw.

Options

Name	Type	Description
`agent`	`string`	The coding agent that ran the session, one of claude-code, codex or opencode
`session_id`	`string`	The session to read, as machine:agent:session:list or machine:agent:session:create returned it
`home`	`string`	The agent's state directory, such as ~/.claude; empty reads the agent's own default

Outputs

Name	Type	Description
`session`	`Session`	The session and its level-one metrics
↳ `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
`messages`	`[]Message`	The user and assistant text messages of the session itself, in order
↳ `role`	`string`	Who wrote it, user or assistant
↳ `text`	`string`	The message text
↳ `at`	`string`	When it was written, RFC 3339 in UTC
↳ `model`	`string`	The model that wrote an assistant message
`turns`	`[]Turn`	Each prompt of the session with its duration and usage
↳ `id`	`string`	The turn as the agent identifies it
↳ `started_at`	`string`	When the turn started, RFC 3339 in UTC
↳ `duration_ms`	`int64`	How long the turn took, zero where the agent did not record it
↳ `model`	`string`	The model that answered the turn
↳ `effort`	`string`	The reasoning effort the turn ran at
↳ `usage`	`Usage`	What the turn spent, its subagents excluded
↳ `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
`subagents`	`[]Subagent`	Every agent the session spawned, at any depth
↳ `id`	`string`	The subagent as the agent identifies it
↳ `parent_id`	`string`	The subagent or session that spawned it
↳ `depth`	`int`	How many spawns down from the session it sits, one for a direct child
↳ `kind`	`string`	The kind of subagent, as the agent names its type or role
↳ `description`	`string`	What the subagent was spawned to do, or its nickname
↳ `model`	`string`	The model the subagent ran on
↳ `tools`	`[]ToolUse`	How many times the subagent called each tool
↳ `name`	`string`	The tool the agent called, as the agent names it
↳ `calls`	`int`	How many times the agent called it
↳ `usage`	`Usage`	What the subagent spent itself
↳ `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
↳ `total_usage`	`Usage`	What the subagent and every subagent below it spent
↳ `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
`errors`	`[]Error`	The failures the session recorded
↳ `at`	`string`	When it happened, RFC 3339 in UTC
↳ `message`	`string`	What failed, as the agent recorded it
`permission_mode`	`string`	The permission or approval mode the session last ran under
`effort`	`string`	The reasoning effort the session last ran at
`context`	`ContextWindow`	How full the context window was at the last request
↳ `size`	`int64`	The tokens the context window holds, zero where the agent did not record it
↳ `used`	`int64`	The tokens the last request put into it
`rate_limits`	`[]RateLimit`	The account's usage limits as the provider last reported them
↳ `name`	`string`	Which limit it is
↳ `used_percent`	`float64`	How much of the limit is used, from 0 to 100
↳ `window_minutes`	`int`	The length of the window the limit counts over
↳ `resets_at`	`string`	When the window resets, RFC 3339 in UTC

Example

name: Read back a Codex session
actions:
  - name: session
    component: machine:agent:session:read
    vars:
      agent: codex
      session_id: 0199b000-0000-7000-8000-00000000000a

outputs:
  messages: "{{ session.messages }}"
  turns: "{{ session.turns }}"
  subagents: "{{ session.subagents }}"
  tokens_in: "{{ session.session.usage.input_tokens }}"

Edit or read the source on GitHub