Each conversion subcommand uses an adapter that reads a native session format and maps it to the minitrace schema. This page documents what each adapter reads, what gets preserved, what gets synthesized, and what is lost.

Source events and attachments

Minitrace now has two first-class primitives for source data that is not a conversational message or normalized tool call:

• events[] stores source-observed lifecycle/timeline facts such as compactions, permission-mode changes, title changes, subagent lifecycle signals, or rate-limit snapshots.
• attachments[] stores artifact references such as images, uploaded files, downloaded files, or future generated outputs. Attachments are references and bounded previews, not blob storage.

Adapters should use annotations for human or derived review notes. They should use events/attachments for facts that came from the source transcript itself.

Claude Code adapter

Source: JSONL v2 transcripts in ~/.claude/projects/ Source format: claude-code-jsonl-v2 (main), claude-code-jsonl-v2+subagent (subagent) Converter version: go-minitrace-claude-adapter-dev

What it reads

Claude Code stores one JSONL file per session. Each line is a JSON event with a type field. The adapter processes:

• Conversation messages → turns (user, assistant, system)
• Tool use blocks → tool calls with operation type mapping
• Tool result blocks → tool call outputs with success/error status
• Usage metadata → per-turn token counts (input, output, cache_read, cache_creation)
• Subagent directories → separate minitrace sessions with parent backlinking
• Lifecycle records → source events where they do not fit turns or tool calls
• Attachment records → attachment references plus optional timeline events

Additionally, dir-v1 tool-results sessions (an older format that stores tool results in a directory structure) are detected and converted.

Field mapping

Tool operation mapping

Subagent handling

When a session directory contains a subagents/ subdirectory, each subagent JSONL file becomes its own minitrace session. The parent session's Agent tool call receives a spawned_agent field with the subagent's sub_session_id. The subagent session's title is prefixed with [subagent].

Preserved framework-specific metadata

Claude Code now keeps additional raw metadata in minitrace without promoting it into shared schema fields:

• operational_context.framework_config.entrypoint
• turns[].framework_metadata:
  • entrypoint
  • slug
  • parent_uuid
  • is_sidechain
  • stop_reason
  • stop_sequence
  • cache_creation
• tool_calls[].framework_metadata:
  • caller
  • tool-result record context such as entrypoint, slug, parent_uuid, is_sidechain

What is not preserved

• System prompt content (set to null for privacy)
• Streaming event-level detail (only the final content is kept)
• Image and binary content (references only)

Codex adapter

Source: Session and exec JSONL files in ~/.codex/ Source format: codex-session-jsonl-v1 or similar Converter version: go-minitrace-codex-adapter-dev

What it reads

Codex stores sessions as JSONL files under ~/.codex/sessions/ and optionally logs exec operations as JSONL. The adapter processes:

• Session JSONL → conversation turns and tool invocations
• Exec JSONL → tool calls from codex exec --json output
• Command metadata → exit codes and execution metadata when present
• Tool-call arguments → command strings plus optional justification text
• Lifecycle/source signals → source events when they describe timeline facts outside turns
• Image-view signals → attachment references when a view_image tool call points at an image

Known limitations

• Older sessions with unrecognized formats produce unsupported Codex format hint: unknown-jsonl errors
• The adapter does not skip these automatically; it fails on the first unrecognized session

Preserved framework-specific metadata

Codex keeps richer raw metadata in the adapter-specific metadata/config fields:

• operational_context.framework_config:
  • approval_policy
  • detailed sandbox_policy
  • collaboration_mode_detail
  • truncation_policy
  • rate_limits
  • session_source
  • other session/runtime config such as originator, personality, reasoning_effort, timezone
• turns[].framework_metadata:
  • turn_id
  • phase
  • memory_citation
• tool_calls[].framework_metadata:
  • codex_function
  • justification (also promoted to input.justification)
  • source
  • parsed_cmd
  • stdout
  • stderr
  • status
  • turn_id
  • exit_code (also promoted to output.exit_code)

What is not preserved

• Some Codex source-specific records may still collapse into the nearest session/turn/tool representation until adapter-specific event mapping is fully implemented
• Binary exec output is truncated

Pi adapter

