Specification: https://atxf.leostera.dev
ATXF is a JSON Schema and JSONL format for exchanging coding-agent session transcripts between tools such as Pi, Codex, Claude Code, OpenCode and Gemini CLI.
Status: v0.1 draft. Expect breaking changes until v1.
Every coding agent stores sessions differently: in-file trees, Responses-API rollouts, Anthropic message logs, SQLite event stores, op logs. Existing interchange formats such as ATIF linearize sessions for evaluation, which loses branches, rewinds and compaction semantics.
ATXF aims to be general enough to hold any of these formats without losing their structure. For example, ATXF has a branching tree, OpenCode records tool lifecycles and Codex records turn policies. Each source record can also be carried verbatim alongside, so a converter can go back to the original format.
- One JSONL file per transcript. The first line is a
transcriptheader. Records are append-only. - A tree. Records link through
id/parentId, and branches are never deleted. Rewinds, rollbacks and reverts becomeleafmoves. - Three layers on one tree:
- context: what the model saw (
message,context,compaction,context_edit,branch_summary). - state: under which settings (
settings). - events: what happened around the model (
turn,tool_status,usage,checkpoint,agent_link,custom).
- context: what the model saw (
- Provider-neutral messages. Roles are
system | user | assistant | tool. Content blocks aretext | image | resource | reasoning | tool_call. - Opaque replay data (thinking signatures, encrypted reasoning) travels in
replay. It is passed back only to the provider that produced it. - Lossless escape hatch.
nativecarries the verbatim source records;extandcustomcarry namespaced extras. - Fidelity is declared, not guessed. The header says what the producer could capture: topology, instructions, reasoning, and so on.
- Tamper-evident, like Git. With
integritydeclared, each record's hash commits to its content and to the hashes of the records it references.sealrecords commit to the whole file, and a record can be proven to belong to a transcript from digests alone.
{"type":"transcript","atxf":"0.1","id":"t1","time":"2026-10-29T12:00:00Z","source":{"agent":"pi"}}
{"type":"message","id":"e1","parentId":null,"time":"2026-10-29T12:00:01Z","role":"user","content":"What does README.md say?"}
{"type":"message","id":"e2","parentId":"e1","time":"2026-10-29T12:00:03Z","role":"assistant","content":[{"type":"tool_call","id":"call-1","name":"read","arguments":{"path":"README.md"}}],"stop":"tool_use"}
{"type":"message","id":"e3","parentId":"e2","time":"2026-10-29T12:00:03Z","role":"tool","toolCallId":"call-1","content":"# Demo"}| Path | What |
|---|---|
SPEC.md |
Normative semantics: tree, active leaf, context building, compaction, usage, replay |
schema/v0.1/atxf.schema.json |
JSON Schema (draft 2020-12) for one record (one line) |
docs/mappings.md |
How Pi, Codex, Claude Code, OpenCode, Gemini CLI and ATIF map onto ATXF |
examples/ |
Example transcripts in the style of each source |
packages/atxf-ts/ |
@leostera/atxf: types, validator, hashes and seals, context building, lossless converters for Pi, Claude Code, Codex, OpenCode and Gemini CLI (@leostera/atxf/pi, …), reconciliation (@leostera/atxf/reconcile) and the atxf CLI |
packages/atxf-rs/ |
The atxf Rust crate and binary: the same API, writing the same bytes and hashes as @leostera/atxf |
scripts/ |
cross-check.sh and cross-check-generated.ts: the TypeScript and Rust implementations must agree byte for byte |
fixtures/ |
Native session files per agent, shared by the tests |
specs/ |
Feynman models of distributed behaviour: reconcile.ts (copies of a session reconciled into one tree), stream-resume.ts (a live Pi session read across evictions and deploys) |
sites/atxf.leostera.dev/ |
The specification website (Astro + Kumo), deployed to https://atxf.leostera.dev |
npx @leostera/atxf validate path/to/session.atxf.jsonl # Node 22+, or bunx
npx @leostera/atxf convert --from pi --to codex session.jsonl > rollout.jsonl
npx @leostera/atxf reconcile studio.atxf.jsonl laptop.atxf.jsonl > merged.atxf.jsonlIn this repository, bun run atxf runs the same CLI from source:
bun install
bun run atxf validate path/to/session.atxf.jsonl
bun run atxf convert --from pi --to codex session.jsonl > rollout.jsonl
bun run check # typecheck and testsFrom Rust, the crate has the same converters and commands:
cargo install --path packages/atxf-rs
atxf convert --from pi --to codex session.jsonl > rollout.jsonluse atxf::{formats, Converter};
let transcript = formats::PI.to_atxf(&std::fs::read_to_string("session.jsonl")?, true)?;
let rollout = formats::CODEX.from_atxf(&transcript, true)?;import { buildContext } from "@leostera/atxf";
import { reconcile } from "@leostera/atxf/reconcile";
import { pi } from "@leostera/atxf/pi";
import { codex } from "@leostera/atxf/codex";
const transcript = pi.toAtxf(await Bun.file("session.jsonl").text());
const rollout = codex.fromAtxf(transcript); // Codex can continue it; reading it back gives `transcript`The Pi extension and the OpenCode plugin add /atxf export,
/atxf import and /atxf join <file>. Agents that join the same file share one session: each pushes its turns
when it finishes them and pulls the others' turns while it is idle.
pi install npm:@leostera/pi-atxf
opencode plugin add @leostera/opencode-atxfbun run e2e runs both with scripted models, in temporary directories.
Packages have their own versions. The format version they implement is separate: ATXF_VERSION (written) and
ATXF_VERSIONS (accepted) in @leostera/atxf and the atxf crate, and atxf.protocols in each package's
package.json. Every package today implements ATXF 0.1. ATXF 0.2, which adds attribution, is a proposed draft: SPEC-v0.2.md, from RFD0001.
- Conformance fixtures for the reference
buildContext(SPEC §5). - Signed seals.
- ATXF to ATIF.
- Streaming converters for every format; Pi streams, resumable from a saved state, in
@leostera/atxf(pi.stream) and theatxfcrate (PiStream); the others do not yet.
MIT