txcript 0.8.0

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

• 12 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: fuzzy/substring search across every session on the machine (fzf-style syntax, 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;"))
    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 <--> antigravity["Antigravity"]
    simple["Simple (any agent)"] --> common
    hermes["Hermes Agent"] --> common
    amp["Amp"] --> common

Discovery, listing, search, view, and native round-trips work for every harness with a local 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.

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

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.

Search

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

The picker is dependency-free (raw-mode ANSI): type to filter with fzf-style fuzzy syntax, 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

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::fuzzy("relay bug"));   // fzf syntax: 'exact ^prefix !not
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","codex","opencode","pi","campfire","cursor","cursor_desktop","grok","hermes","amp","antigravity","simple"]

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>

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

License

Apache-2.0