The convert group reads native AI agent session stores and writes minitrace JSON archives. Each subcommand handles one source format.

All convert subcommands share these common behaviors:

• Output directory: --output-dir defaults to ./output. Sessions are written to output/active/YYYY-MM/<id>.minitrace.json.
• Manifest: A manifest.json is written at the output root and in each period directory with session metadata and statistics.
• Dry run: --dry-run inspects sources and reports what would be converted without writing files.
• Quality grading: Every session is assigned quality A, B, or C based on content richness.
• Path normalization: Home directory paths in tool call inputs are normalized to ~.
• Content truncation: Tool call outputs larger than 10 KB are truncated with a SHA-256 hash of the original.

convert claude-code

Converts Claude Code sessions from the local project store.

go-minitrace convert claude-code --source-dir ~/.claude/projects --output-dir ./output
go-minitrace convert claude-code --dry-run

What it reads: JSONL v2 transcripts, dir-v1 tool-results sessions, and subagent transcript files found in subagents/ subdirectories.

Subagent handling: When a session contains subagent transcripts, each subagent becomes its own minitrace session with source_format: claude-code-jsonl-v2+subagent. The parent session's Agent tool call carries a spawned_agent field linking to the subagent's session ID.

Source format values: claude-code-jsonl-v2 for main sessions, claude-code-jsonl-v2+subagent for subagent sessions.

convert codex

Converts Codex sessions from the local session store.

go-minitrace convert codex --source-dir ~/.codex --output-dir ./output

What it reads: Session JSONL files from ~/.codex/sessions/ and exec JSONL files from codex exec --json output.

Known limitation: Older Codex sessions with unrecognized JSONL formats produce an unsupported Codex format hint: unknown-jsonl error. These sessions are skipped by the discovery phase but cause a hard error if the converter encounters them.

Source format value: codex-session-jsonl-v1 or similar depending on the detected format.

convert pi

Converts Pi agent sessions from the local session store.

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

What it reads: JSONL v3 session files. The directory structure uses workspace-encoded paths like --home-manuel-code-foo--/.

Source format value: pi-agent-jsonl-v3.

convert claude-ai

Converts a claude.ai privacy data export into minitrace sessions.

go-minitrace convert claude-ai --source ~/Downloads/data-2026-03-29-11-53-11-batch-0000.zip --output-dir ./output
go-minitrace convert claude-ai --source ~/Downloads/export.zip --uuid-filter abc123,def456

How to get the export: On claude.ai, go to Settings → Privacy → Export data. You will receive a ZIP file by email.

What it reads: The ZIP contains a JSON file with all conversations. Each conversation becomes one minitrace session.

Source format value: claude-ai-privacy-export-v1.

convert chatgpt

Converts a ChatGPT data export ZIP into minitrace sessions.

go-minitrace convert chatgpt --source ~/Downloads/chatgpt-export.zip --output-dir ./output
go-minitrace convert chatgpt --source ~/Downloads/export.zip --id-filter 69c7,69c8 --dry-run

How to get the export: On ChatGPT, go to Settings → Data controls → Export data. You will receive a download link by email.

What it reads: The ZIP contains conversations.json with all conversations. Message parts are assembled into turns.

Source format value: chatgpt-export-zip-v1.

convert chatgpt-json

Converts per-conversation ChatGPT JSON transcript files. This is a different, richer format than the standard account export.

go-minitrace convert chatgpt-json --source-dir /tmp/chatgpt-exports --output-dir ./output
go-minitrace convert chatgpt-json --source-dir /tmp/exports --id-filter 69c7 --dry-run --output json

What it reads: Each JSON file represents one conversation. This format includes tool call details that the standard export ZIP does not.

Source format value: chatgpt-json-transcript-v1.

convert turnsdb

Converts a Geppetto/Pinocchio turns.db SQLite database into minitrace sessions.

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

What it reads: The SQLite database stores conversation snapshots. The converter reconstructs logical conversation deltas from canonical turn snapshots using a diffing algorithm, rather than treating each stored row as a separate transcript turn.

Source format value: pinocchio-turns-sqlite-v1.

Output directory structure

After conversion, the output directory looks like this:

output/
├── manifest.json                       # Root manifest with all sessions
└── active/
    ├── 2026-02/
    │   ├── <id>.minitrace.json        # One file per session
    │   ├── <id>.minitrace.json
    │   └── manifest.json              # Period manifest
    └── 2026-03/
        ├── <id>.minitrace.json
        └── manifest.json

Sessions are bucketed by the month they started. The root manifest.json contains aggregate statistics (total sessions, breakdowns by profile/quality/classification, date range).

Troubleshooting

See also

• go-minitrace help what-is-minitrace — conceptual overview of the pipeline
• go-minitrace help discover-commands — inspect sources before converting
• go-minitrace help minitrace-schema — understand the output format
• go-minitrace help adapter-reference — detailed per-adapter conversion behavior