Skip to content

For the complete documentation index, see llms.txt.

Trace object and sources

PIG reads native session files on an enrolled host and sends their contents to your analyzer. The analyzer stores the raw records and builds a canonical trace, a common representation of one agent session. The canonical trace lets analysis work across different native formats while the raw records keep the original evidence.

The collector supports four source families. Startup and terminal hooks can supply a transcript path directly. Background catch-up also discovers files in the following locations:

SourceHost valueDefault discovery locations
Claude Codeclaude~/.claude/projects/**/*.jsonl
Codexcodexsessions/**/*.jsonl and archived_sessions/**/*.jsonl beneath CODEX_HOME, or ~/.codex when unset
Claude Desktopclaude-desktop**/audit.jsonl beneath the two supported session directories in Claude’s application data
CursorcursorDesktop transcripts under ~/.cursor/projects/*/agent-transcripts/**/*.jsonl, plus the Cursor session database (see platform paths below)

For Claude Desktop, the supported session directories are local-agent-mode-sessions and claude-code-sessions. Their parent application directory depends on the operating system:

PlatformClaude application directory
macOS~/Library/Application Support/Claude/
Windows%APPDATA%/Claude/, or ~/AppData/Roaming/Claude/ when APPDATA is unset
Linux$XDG_CONFIG_HOME/Claude/, or ~/.config/Claude/ when XDG_CONFIG_HOME is unset

For Cursor, the collector reads the desktop session database. Its default location depends on the operating system, and PROMPTLESS_CURSOR_DATABASE overrides it:

PlatformCursor session database
macOS~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
Windows%APPDATA%/Cursor/User/globalStorage/state.vscdb, or ~/AppData/Roaming/Cursor/User/globalStorage/state.vscdb when APPDATA is unset
Linux${XDG_CONFIG_HOME:-~/.config}/Cursor/User/globalStorage/state.vscdb

The Cursor collector exports selected messages, tool arguments, saved tool results, and session identity from that database. It leaves out whole application rows and encryption metadata. Content that is missing, pruned, unsupported, interrupted, or oversized gets a capture marker, and transcript text serves as a degraded fallback. The collector writes what it captures to journals under ~/.promptless/instruction-hub/cursor/journals/ and uploads them with the same byte-range acknowledgments as other sources. It stops collecting at 128 MiB per journal, 1 GiB of journals in total, 4,096 journals, or 4,096 pending lifecycle notifications. It does not delete journals automatically.

These are discovery paths implemented by the collector. They do not mean every agent application is available on every platform or writes every listed format. Claude Desktop collection depends on the audit files being present and readable.

Claude Code’s generated hooks also attempt local Claude Desktop collection. Codex and Cursor use their own generated hooks. Gemini currently distributes instructions without native trace collection. See Supported agents for the distinction.

The collector records each source’s progress in a local ledger at ~/.promptless/instruction-hub/host-runtime-ledger.json. Each upload moves through these stages:

StageBehavior
ReadThe collector reads new byte ranges, compresses their contents with gzip, and base64-encodes them for transport.
SendThe collector sends authenticated batches to the analyzer’s POST /v0/traces/batches?target=<host> endpoint, where <host> is a host value from Native sources.
StoreThe worker validates the source and target, stores the native data, and returns acknowledged ranges.
Advance progressOnly a matching acknowledgment advances the host’s recorded progress.
RetryA retry can resend a range whose response was lost. If the worker already accepted part of that range, the runtime checks the worker’s content proof before reconciling its offset.

When the collector first discovers a file, collection can begin at the file’s start, so first enrollment can upload existing history. Catch-up skips very recent files while they’re inside the collector’s idle grace period. A hook’s explicit transcript path takes priority.

Don’t edit the ledger to force an upload, and don’t treat an HTTP success alone as evidence that analysis completed. Keep native files intact while you resolve an outage. File truncation, replaced content, malformed records, and oversized records each need accounting beyond advancing a byte counter.

The analyzer stores raw native artifacts in your trace bucket and maintains canonical session objects alongside them. PostgreSQL holds the associated metadata, ingestion progress, and analysis state.

A canonical object uses schema_version: 1 and contains these top-level fields:

FieldMeaning
schema_versionThe canonical object format version
sessionSource and session identity, agent type, observed models, and optional repository or parent-agent context
lifecycleSession state and timestamps, with native event time separate from ingestion time
sourcesSource file identities, raw artifact references, observed offsets, ingestion counts, and skipped or truncated content counts
rollupsObserved token usage, tool counts, compactions, and record accounting
context_artifactsTrace observations of instructions used, such as skill invocations or instruction-file references
preambleEvents before the first turn
pendingEvents not yet attached to a turn
turnsOrdered turns containing the session’s events

context_artifacts records what the trace reveals. It is separate from the instruction and repository snapshot prepared for analysis, described in Trust and data model.

Events have a kind, a global sequence number seq, and source evidence where available. The kinds are:

KindContent
user_messageUser input that opens a turn
assistant_messageAssistant output, with its observed audience where available
reasoningReasoning content exposed by the native trace
tool_callA tool invocation and its input
tool_resultA tool’s output or error
compactionA compaction summary
session_eventSession lifecycle or other agent machinery
otherA record not represented by a more specific event kind

Sequence numbers are contiguous in document order. Native events carry a src reference identifying their source entry, record, and byte offset. When the canonical view truncates a payload inline, the original uploaded bytes remain in the referenced raw artifact. Unknown event kinds and malformed records are different cases; parse coverage records what could not be decoded or modeled.

To trace an Acme pilot session through the analyzer, run these checks in order:

CheckWhat it shows
Source and session IDThe session reached the analyzer. If it never arrives, start with the host’s enrollment and collection checks.
Raw artifactsThe native data is stored in your trace bucket.
Ingestion and parse gapsWhich content the analyzer skipped, truncated, or couldn’t decode or model.
Analysis run statusWhether analysis completed. A stored trace can still be waiting for the quiet period, repository resolution, or model access.

To investigate each stage, see Observability.