Skip to content

System

ctx

ctx system

Hidden parent command that hosts Claude Code hook plumbing and a small set of session-lifecycle plumbing subcommands used by skills and editor integrations. The parent is registered without a visible group in ctx --help; run ctx system --help to see its subcommands.

ctx system <subcommand>

Commands Previously under ctx system

Several user-facing maintenance commands used to live under ctx system and were promoted to top-level:

  • ctx system events → ctx hook event
  • ctx system message → ctx hook message
  • ctx system prune → ctx prune
  • ctx system resources → ctx sysinfo
  • ctx system stats → ctx usage

ctx system bootstrap remains under ctx system as a hidden, agent-only command. Update any scripts or personal docs that reference the old paths.

Plumbing Subcommands

These are not hook handlers; they're called by skills and editor integrations during the session lifecycle. Safe to run manually.

ctx system mark-journal

Update processing state for a journal entry. Records the current date in .context/journal/.state.json. Used by journal skills to record pipeline progress.

ctx system mark-journal <filename> <stage>

Stages: exported, enriched, normalized, fences_verified

Flag Description
--check Check if stage is set (exit 1 if not)

Example:

ctx system mark-journal 2026-01-21-session-abc12345.md enriched
ctx system mark-journal 2026-01-21-session-abc12345.md normalized
ctx system mark-journal --check 2026-01-21-session-abc12345.md fences_verified

ctx system mark-wrapped-up

Suppress context checkpoint nudges after a wrap-up ceremony. Writes a marker file that check-context-size checks before emitting checkpoint boxes. The marker expires after 2 hours.

Called automatically by /ctx-wrap-up after persisting context (not intended for direct use).

ctx system mark-wrapped-up

No flags, no arguments. Idempotent: running it again updates the marker timestamp.

ctx system pause / ctx system resume

Session-scoped hook suppression. ctx system pause writes a marker file that causes hook plumbing to no-op for the current session; ctx system resume removes it. These are the hook-plumbing counterparts to the ctx hook pause / ctx hook resume commands (which call them internally).

Read the session ID from stdin JSON (same as hooks) or pass --session-id.

ctx system session-event

Records a session lifecycle event (start or end) to the event log. Called by editor integrations when a workspace is opened or closed.

ctx system session-event --type start --caller vscode
ctx system session-event --type end --caller vscode

ctx system statusline

Renders the Claude Code status line. Claude Code pipes a JSON payload to the configured statusLine command after each assistant message; this command turns it into one line:

user@host ~/project | Opus | ctx: 42% | $1.23

ctx init wires it into .claude/settings.local.json, backing up any pre-existing statusLine entry to .context/state/previous-statusline.json (restored when statusline.enabled: false is set in .ctxrc; a statusLine that is not ctx's is never removed).

Missing payload fields drop their segment. Output is sanitized to bounded printable ASCII, and the command always exits zero: a non-zero exit would blank the status line. The line is informational only; there is no cost gating and no model-switch nudging (see specs/statusline.md for the rationale).

ctx system statusline < payload.json

Config (.ctxrc): statusline.enabled (default true) and statusline.show_cost (render the $ segment, default true; disable for screen-sharing or demos). Setting enabled: false blanks the rendered line immediately; the settings entry itself is restored/removed the next time the init merge runs.

Hook Subcommands

Hidden Claude Code hook handlers implementing the hook contract: read JSON from stdin, perform logic, emit output on stdout, exit 0. Block commands output JSON with a decision field.

UserPromptSubmit hooks: context-load-gate, check-context-size, check-persistence, check-ceremony, check-journal, check-version, check-resource, check-knowledge, check-map-staleness, check-memory-drift, check-reminder, check-freshness, check-hub-sync, check-skill-discovery, heartbeat.

PreToolUse hooks: block-non-path-ctx, block-dangerous-command, qa-reminder, specs-nudge.

PostToolUse hooks: post-commit, check-task-completion.

See AI Tools for registration details and the Claude Code plugin integration.