ctx.cat

Turn a local Codex session into an encrypted link your teammate can read. Qualified Codex versions also support continuing the session in their own CLI.

Install

Sharing requires Node.js 22 or newer on macOS or Linux. Newer and alpha Codex versions can share validated full conversation snapshots for browser viewing and download without installing a matching Codex CLI.

Native continuation additionally requires an authenticated, PATH-visible codex-cli 0.144.4 or codex-cli 0.147.0.

Bun 1.3.13 is required for the one-paste continue command. Install that exact version before copying the browser command; permanent ctx installs may continue to use the Node.js/npm path below.

npm install --global @synthlabs/ctx-cat-client

Check the installation with ctx --help.

ctx is the preferred command. ctxcat remains an equivalent compatibility executable, and ctxcat-mcp remains the MCP entry point. Existing configuration and recovery files keep their current locations.

If another tool already provides ctx, do not force npm to overwrite it. Keep using ctxcat from your existing installation, or run this package explicitly:

npm exec --package @synthlabs/ctx-cat-client -- ctxcat --help

Check command -v ctx when diagnosing which tool your shell runs.

Share a session

ctx share <full-codex-session-id>

Send the link to your buddy to read in the browser. For qualified native sessions, they can copy the link and run ctx resume in their checkout.

The command copies the encrypted reader link to your clipboard and prints it below Shared · link copied. If the clipboard is unavailable, the link still prints and the share succeeds. JSON output never copies to the clipboard. It keeps the owner capability in a private managed recovery file under $XDG_STATE_HOME/ctxcat or ~/.local/state/ctxcat instead of printing it. Run this human-facing command in a real terminal; the reader link is itself a capability, so share it only with the intended teammate.

Inspect the selected conversation locally before uploading:

ctx share <full-codex-session-id> --preview

Newer and alpha versions use encrypted browser sharing when native continuation has not been qualified. The CLI says so before upload; a successful share does not claim native continuation support. The snapshot includes full recorded history and tool output, follows fork ancestors up to their recorded fork boundaries, and excludes external working-tree files. It is a point-in-time snapshot, not a live sync. Unknown record types are preserved. Invalid history or missing ancestors fail before upload instead of silently sharing a partial conversation. An unfinished trailing record is omitted with a notice; share again after the turn finishes to include later content. This compatibility path currently reads up to 36 MiB of source session files, including ancestor files.

You can also select --latest or --previous:

ctx share --latest

For Codex 0.147, the sender supports only paginated sessions produced by the official Codex TUI. It verifies and captures the selected leaf's complete root-to-leaf lineage before it creates the encrypted share. Use the leaf's full session ID with the normal command:

ctx share <full-0.147-leaf-session-id>

Advanced exact-path selection and explicit recovery output are documented in the CLI reference linked below.

The 0.147 portable sender is exact-version only and fails closed on missing, changed, duplicate, cyclic, or structurally invalid lineage. Codex 0.147 codex exec sessions use legacy history and are rejected before share creation; create the source session and fork in the Codex TUI. The sender uses one-shot transport through 8 MiB and multipart transport above that boundary. Codex 0.144.4 remains the separate verified legacy native-resume path.

Open a document in Codex

Copy a shared Markdown or text document's reader link, open your project terminal, and run:

ctx codex

The CLI decrypts the share and starts Codex with the document as context. Documents up to 64 KiB are supplied inline through stdin, then the initialized conversation opens interactively. That path includes a short model acknowledgment using your Codex account and configuration.

Larger documents are saved byte-for-byte under ~/.ctxcat/attachments/. Codex opens with a short prompt to read that private file as reference context. The attachment remains on disk after exit so it is still available when you resume; remove it when you no longer need it. Files are owner-only (0600), inside private directories (0700), outside your project checkout.

Documents must be nonempty UTF-8 text without NUL bytes and at most the existing 36 MiB document limit. Text is never truncated. Large attachments can be read as needed rather than forcing the whole file into the initial model context.

The website's Copy command action provides a short ctx codex --handoff-nonce=… command. Its associated rich clipboard representation carries the private reader link; a missing or mismatched clipboard fails before download. Private URLs and document text stay out of command arguments. macOS supports this clipboard handoff directly; Linux requires wl-clipboard or xclip.

Public shares can also be opened directly with ctx codex <public-url-or-id>. Use --cwd DIR to choose another project directory. Inline startup uses codex exec --json - and codex resume <id>; large-file startup uses the interactive prompt argument. Install a current Codex CLI. This document flow is separate from the qualified native-session import below.

Both terminal input and output must be interactive. If inline context is saved but Codex cannot open, the error includes the exact codex resume command; use that command to recover the existing conversation instead of creating another.

Resume it

On a compatible ctx.cat reader page, choose Copy Continue in Codex command, open the target checkout, and paste the copied command. The page supplies an exact qualified package version in this shape:

