HeadlessCode stores imported or native session archives under the workspace's shared session store. headlesscode sessions list shows archive metadata; show prints an archive, export writes JSON to stdout or a new path, and fork creates a separate archive. import always creates a new archive and leaves the source file unchanged.
Archives use schema version 1 and live under <HEADLESSCODE_DATA_DIR>/projects/<project-key>/sessions/, or the normal HeadlessCode data directory when the override is unset. Git worktrees of the same repository share that project key. Records use UUID filenames, owner-only directory and file permissions, atomic replacement, and revision checks that reject concurrent overwrites. A crashed writer can leave a lock; inspect that writer and lock before removing it and retrying. Each archive is limited to 16 MiB and 50,000 messages.
Continue an archive with headlesscode chat --resume <id> --workspace <path>. The selected workspace remains the execution workspace even when an archive records an earlier worktree path. Archives are editable conversation records; the separate evidence collector remains the source of authenticated execution evidence. Continuation sends up to 64,000 characters of recent history as labelled reference text. It excludes historical system/developer instructions and opaque data, and reports any shortening without changing the saved archive.
Use headlesscode sessions discover --from claude|codex to list candidate source files. Discovery shows file paths, modification times, and sizes; it does not print transcript messages. By default it scopes Claude files to the current workspace's Claude project directory and filters Codex rollouts by their workspace metadata. An explicit Claude --source-root still filters transcript records by their cwd unless --all is supplied. Muse's documented durable envelope does not specify a workspace-association metadata schema, so discovery fails closed; use headlesscode sessions discover --from muse --source-root <path> --all to scan a selected directory, or import a selected file directly. Muse logs use the XDG data directory under muse/sessions/YYYY/MM/DD/<session-id>/session.jsonl. --source-root selects a provider-specific directory. --all disables workspace filtering and requires an explicit source root for Muse.
Import one selected file with headlesscode sessions import --from <provider> --file <path>. Imported records retain their chronological text, supported tool calls and results, timestamps, and source provenance (provider, original session ID when present, source path, SHA-256 digest, and import time). Imported history is labeled unverified. Tool history is context only; imports do not replay calls or restore permissions, approvals, credentials, configuration, budgets, or outstanding jobs. Plaintext reasoning and media payloads are omitted; encrypted reasoning and safe media reference metadata may be retained as opaque archive data and excluded from continuation context. Unsupported or malformed records produce warnings; bounded opaque content is kept when it can be inspected safely.
Adapters accept Claude Code transcript JSONL, Codex rollout JSONL, Muse session JSONL, and Muse export JSON documents with export_schema_version: 1. Muse v1 exports contain ordered events with recorded envelopes; the importer maps committed run prompts, tool results, and assistant messages. Provider storage formats can change. The Claude CLI reference documents session resume behavior, and the Codex developer command reference documents saved interactive sessions and rollouts; neither is a schema guarantee. The Muse audit and replay references document its JSONL envelope and export event structure. See Claude CLI reference, Codex developer commands, Muse audit and resume, and Muse deterministic replay.
The importer reads source files with byte, line, line-length, and JSON-depth limits. Discovery limits traversal depth and entries, ignores symlinks, and never scans arbitrary home-directory files. Select provider session files explicitly when discovery cannot identify a workspace association.