Source: JSONL v3 session files in ~/.pi/agent/sessions/ Source format: pi-agent-jsonl-v3 Converter version: go-minitrace-pi-adapter-dev

What it reads

Pi stores one JSONL file per session in workspace-named directories (e.g., --home-manuel-code-foo--/). Each line is a structured event. The adapter processes:

• User messages → user turns
• Assistant messages → assistant turns with model metadata
• Tool calls → tool calls with mapped operation types
• Tool results → tool call outputs
• Token usage events → per-turn usage counters
• Lifecycle records → source events for session info, compactions, model changes, thinking-level changes, and custom records as support is added

Field mapping

Tool operation mapping

Pi tools are mapped similarly to Claude Code:

Preserved framework-specific metadata

Pi now preserves additional raw metadata alongside the normalized schema:

• turns[].framework_metadata:
  • stop_reason
  • error_message
• tool_calls[].framework_metadata:
  • diff
  • first_changed_line

Single session conversion

Use --source-session to convert one specific JSONL file without scanning the full directory:

go-minitrace convert pi --source-session /path/to/session.jsonl --output-dir ./output

claude.ai adapter

Source: Privacy export ZIP from claude.ai Source format: claude-ai-privacy-export-v1 Converter version: go-minitrace-claudeai-adapter-dev

What it reads

The ZIP contains a JSON file with all conversations. Each conversation has an array of message objects. The adapter maps:

• Human messages → user turns
• Assistant messages → assistant turns
• Attachments → referenced in turn metadata
• Conversation metadata → title, model, timestamps

Filtering

Use --uuid-filter to convert only specific conversations by UUID prefix:

go-minitrace convert claude-ai --source export.zip --uuid-filter abc123,def456

What is not preserved

• File attachments (only references, not content)
• Rendering metadata
• Organization/workspace context
• Token usage (not available in the export format)

ChatGPT adapter (ZIP)

Source: Data export ZIP from ChatGPT Source format: chatgpt-export-zip-v1 Converter version: go-minitrace-chatgpt-adapter-dev

What it reads

The ZIP contains conversations.json with all conversations. The adapter processes the nested message tree structure that ChatGPT uses internally.

What is not preserved

• Tool call details (the ZIP export has limited tool information)
• Plugin/action metadata
• Image generation details (only text content is preserved)
• Token usage (not available in the export format)

ChatGPT adapter (JSON)

Source: Per-conversation JSON files Source format: chatgpt-json-transcript-v1 Converter version: go-minitrace-chatgpt-adapter-dev

What it reads

Each JSON file represents one conversation in a richer format than the standard export. The adapter extracts:

• Messages → turns with role mapping
• Tool calls → extracted from assistant messages
• Tool results → mapped to tool call outputs

This format includes tool call details that the standard export ZIP does not provide.

Filtering

Use --id-filter to convert specific conversations:

go-minitrace convert chatgpt-json --source-dir /tmp/exports --id-filter 69c7,69c8

turnsdb adapter

Source: SQLite turns.db from Geppetto/Pinocchio Source format: pinocchio-turns-sqlite-v1 Converter version: go-minitrace-turnsdb-adapter-dev

What it reads

The turns.db SQLite database stores conversation snapshots rather than individual turns. Each row is a full snapshot of the conversation at a point in time. The adapter:

1. Groups snapshots by conversation ID
2. Sorts snapshots chronologically
3. Diffs consecutive snapshots to extract the incremental turns
4. Maps the extracted deltas to minitrace turns and tool calls

This snapshot-diffing approach is fundamentally different from the other adapters and is necessary because the database does not store individual turn events.

Single conversation

Use --conv-id to convert one specific conversation:

go-minitrace convert turnsdb --source /tmp/turns.db --conv-id 5cf06c5f-0460-485e-a7c5-92d56af826f9

What is not preserved

• Snapshot-level metadata beyond what maps to minitrace
• Internal Pinocchio orchestration state
• Exact timing between turns (reconstructed from snapshot timestamps)

Quality grading across adapters

All adapters use the same quality grading logic after conversion:

See also

• go-minitrace help convert-commands — conversion command flags and usage
• go-minitrace help minitrace-schema — the target schema these adapters produce
• go-minitrace help framework-metadata-mappings — detailed per-adapter metadata preservation tables