session -- Treeship

A session groups related work into a single unit. When you close a session, Treeship composes a Session Receipt v1 and writes a portable .treeship package that can be inspected and verified offline, or uploaded to a hub for sharing at a permanent public URL.

See the Session Receipts concept page for the full format and determinism rules.

treeship session start

Start a new session.

treeship session start
treeship session start --name "fix auth bug"
treeship session start --actor agent://coder

Options

Option	Description
`--name <text>`	Human-readable session name
`--actor <uri>`	Default actor URI for attestations in this session

Starting a session writes .treeship/session.json, initializes an append-only event log at .treeship/sessions/<session_id>/events.jsonl, and emits a session.started event. All subsequent attestations and wrap calls are linked to the session.

treeship session status

Show the current session state.

treeship session status

Outputs session id, name, actor, started-at timestamp, artifact count verified against the chain, and the number of events in the session's event log.

If no session is active, exits cleanly with a hint to run session start.

treeship session close

Close the active session, compose the Session Receipt, and write a .treeship package.

treeship session close
treeship session close --summary "fixed JWT expiry bug"

Options

Option	Description
`--summary <text>`	Plain-text summary of what the session accomplished

On close, Treeship:

Appends a session.closed event to the event log.
Walks the artifact chain from .last back to the session's root artifact.
Composes a canonical Session Receipt v1 from the events, the artifact chain, and the agent graph.
Builds a .treeship package under .treeship/sessions/<session_id>.treeship/ with receipt.json, merkle.json, render.json, per-artifact inclusion proofs, and a static preview.html.
Signs a session.close chain artifact as before.
Prints the package path, the canonical receipt digest, and the Merkle root.

Example output:

✓ session receipt composed
  package:   .treeship/sessions/ssn_42e740bd9eb238f6.treeship
  digest:    sha256:942e6b2bfcbe860223fbae57ee7d9b73400a278ccfb0f1d5ca865aec9ce9aba6
  merkle:    mroot_effc020c67548f53
  files:     8

✓ session closed
  id:       ssn_42e740bd9eb238f6
  duration: 6m
  receipts: 2
  events:   2

After close, run treeship package verify against the package path to confirm the receipt is locally verifiable.

treeship session report

Upload a closed session's receipt to the configured hub and print the permanent public URL.

treeship session report
treeship session report ssn_42e740bd9eb238f6

Options

Argument	Description
`[session_id]`	Session ID to upload. Defaults to the most recently closed session's package under `.treeship/sessions/`.

The command:

Locates the .treeship package for the requested session (or the most recently modified one).
Reads receipt.json verbatim so the digest signed by session close is preserved bit-for-bit.
DPoP-signs a PUT {hub_endpoint}/v1/receipt/{session_id} request using the active hub connection's private key.
Prints the permanent receipt URL.

Example output:

✓ session receipt uploaded
  hub:      local
  session:  ssn_42e740bd9eb238f6
  agents:   1
  events:   2

  receipt:  https://treeship.dev/receipt/ssn_42e740bd9eb238f6

  → share this URL freely -- it never expires and needs no auth

The receipt URL is permanent and public. No token, no expiry, no auth required to fetch it. A2A clients, dashboards, and offline verifiers can all curl it programmatically. See GET /v1/receipt/{session_id} for the API reference.

What gets sealed in a receipt

A Session Receipt v1 includes:

Session metadata: id, name, mode, started-at, ended-at, duration, status
Participants summary: total agents, spawned sub-agents, handoffs, max delegation depth, hosts, tool runtimes
Agent graph: every agent instance with its role, host, depth, and edges (parent-child spawn, handoff, collaboration, return)
Timeline: all events in deterministic order (timestamp, sequence_no, event_id)
Side effects: files read, files written, ports opened, network connections, processes, tool invocations
Artifacts: chain entries with content-addressed ids
Merkle root + inclusion proofs over the artifact ids
Render hints for Explorer and the preview HTML

Events the session can capture include tool calls, file reads (via the daemon's sensitive-file watcher), file writes, network connections, process execution, agent spawning, handoffs, collaborations, and returns.

A session is auto-sealed: the chain of signed artifacts inside the session is what the receipt commits to via the Merkle root. The receipt itself is a human-readable summary on top of that cryptographic backbone.

session

On this page