txcript 0.12.1

Start a session in Claude Code, hit a usage limit or a wall, and pick it up in Codex with the full conversation, reasoning, and tool history intact:

txcript maps each harness's native transcript format through a typed common model. Native load/save is byte-lossless; cross-harness conversion preserves messages, reasoning, tool calls, tool results, images, metadata, and usage where available. It ships as a CLI, a Rust crate, and an npm package.

Highlights

• 16 harnesses, one model: every format converts through Transcript<Common>, so adding a harness connects it to all the others.
• A format for everyone else: agents txcript has never heard of emit the documented Simple interchange JSON — a file or a stream, handed to txcript directly — and their transcripts continue in any supported harness.
• Byte-lossless round-trips: loading and saving a session in its own format reproduces it exactly.
• Continue anywhere: txcript continue <id> --with <harness> rewrites a session into another harness's native format and launches it. The original is never modified.
• Search everything: literal, case-insensitive search across every session on the machine (powered by nucleo), as a library API, a one-shot CLI query, or an interactive picker.
• MCP server: txcript mcp exposes read-only list_sessions, search_sessions, and read_session tools, so agents can mine past sessions as context.
• Documented formats: every harness's on-disk format is written up in docs/formats/, with provenance for each claim (official docs, source permalinks, or reverse-engineering notes).

Supported harnesses

flowchart LR
    claude["Claude Code"] <--> common(("Transcript&lt;Common&gt;"))
    claudechat["Claude Chat"] --> common
    chatgpt["ChatGPT"] --> common
    cowork["Cowork"] <--> common
    codex["Codex"] <--> common
    opencode["OpenCode"] <--> common
    pi["pi"] <--> common
    campfire["Campfire"] <--> common
    common <--> cursor["Cursor CLI"]
    common <--> cursordesktop["Cursor desktop"]
    common <--> grok["Grok CLI"]
    common <--> fx["fx"]
    common <--> antigravity["Antigravity"]
    simple["Simple (any agent)"] --> common
    hermes["Hermes Agent"] --> common
    amp["Amp"] --> common

Discovery, listing, search, and view work for every harness with a backing store. The id strings are what the CLI and WASM APIs take.

1 Amp threads are server-side and the CLI has no import: sessions convert from Amp, but can't be continued into it.

2 Simple is txcript's own interchange format — the on-ramp for any agent not listed above. There is no app and no managed directory: a Simple session is a document (a file, or stdin) handed to txcript continue directly, and the continued conversation lives in the target harness from then on.

3 Hermes's state.db is read-only in txcript and Hermes has no session-import command: sessions convert from Hermes, but can't be continued into it.

4 Claude Chat is a live, pull-only source. On macOS, explicitly selecting --from claude_chat reuses the signed-in Claude Desktop session automatically; aggregate discovery does not contact Claude Chat. Environment-supplied session and Cloudflare credentials are rejected in V1. An optional TXCRIPT_CLAUDE_CHAT_ORGANIZATION_UUID restricts discovery, while Desktop auth otherwise uses the app's active organization. Direct Rust calls to ClaudeChatStore::discover() produce a compile-time warning that discovery uses an undocumented private endpoint Anthropic can observe or restrict. txcript performs GET requests only and refuses save, delete, same-harness continue, and --with claude_chat. Generated files presented on the active branch become Common artifact blocks; Claude Code conversions materialize them beside the generated session and use Claude Code's native Artifact tool. Claude's data-export ZIP and conversations.json are not supported.

5 ChatGPT is a live, pull-only source. Like Claude Chat reuses Claude Desktop, explicitly selecting --from chatgpt automatically reuses the ChatGPT login managed by Codex at CODEX_HOME/auth.json or ~/.codex/auth.json; the account may differ from the one signed in through a browser. txcript only reads that credential file and never refreshes or rewrites it. Aggregate discovery does not contact ChatGPT, while an exact conversation UUID can be read directly without enumerating the account. Conversation traffic is GET-only, and txcript refuses save, delete, same-harness continue, and --with chatgpt. ChatGPT exposes no supported conversation API, so the private endpoint and Codex auth contract may change or be restricted. ChatGPT data-export archives are not supported.

Install

CLI (installs the txcript binary):

cargo install --git https://github.com/skillsynchq/txcript txcript-cli
# or from a checkout: cargo install --path cli

Rust crate:

cargo add txcript

npm package (prebuilt WASM, no Rust toolchain needed):

bun add txcript     # or: npm install txcript

CLI