bunx --package @synthlabs/ctx-cat-client@<qualified-version> ctxcat codex continue --from-clipboard --handoff-nonce=<nonce>

The clipboard's plain-text representation contains only that command. A separate HTML representation carries the reader link and is bound to the non-secret nonce. ctx codex continue reads that structured representation, rejects missing or mismatched clipboard state before download, imports one recipient-owned child, and launches Codex. It never accepts the reader link as a positional argument.

ctx resume remains the manual compatibility path. Copy the reader link, open the target checkout, and run:

ctx resume

ctx resume reads the link from your clipboard, validates and imports the snapshot, creates or recovers one recipient-owned child session, and launches codex resume in the current directory. Your own Codex authentication, config, approvals, hooks, and environment remain in control.

macOS clipboard access is built in. On Linux, install wl-clipboard or xclip for either clipboard command. The structured continue path requires an HTML clipboard representation; it never silently falls back to the plain command or plain reader URL.

For secret-safe automation, pipe the link from a secret source. This imports the session and returns JSON without launching an interactive Codex process:

# macOS example
pbpaste | ctx resume --from-stdin --json

Native handoff is qualified only for the separate pinned Codex 0.144.4 legacy contract and exact Codex 0.147.0 portable contract. Source and recipient versions must match their selected contract; this is not a general cross-version compatibility claim. Claude Code continuation uses reconstructed transcript context rather than native resume.

See the CLI documentation for advanced selectors, timeouts, previews, explicit recovery paths, lifecycle commands, Claude reconstruction, and large-session qualification.

Security model

• Session content is encrypted locally. The backend never receives the decryption key.
• A reader link grants access to the encrypted share. Keep it out of command arguments, logs, model prompts, analytics, and issue trackers.
• The one-paste continue command keeps the reader link out of shell history, process arguments, and terminal logs. The capability still exists briefly in the clipboard's HTML representation and remains observable to clipboard managers, browser extensions, or other local clipboard readers.
• The owner capability is written to a new 0600 recovery file inside the app's 0700 state directory before network access. It is never printed.
• Resume accepts clipboard input by default or stdin for automation; it does not accept a capability URL as a positional argument.
• ctx codex continue accepts exactly one nonce-bound structured clipboard envelope. Recopying may change the nonce, but it does not change the durable import identity derived from the capsule, recipient home, and working directory.
• ctx fetch and ctx meta refuse capability-bearing URL fragments on the command line. Private reads use --capability-input PATH or --from-stdin.
• Legacy 10-byte reader keys fail closed. Admit them only with --allow-legacy-reader on --from-stdin (capability files always use 32-byte keys), or allowLegacyReaderKey: true in library/browser loaders.
• API origins must be HTTPS or loopback HTTP. Multipart rejects the localhost hostname (IP loopback only); one-shot private browser loads may still use exact http://localhost origins.
• The recipient chooses the checkout. Sender credentials and absolute paths are never imported.

Session commands

• ctx share / ctx sessions share share the complete conversation. Newer and alpha versions use browser viewing with native continuation unavailable; the qualified versions create a native session capsule for teammate handoff and resume.
• ctx sessions upload creates a private viewer-oriented share of session text or JSONL. It is not curated training or eval export.
• Training eligibility and TrainingExport remain server-side gated workflows.

MCP

Install the package, then run the stdio server with:

ctxcat-mcp

The MCP surface reads and verifies public shares and renders bounded traces. It does not accept private reader links or create shares because those capabilities must not enter model-visible tool output. Use the human-facing ctx share command for session handoff. Prefer numeric JSON-RPC request IDs; never put keys or share URLs in the request id. Capability-bearing CLI artifacts (recovery files, --reveal-reader-url output) must stay out of model prompts and shared logs.

See the MCP setup guide for Codex, Claude Code, OpenCode, Cursor, and generic MCP configuration.

Library

The browser-first TypeScript package exposes encrypted sharing, signing, session detection, rendering, session scanning, and browser-safe multipart loading:

import { createPrivateShare, loadPrivateShare } from "@synthlabs/ctx-cat-client";

Library create calls require an explicit durable recovery sink. Retention, provenance, training eligibility, user or organization attribution, and server-side storage policy remain server responsibilities. Optional sign.githubUser is claimed transport attribution only (X-Ctx-Signature-Github-User / untrustedGithubUser); the client does not treat it as verified identity.

Compatibility

Arbitrary files use the explicit ctx file share <path> namespace. The earlier ctxcat share-session command and low-level ctx share <file> --capability-output ... grammar remain supported aliases; new human-facing examples use ctx share for sessions. Browser codecs and session-capsule loaders are owned by this package; root must consume the published exports rather than re-growing a mirrored decoder (see docs/adr/2026-08-06-client-codec-authority.md). Cross-repo packed integrity is pinned only in compatibility/ctx-cat.json.

Development

This repository uses Bun:

bun install
bun run build
bun run typecheck
bun run test

The distributed package bytes are MIT-licensed. The source repository remains private.