sctxx

Session ConTeXt eXtractor. Turn a finished coding-agent session into a warm start for any other coding agent.

You hit a context limit in Claude Code, or you want to continue yesterday's Codex work in Pi. The transcript is on disk — often hundreds of megabytes of tool output — and pasting it into a new session is neither possible nor useful.

sctxx reads that transcript and writes a compact, verified, provenance-linked handoff artifact the next agent can load instead.

cargo install sctxx
sctxx skill install          # teach your agents when to use it

Then, from inside any agent:

use sctxx to extract session 7c1e8f82 from claude code and continue here

or directly:

sctxx extract claude:7c1e8f82 --out .sctxx/

302 MB transcript, 141,409 events, 288 user turns  ──►  7.9 KB handoff, 3.2k tokens   (5.0 s, no model)

Install

npm i -g sctxx                 # prebuilt binary for your OS, no toolchain needed
cargo install sctxx            # builds from crates.io
sctxx update                   # update the way you installed it (npm or cargo, detected)
cargo binstall sctxx           # prebuilt binary via cargo

Supported agents

Adding a provider means writing one adapter to the canonical IR.

Common commands

sctxx list                                   # what sessions exist here
sctxx find "auth migration"                  # find one by topic
sctxx extract claude:last --out .sctxx/      # the most recent session in this directory
sctxx extract codex:6f1a2b3c --llm none      # deterministic, no model, no network
sctxx extract pi:last --focus "finish the exporter"
sctxx expand claude:7c1e8f82 4122..4381 --context 3
sctxx verify .sctxx/ --strict                # is this handoff still true?
sctxx doctor                                 # what did sctxx detect on this machine?

sctxx extract --dry-run prints the plan and the estimated token cost before spending anything.

LLM backends

The fold is optional and works with whatever you already have.

Use an API for a long session; a subscription CLI cannot fold one. Measured on a real 103,757-event session with the same digest and the same two calls:

The CLI backends ask a coding agent to answer a 50,000-token prompt, and their harnesses are built for something else. They are fine for a small session; for a large one they will not return. Pass --model-context so sctxx checks the prompt against the window before sending it. | api:compat/<model> | any OpenAI-compatible endpoint via SCTXX_BASE_URL (OpenRouter, DeepSeek, Ollama, vLLM, LM Studio) |

The main line

Get one agent's session into another agent:

sctxx handoff last --to claude            # extract the context and print the command
sctxx handoff last --to claude --run      # ...and start the agent with it loaded
sctxx handoff last --json                 # who could continue this session?

Measured on an Apple M1 Max (release build) against a synthetic 302 MB session with tool-output-heavy turns; see specs/004-m1-deterministic-handoff-skeleton/evidence/perf-synthetic-2026-09-11.md for the command, the raw numbers, and the memory characteristic.

What makes the output trustworthy

Most compaction is a model reading a transcript and writing a paragraph. sctxx is built the other way round.

• Deterministic first. Rust computes branch resolution, the file/command/error ledgers, masking, budgets, validation, and rendering. A model is used only for semantic judgment. --llm none produces a complete, useful artifact and calls nothing.
• Provenance or it did not happen. Every item cites the event range that justifies it, and sctxx expand <ref> 4122..4381 prints those events back. Nothing in the artifact is a claim you cannot check.
• Constraints are quoted, not paraphrased. A rule attributed to you must carry your verbatim words, checked against the transcript. An invented quote is rejected before it can reach the artifact — and the rejection is recorded in state.json. The layer that finds them runs without a model, so the section exists even when --llm none does, and a deterministic verifier restores any constraint the semantic pass drops. The artifact reports constraints / preserved / restored / missing rather than asserting that nothing was lost — and states, in the section itself, what a pattern cannot see: a rule you wrote declaratively is invisible to it, so a missing rule is unknown, not permission.
• The prompt is checked against the reader's window before it is sent. --model-context 200000 --max-completion 8000 makes sctxx verify K ≤ L on every call and refuse once, immediately, naming each term (K = system + state + ledgers + premap + chunk + scaffold) instead of failing forty times over two hours.
• The repository wins. After extraction, sctxx reconciles the artifact against your working tree with read-only git commands and marks anything stale or contradicted.
• Secrets are redacted before any model call, again on the model's output, and again on the rendered artifact.
• Nothing from a transcript is ever executed, and every prompt that embeds transcript text fences it as data.

