ctx.cat CLI

@synthlabs/ctx-cat-client@0.3.1 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.3.1 && command -v ctxcat >/dev/null && command -v ctxcat-mcp >/dev/null

Direct Git dependency installation is not a supported installation contract.

Share And Resume A Codex Session

The accepted native continuation 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.