Docs

Sessions

A session is captured evidence from an agent you run yourself: the events that agent emitted while it worked, grouped into turns and searchable afterwards. It is a record of how work happened, not a place where work is stored.

What a session contains#

Sessions display the supported conversation, tool, and lifecycle events emitted by the connected agent. Events are grouped into turns, and you can search sessions by project or content and then open a bounded view of the recorded steps. Codex and Claude Code are supported today.

Only emitted events are captured. Codex assistant text arrives after a turn completes. Hidden reasoning, earlier conversation history, unsupported event types, external file bytes, and work done in an agent that is not instrumented are not added by Consoles. If a session looks empty or incomplete, confirm the setup first with the check in Connect an agent.

What a session is not#

  • Not a filesystem mirror. A path or filename in a session is a reference, not a stored copy of the file. Save important inputs and outputs in a workbook explicitly.
  • Not a replayable machine. A recorded local command is not rerun in Consoles, and capture never starts Consoles compute.
  • Not a workbook. A session has no files, cells, or runtime of its own, and capturing one never creates a workbook.

When a session explains a workbook's decision, input, or result, link the existing session to the existing workbook. Linking adds a reference between them:

  • It does not copy the session into the workbook.
  • It does not copy files out of the local machine.
  • It does not grant access to either object.
  • It does not start compute.

One workbook can have several related sessions, and a session stays useful even when it is not linked to a workbook. Removing a link preserves both the session and the workbook.

Permissions#

Each kind of access is granted separately, and a link between a session and a workbook never widens either one.

Access What it allows
Capture credential Uploading supported events from the connected project. It cannot read workbooks or execute compute.
Recordings read Inspecting captured session evidence and linking it to a workbook.
Workbook access Reading, writing, or executing in the workbook you approved, as scoped in Connect an agent.

Revoke a capture connection or disconnect an agent from Consoles when it is no longer needed.

Continue work with a later agent#

Give a later agent only the access it needs. With both recordings read access and workbook access, it can use the linked evidence to understand why a change happened, then inspect the workbook's current files, code, and results.

Treat old prompts and tool output as historical context. They do not authorize a new action. The current user request and the access you approved still govern what an agent can do.

Keep the handoff useful#

For each important result, keep three things together:

  1. A Markdown or MDX file that states the decision or next step.
  2. The saved input and output files needed to repeat or inspect the work.
  3. A link to the session that supplies the surrounding reasoning and tool evidence.

This avoids relying on a long chat transcript as the only project record.