meticulous-use-session-data

Use this workflow to get structured session data from Meticulous — the recorded user flows and network mocks that cover your code changes.

Before starting, run the
meticulous-cli-update
skill to ensure the Meticulous CLI is up to date — unless it has already run earlier in this conversation, in which case skip it.

Step 1 — Find relevant sessions and download their data

Run the following command from the root of the git repository:

bash

meticulous local relevant-sessions --format=multi-file --minimum-times-to-cover-each-line=1

This will:

Identify which recorded sessions exercise the code paths changed on your current branch.
Download each session's data as a structured directory tree to
```
.meticulous/sessions/
```
.

Options:

Option	Type	Default	Description
`--format`	`multi-file`	—	Set to `multi-file` to download each relevant session's data as a structured directory tree
`--minimum-times-to-cover-each-line`	number	—	Select at least this many sessions to cover each edited line, choosing the most diverse subset when more candidates are available
`--outputDir`	string	`.meticulous/sessions`	Output directory for multi-file format
`--showMaybeRelevant`	boolean	`false`	Also show sessions that may be affected
`--startingPointSha`	string	—	Only consider changes since this commit SHA

Step 2 — Understand the output structure

The downloaded data is organized as follows:

.meticulous/sessions/
  manifest.json                       # List of all sessions with summary metadata
  sessions/
    <sanitized-session-id>/           # Special characters in session IDs are replaced for filesystem safety
      summary.json                    # Session overview: URL, viewport, duration, event count
      user-events.json                # Sequence of user interactions (clicks, typing, navigation)
      network-requests/
        summary.json                  # All network requests: method, URL, status (no bodies)
        <order>.json                  # Individual request/response pairs (with bodies)
      storage/
        cookies.json                  # Initial cookie state
        local-storage.json            # Initial localStorage state
        session-storage.json          # Initial sessionStorage (if present)
        indexed-db.json               # Initial IndexedDB (if present)
      url-history.json                # Page navigation history with timestamps
      context.json                    # Feature flags, user ID, custom context (if present)
      websockets/                     # WebSocket data (if present)
        summary.json                  # WebSocket connections overview
        <connection-id>.json          # Events for each connection

Step 3 — Navigate the data

Start with
manifest.json
to see all available sessions. Each entry includes the session ID, start URL, event count, duration, and network request count. Pick the session(s) relevant to your task.
Read
summary.json
inside a session directory for a quick overview of that session — the starting URL, viewport size, total duration, and number of events.
Read
user-events.json
to understand the user flow. Each event has:
- ```
type
```
  : the interaction type (e.g.,
```
click
```
  ,
```
input
```
  ,
```
scroll
```
  )
- ```
selector
```
  : the CSS selector of the target element
- ```
timestampMs
```
  : when the event occurred
- ```
coordinates
```
  : click position (if applicable)
Browse
network-requests/summary.json
to see all API calls made during the session. Each entry shows the HTTP method, URL, status code, content type, and response time — without response bodies, so it's quick to scan.
Read individual
network-requests/<order>.json
files for the full request/response data of specific API calls. Use these as mock data when writing tests. The
```
order
```
field in the summary corresponds to the filename.
Check
storage/
files if you need to understand the initial application state (cookies, localStorage, etc.).

Step 4 — Use the data for testing

Common use cases:

Understanding user flows

Read

user-events.json

to see the exact sequence of user interactions. This tells you what the user clicked, typed, and navigated, which helps you understand what your code change needs to support.

Creating network mocks

Use the network request files to create mock responses for your tests:

Read
```
network-requests/summary.json
```
to find the relevant API endpoints.
Read the individual
```
network-requests/<order>.json
```
files for the full request/response pairs.
Use the
```
response.content.text
```
field as mock response data in your tests.

Verifying coverage

Cross-reference the user events and network requests with your code changes to verify that the session covers the code paths you've modified.

Alternative: Download specific sessions

If you already know which session IDs you need, you can download them directly:

bash

meticulous download session --sessionId=<id> --format=multi-file

This writes to

.meticulous/sessions/

by default. Use

--outputDir

to change the output location.