Discover local sessions and continue one in any harness:

txcript list                             # local sessions across every harness
txcript continue <id>[#range]            # continue <id>, then launch its harness
    [--with <harness>]                    #   ...continuing in <harness> instead
    [--from <harness>]                    #   scope the id lookup to one harness
    [--out <dir>]                         #   write under <dir>; implies --no-resume
    [--no-resume]                         #   write the session but don't launch
txcript continue <file|->[#range]        # continue a Simple document instead:
    --with <harness> [...]                #   a file, or stdin (`-`), from any agent
txcript view <id>[#range]                # print a session as compact text
    [--from <harness>]                    #   scope the id lookup to one harness
txcript export <id>[#range]              # write a session as a Simple document
    [--from <harness>]                    #   scope the id lookup to one harness
    [--out <file>]                        #   write to <file> instead of stdout

continue writes the session where the target harness keeps its sessions, then launches that harness on it, handing over the terminal:

• Same-harness: resumes the original in place.
• Cross-harness (--with): re-synthesizes the session into the target's native format. What is written is always a copy; the source session is never modified or removed.
• A Simple document instead of an id — txcript continue ./run.json --with claude_code, or my-agent | txcript continue - --with claude_code — brings any agent's transcript in the same way; --with is required since a document has no harness of its own.
• The launch command is per-harness and overridable: set TRANSCRIPT_<HARNESS>_RESUME_CMD to a {id} template, e.g. TRANSCRIPT_CODEX_RESUME_CMD="codex resume {id}".

view prints the session as compact text, each message numbered by a ── #N ── rule. #range selects messages by those printed ordinals, 1-based and inclusive:

• abc#7: message 7 only
• abc#5-12: messages 5 through 12
• abc#5-: message 5 to the end
• abc#-10: start through message 10

continue accepts the same suffix and continues just those messages as a new session. A range that would cut a tool call away from its result is refused, and the error suggests the nearest valid range.

export writes the session as a Simple document, to stdout or --out <file>. The document is the full rendering of the canonical model — everything continue carries between harnesses — detached from any harness's store, so it moves between machines as a file:

txcript export 0dc114bf --out session.json       # on this machine
txcript continue ./session.json --with claude_code   # on the other one

The recorded working directory is kept when it exists on the importing machine and otherwise replaced by the directory continue runs in. export accepts the same #range suffix and --from scope as view.

Search

txcript query 'relay bug'                # one-shot: ranked hits, highlighted
txcript query                            # interactive picker; Enter continues
    [--from <harness>]                   #   search only <harness> (default: all)
    [--with <harness>]                   #   continue the pick in <harness>

A pattern matches literally and case-insensitively: relay bug finds lines containing that exact text, spaces and all.

The picker is dependency-free (raw-mode ANSI): type to filter, arrows / ctrl-p/n to move, Enter to continue the selection in its own harness (or --with), Esc to cancel. Every row shows which kind of content matched: user text, assistant text, thinking, tool use, tool output, or session metadata.

MCP server

txcript mcp                              # stdio transport

Exposes three read-only tools; their optional filters match the CLI:

• list_sessions(from?, cwd?)
• search_sessions(pattern, from?, cwd?)
• read_session(id, from?)

* Omitting from includes every harness; omitting cwd applies no directory filter. Sessions without a recorded working directory match only when cwd is omitted.

Shell completions

txcript completion zsh > ~/.zfunc/_txcript      # or wherever your fpath looks
source <(txcript completion bash)               # bash, ad hoc
txcript completion fish > ~/.config/fish/completions/txcript.fish

From a checkout, cli/prep.sh installs the binary and wires the completions into ~/.zshrc and ~/.bashrc; it also offers to bind ctrl+shift+r to txcript query --cwd ., a session picker scoped to the current folder (--picker / --no-picker skip the prompt).

Rust crate

[dependencies]
txcript = "0.6"
# Drops the OpenCode SQLite store (rusqlite); the OpenCode codec stays available.
# txcript = { version = "0.6", default-features = false }

Three layers, smallest to largest:

• Codec: to_common / from_common per harness; convert::<A, B> chains them through the canonical model.
• TextCodec: from_text / to_text to parse and render a harness's native session text, no I/O.
• Store: discover/load/save against a real backend (session directories, or SQLite DBs for OpenCode and both Cursors).

Convert in memory (no filesystem):

use txcript::harness::{claude_code, codex};
use txcript::{Codec, TextCodec, convert};

let claude = claude_code::ClaudeCode::from_text(jsonl_text)?;          // Transcript<ClaudeCode>
let codex = convert::<claude_code::ClaudeCode, codex::Codex>(&claude)?; // Transcript<Codex>
let codex_text = codex::Codex::to_text(&codex)?;                       // native rollout JSONL

Or go through disk with a Store:

use txcript::harness::{claude_code, codex};
use txcript::{Store, convert};

let store = claude_code::ClaudeStore::default_root().expect("home dir");
let found = store.discover()?;                       // cheap metadata scan
let claude = store.load(&found[0].reference)?;       // Transcript<ClaudeCode>

let codex = convert::<_, codex::Codex>(&claude)?;
codex::CodexStore::default_root().expect("home dir").save(&codex)?;  // resumable on disk

The canonical model is Transcript<Common>: Meta + Vec<Message>, where a Message holds typed Blocks (Text, Thinking, ToolUse, ToolResult, Image) and a typed Tool enum.

Slash commands the user ran at the harness (/release patch) are canonical too: a Tool::Command call on the user turn, paired with what the command printed back as its ToolResult.

Search (feature search, on by default)

txcript::search supports fuzzy and substring search over transcripts via nucleo. One-shot search:

use txcript::search::{Query, search};

let hits = search(&common, &Query::substring("relay bug"));  // or Query::fuzzy for fzf syntax
for hit in hits {
    // hit.origin: User | Assistant | Thinking | ToolUse | ToolResult | Meta
    // hit.span addresses the message; hit.highlights are char ranges into hit.line
    let messages = common.fragment(&hit.span);            // zero-copy: Option<&[Message]>
}

For picker-style search, build an Index once and query it per keystroke:

use txcript::search::{DocKey, Index, Query};

let mut index = Index::new();
index.insert(DocKey { harness, id }, &common);   // re-insert replaces; caller owns refresh
let matches = index.query(&Query::fuzzy("srch")); // ranked docs, best lines as hits

An empty pattern returns documents newest-first. Tool outputs are excluded by default; use Origin::ALL to include them. Query.harnesses, Query.limit, and Query.hits_per_doc narrow results.

Text projection

txcript::text::to_text(&common) is the projection behind txcript view: a one-way, token-conscious rendering of Transcript<Common> for use as LLM context. It keeps messages, reasoning text, and compact tool calls/results; replay-only payloads (encrypted reasoning, usage accounting, inline image bytes) are omitted. to_text_fragment(&common, &span) renders a Span of the body, keeping each message's ordinal in the full session.

npm package

The npm package ships the codec as prebuilt WASM for Bun, Node, and browsers. The JS host owns all I/O and calls in for the transformation; the Store layer (filesystem, SQLite, subprocess) stays native and is excluded from the WASM build.

import { convert, toCommon, fromCommon, harnesses } from "txcript";
import { readFileSync, writeFileSync } from "node:fs";

const input = readFileSync("rollout.jsonl", "utf8");

// native -> native (e.g. a Codex rollout into Claude Code's JSONL)
writeFileSync("session.jsonl", convert(input, "codex", "claude_code"));

// canonical view, and back
const common = JSON.parse(toCommon(input, "codex"));   // { meta, messages }
const pi = fromCommon(JSON.stringify(common), "pi");

harnesses(); // ["claude_code","claude_chat","chatgpt","codex","opencode","pi","campfire","cursor","cursor_desktop","grok","fx","hermes","amp","antigravity","simple","cowork"]

Text-in / text-out: input is the source harness's native session text and the result is the target's. Invalid harness names or unparseable input throw a JS Error.

To build the wasm from source instead:

git clone https://github.com/skillsynchq/txcript.git
cd txcript
bun run setup        # once: wasm target + wasm-bindgen-cli
bun run build        # produces ./pkg

Format documentation

Not all of these transcript formats are documented by their vendors. docs/formats/ has one document per harness covering where sessions live on disk, how discovery finds them, a dissection of every part of the format, and its quirks, each tagged with the provenance of what it claims: official documentation, the harness's own open-source serialization code (cited with commit-pinned permalinks), or reverse engineering.

Development

cargo test                                          # native suite
cargo test --no-default-features                    # without the SQLite store
bun run build && bun examples/convert.ts <file> <from> <to>
git config core.hooksPath .githooks                 # pre-push runs the CI checks

The binary lives in its own workspace crate (cli/, package txcript-cli) so its dependencies (clap) never touch library consumers.

License

Apache-2.0