ctx.cat CLI

@synthlabs/ctx-cat-client@0.4.11 is the public package for ctxcat and ctxcat-mcp. Its published package bytes are MIT-licensed; the source repository remains private.

Install

Prerequisites are Node.js 22 or newer, Bun 1.3.13, and a PATH-visible Bun executable:

bun add --global @synthlabs/ctx-cat-client@0.4.11 && command -v ctxcat >/dev/null && command -v ctxcat-mcp >/dev/null

Direct Git dependency installation is not a supported installation contract.

Continue A Portable Codex 0.147 Session

When a private reader link contains an authenticated portable Codex 0.147 transcript, the hosted reader shows **Continue in Codex**. Review the logical transcript first, then use that control to copy a command shaped like:

bunx --package @synthlabs/ctx-cat-client@0.4.11 ctxcat codex continue --from-clipboard --handoff-nonce=<22-char-nonce>

Paste the command unchanged into the desired local workspace. The plain text does not contain the reader URL; the same clipboard item carries that capability in a nonce-bound structured representation. The CLI verifies the share, creates or recovers a recipient-owned Codex 0.147 continuation, and launches codex resume locally. If structured clipboard access is unavailable, the reader fails honestly instead of copying the capability into shell history.

Client 0.4.11 enables public Codex 0.147 sender emission only for official interactive Codex TUI paginated lineages. codex exec emits legacy history; other headless sessions are unsupported. The retained Codex 0.144.4 handoff below remains a separate path.

Share And Resume An Exact Codex 0.144.4 Session

The retained exact-session path is pinned to official Codex CLI 0.144.4. Replace <full-codex-session-id> with the exact ID from ctxcat sessions scan --json. Run the sender command in a user-controlled terminal:

ctxcat share <full-codex-session-id>

The command prints an encrypted reader link. Copy it only to the intended teammate. The recipient needs authenticated, PATH-visible codex-cli 0.144.4 and an owned CODEX_HOME directory with mode 0700. After copying the reader link, run this from the desired workspace:

ctxcat resume

ctxcat resume reads the link from the clipboard, creates or recovers one recipient-owned child, and launches codex resume in the current directory. The reader URL is a capability; do not place it in model-visible arguments or logs.

For Automation

The lower-level commands are for a user-controlled automation that needs a durable recovery file. Keep the file in a private directory; it contains reader and owner lifecycle capabilities. Do not put a reader URL in command arguments, model-visible input, or logs.

SESSION_ID='<full-codex-session-id>'; RECOVERY_DIR="$HOME/.local/share/ctxcat/$(date +%s)-$$-$RANDOM-$RANDOM"; install -d -m 700 "$RECOVERY_DIR" && ctxcat sessions share "$SESSION_ID" --capability-output "$RECOVERY_DIR/codex-handoff.recovery.json" --reveal-reader-url
# macOS
pbpaste | ctxcat resume --from-stdin --json
# Linux Wayland
wl-paste --no-newline | ctxcat resume --from-stdin --json
# Portable: save only the reader URL in this 0600 local file with a local editor.
READER_FILE="$RECOVERY_DIR/reader-url"
install -m 600 /dev/null "$READER_FILE"
ctxcat resume --from-stdin --json < "$READER_FILE"

Share A File

Every create needs a fresh recovery path in a private directory:

RECOVERY_DIR="$HOME/.local/share/ctxcat/$(date +%s)-$$-$RANDOM-$RANDOM"
install -d -m 700 "$RECOVERY_DIR"
ctxcat file share ./notes.md --capability-output "$RECOVERY_DIR/notes.recovery.json"

The recovery file contains reader and owner lifecycle capabilities. Keep it out of agent context, output, and logs, and never overwrite or reuse it for another share.

Read And Inspect

ctxcat fetch 'https://www.ctx.cat/<id>#<key>'
ctxcat fetch 'https://www.ctx.cat/<id>#<key>' --json
ctxcat meta 'https://www.ctx.cat/<id>#<key>' --json

fetch --json reads or decrypts content locally and includes its verification result. meta --json returns server-visible storage metadata; it does not decrypt content or independently verify the share.

Lifecycle

Use the recovery file from the corresponding create command:

CAPABILITY_INPUT="${RECOVERY_DIR:?initialize RECOVERY_DIR first}/codex-handoff.recovery.json"
ctxcat lifecycle read --capability-input "$CAPABILITY_INPUT"
ctxcat lifecycle update --capability-input "$CAPABILITY_INPUT" --expires-at never
printf '%s' 'ready for review' | ctxcat lifecycle comment --capability-input "$CAPABILITY_INPUT" --from-stdin
ctxcat lifecycle comments --capability-input "$CAPABILITY_INPUT"
ctxcat lifecycle delete --capability-input "$CAPABILITY_INPUT"

lifecycle update changes expiry only. If a mutation was dispatched or accepted but its response could not be completed, inspect the share and never retry that mutation automatically.