Built on published research

sctxx does not invent its compaction policy. Every mechanism below is taken from a peer-reviewed paper or a public artifact, with a note in docs/research/ recording what transferred, what did not, and what the measurement said when it was implemented.

Where a source's setting differs, sctxx says so rather than borrowing the authority. That paper's corpus is authored rules files, where make sure … opens a rule; in a transcript it opens a task. Measured on a real 274-turn session, the difference is the whole ballgame: matching on markers anywhere in a sentence returns 40 "constraints" of which none of the first six inspected is an instruction; anchoring the marker at the head of the clause returns 1, which is real. The full measurement, including the recall this layer does not have, is in docs/research/ and ADR 0008.

Does it work? Measured, not asserted

The survey of the field found no published result measuring what sctxx does. The closest work, Handoff Debt, is a real handoff benchmark with one arm missing: a successor that can ask for the part of the transcript it needs. So sctxx ships the benchmark, sctxx bench, and it is built to be able to lose — none and tail are arms, because a win over doing nothing is not a win, and tail is the strategy the published evidence actually favours.

Four real sessions, 76 questions, one successor backend, Claude Code and Codex transcripts:

By class, which is where it gets interesting:

A brief cannot answer a question about the middle of a long session — no arm without retrieval scores a single one of forty. Retrieval takes that to 23/40 and cuts the cost per correct answer by 2.2×, because a reader who can ask for one event range does not need the whole transcript in front of it.

What this does not measure: whether a successor resolves an issue. It measures whether a fresh agent can answer checkable questions about the session from a given context. That is a proxy, it is named as one, and the method and its limitations are in docs/BENCHMARK.md. Numbers and raw reports: docs/benchmarks/.

The artifact

Four layers, cheapest first, so an agent can stop reading as soon as it knows enough.

An excerpt from a real run:

**Current step** (S2): Making TrustTier 3 actually sandboxed in ModuleHost.spawn.
`pnpm vitest run packages/ext-engine` still fails: TypeError: Cannot read properties
of undefined (reading 'capabilities') at module-host.ts:41:22. [evt 12–15]

**Hard constraints**
- (C1) "Never auto-install extensions from the registry without asking me." [evt 0]

**Don't retry**
- (X1) Wiring the raw manifest into ModuleHost.spawn — spawn reads
  manifest.capabilities, which is undefined. [evt 7–11]

sctxx Handoff Architecture - What Comes from Codex vs What Is Original

It is deterministic: no model, no tokens, seconds. The artifact carries every [evt a-b] pointer, every ledger, and the recency tail, and the receiving agent follows pointers with sctxx expand. --llm cli:claude asks for the model-written fold, which is a choice: on a 100k-event session that is 41 fold calls plus 40 premap calls.

The same thing with two keystrokes: sctxx --tui, pick a session, press h.

The npm package is a shim: it depends on a per-platform package containing the binary, so npm i -g sctxx needs no Rust toolchain. On an unsupported platform it says so and points at cargo install rather than failing the install. See npm/README.md.

Or download a binary from Releases.

Documentation

Everything on one page: https://handyutils.github.io/sctxx/

In this repository

Elsewhere: npm · crates.io · Releases · Issues · the upstream we port from

Status

v0.3.0. The CLI, exit codes, and the sctxx.handoff/v1, ops.v1, and state.v1 schemas are contracts. The Rust library surface is public but unstable before 1.0.

Not yet built, and tracked in the roadmap: the probe loop and sctxx eval (M5), cache and resume, incremental updates, host mode, and an MCP server (M6).

Licence and provenance

Apache-2.0. Includes code derived from OpenAI Codex (Apache-2.0) at commit 818f1cc: UTF-8-safe truncation, secret redaction, evidence tiering budgeting, rollback-aware replay, and the apply_patch header grammar. Each ported file carries its attribution header; src/vendor/codex/README.md is the manifest. sctxx is not affiliated with or endorsed by OpenAI or Anthropic.

The Claude Code adapter is clean-room: written from on-disk session files, public documentation, and contributed fixtures only.