CLI command reference

This is the canonical manual for the ContextRelay command-line interface. Every command, subaction, and flag below is dispatched from src/cli.ts and backed by a dedicated handler under src/cli/. Commands are grouped by what you do with them: set up and launch, inspect, configure policy, automate, and manage sessions and lifecycle.

If you are new to ContextRelay, start with Install and first run and Daily operation - those pages walk you through the handful of commands you use every day. This page is the exhaustive reference you come back to.

The binary

ContextRelay installs three interchangeable binaries that all point at the same CLI. Use whichever you prefer; these docs prefer contextrelay and ctxrelay.

contextrelay <command> [args...]
context-relay <command> [args...]
ctxrelay <command> [args...]

The package is published as @proofofwork-agency/contextrelay.

Running with no subcommand opens the dashboard

contextrelay (or ctxrelay) with no subcommand opens the native full-screen terminal dashboard - the same thing as ctxrelay tui. There is no separate "TUI" launch step.

Global flags

Flag	Effect
--help, -h	Print top-level usage, the command list, and examples. Also works after most subcommands (e.g. ctxrelay upgrade --help).
--version, -v	Print the installed ContextRelay version.

Command summary

One row per command. The nuanced commands have notes in the sections that follow.

Command	Purpose
tui [--no-start] [--force]	Open the native terminal dashboard.
init [--instructions project|global|both|skip]	First-time setup: check dependencies, create project config, install the Claude plugin, and optionally write managed instruction blocks.
upgrade [--dry-run] [--no-plugin] [--instructions refresh|project|global|both|skip]	Reconcile an installed ContextRelay to the version on disk after an npm update.
dev	Register the local plugin marketplace and sync the local plugin for development.
claude [--session <id>] [args...]	Start Claude Code with the ContextRelay plugin channel enabled.
codex [--session <id>] [args...]	Start the Codex TUI connected to the daemon and proxy.
codex-mcp install|remove|status|server	Manage the Codex MCP tool registration.
pair [--dry-run] [--no-tui] [--port-base <port>] [--session <id>]	Start Claude and Codex in separate terminals, then keep the control TUI open.
doctor [--no-auth]	Diagnose binaries, auth, state, plugin registration, daemon health, tokens, and stale locks.
instructions status|install|remove [--scope project|global|both]	Manage the ContextRelay collaboration blocks in CLAUDE.md / AGENTS.md.
coordinator [status|claude|codex|human] [--scope project|global|both]	Set the manual coordinator and rewrite managed instruction blocks.
permissions status|readonly on|off|allow <cap>|deny <cap>|reset [--agent <id>]	Configure ContextRelay-mediated permission policy.
detach-claude	Clear the active Claude foreground connection without killing Codex or the daemon.
status [--json]	Print daemon, session, connection, ledger, task, autonomy, finality, and backup state.
session list [--scope project|global] [--no-probe] [--archived] | create <id> [--label <text>] [--worktree <path>] | select <id> | archive <id> | rebind <id> [--worktree <path>] | prune [--dry-run|--apply] [--json]	List, create, select, archive, rebind, and prune registry-backed runtime sessions. Global list is read-only and shows daemon/agent/queue state per instance; --no-probe skips daemon probing.
recover [--json]	Summarize crash-recovery context, recent failures, interrupted commands, git status, and a resume prompt.
instances	List known project instances and their assigned ports.
viewer [--no-open]	Open the local browser Command Deck.
autonomy on|off|status	Control whether explicit read-only backup-agent requests may run.
idle-scanner off|suggest|ask|act|status [--why]	Configure the idle opportunity scanner. status --why and check print the act gate table with a satisfy hint per failing gate plus daemon dispatch diagnostics.
idle-budget status|reset	Show resolved read-only idle-action budgets, or reset live usage with reset --confirm.
idle-eval status|compare	Manually plan or run single-vs-fleet value-probe evaluations.
write-mode off|suggest|ask|act|status	Configure the default-off act:write gates.
finalize auto|manual|status	Control whether finality can be recorded automatically.
usage status|off|lean|strict	Configure token/context usage presets across shared-context tool output and Claude hook injection.
usage hook status|verbose|compact|count|set	Advanced UserPromptSubmit hook token controls.
usage context off|lean|strict|status	Advanced ContextRelay MCP shared-context output controls.
usage ledger compact [--dry-run|--apply]	Deterministically compact old ledger entries into hash-backed summaries.
usage ledger clear [--dry-run|--apply]	Archive the ledger and replace it with a fresh session_started entry. Dry-run is the default.
hook-compaction status|verbose|compact|count|set	Compatibility alias for usage hook ....
usage-control off|lean|strict|status	Compatibility alias for usage context ....
ledger list [--scope project|global] [--session <id>] [--runtime-session <id>] [--json]	Inspect append-only ledger entries across the current project or known live project instances.
ledger show <entry-id> [--scope project|global] [--json]	Show one ledger entry without mutating the ledger.
ledger compact [--dry-run|--apply]	Compatibility alias for usage ledger compact ....
ledger clear [--dry-run|--apply]	Compatibility alias for usage ledger clear ....
queue list|show|remove|drain [--scope project|global] [--json]	Inspect durable and live queued messages. Removal/drain is dry-run by default and marks durable rows drained rather than deleting them.
messages status | drain [--apply] [--chat <id>]	Inspect or drain the pending Codex-to-Claude delivery queue. status (default) lists pending messages; drain previews by default and only clears with --apply. Never touches the session ledger.
release-gate [--json] [--smoke]	Run build/check release-readiness and record a release_gate artifact.
kill [--all|--session <id>]	Stop this project instance, every known instance, or one named session's Codex runtime.
gate-check [--status|--json|--why]	Resolve whether ContextRelay is active for this session (exit 0 active / 1 dormant).
attach [session-name]	Opt the current workspace into ContextRelay in-session.
detach	Opt the current workspace out of ContextRelay.
standalone on|off|status [--scope project|global|both] [--path <file>]	Per-user dormant-by-default control.

Setup and launch

init

ctxrelay init --instructions project

Run once per project. init checks that the Claude and Codex binaries are present, creates .contextrelay/config.json with safe defaults (autonomy off, finality manual, idle scanner off, write-mode off), installs the Claude Code plugin, and - depending on --instructions - writes the managed collaboration blocks into CLAUDE.md / AGENTS.md.

The --instructions value selects where those blocks go: project (the current repo), global (your home + conventional global files), both, or skip (touch no instruction files). See Configure collaboration policy.

upgrade

# After: npm i -g @proofofwork-agency/contextrelay@latest
ctxrelay upgrade

upgrade reconciles an already-installed ContextRelay to the version currently on disk. It is the third setup flow alongside init (first-time) and dev (local source rebuild): once you have bumped the npm package, upgrade brings the agent-facing surface - registered plugin, managed instruction blocks, project config, and the bare /contextrelay command - into line with the new package, safely and idempotently.

What it does:

• Migrate-merges config. It deep-merges the new defaults into .contextrelay/config.json so new default keys are added while your existing values are preserved (coordinator, activation state, permissions, write-mode, and so on stay exactly as you set them). It records the applied version so a later run - or doctor - can show drift.
• Refreshes managed instruction blocks in place. For each CLAUDE.md / AGENTS.md that already carries a managed block, it re-applies the current wording while preserving that file's slim or full state - a dormant (slimmed) file stays slim, a full file stays full.
• Refreshes the bare /contextrelay command only if it is present (i.e. you have run standalone on). It never creates that command from upgrade.
• Re-registers and reinstalls the Claude plugin so the new bundles are picked up (skip with --no-plugin).
• Prints from X → Y (or Now at Y) and reminds you to run /reload-plugins inside a running Claude Code session.

Flags:

Flag	Effect
--dry-run	Compute and print the full plan, then write nothing and run no plugin install.
--no-plugin	Skip the Claude plugin re-register/reinstall step (e.g. offline, or Claude not installed).
--instructions refresh|project|global|both|skip	refresh (default) refreshes only files that already carry a managed block; project / global / both additionally install blocks where missing; skip touches no instruction files.

ctxrelay upgrade --dry-run     # Preview exactly what would change

What upgrade does NOT do

upgrade performs no git operations, no npm operations, and no version bump or publish. It does not restart the daemon, and it does not delete obsolete config fields - it only adds new defaults and preserves what you already have. It never changes your coordinator or your activation on/off state, and it never un-slims a dormant file. Running it twice with no package change is a no-op ("Already up to date at vX.").

On an older release without upgrade?

If your installed ContextRelay predates the upgrade command, you can reach the same end state manually: re-sync the plugin with ctxrelay dev, refresh instruction blocks with ctxrelay instructions install, and verify the result with ctxrelay doctor. See Upgrading ContextRelay.

dev

ctxrelay dev

Registers the local plugin marketplace and syncs the plugin from source. This is the developer path for working on ContextRelay itself; end users who installed from npm use init and upgrade instead.

claude and codex

ctxrelay claude              # Start Claude Code with the ContextRelay channel
ctxrelay claude --resume     # Extra args pass straight through to the claude binary
ctxrelay codex               # Start the Codex TUI connected to the daemon
ctxrelay codex --model o3    # Extra args pass straight through to the codex binary

Both ensure the daemon is up and connect the agent to it. Any arguments after the ContextRelay flags are forwarded to the underlying claude / codex binary.

The optional --session <id> binds a named runtime pair instead of the default one. Named sessions require an explicit opt-in:

Named sessions are opt-in

ctxrelay claude --session <id> and ctxrelay codex --session <id> require CONTEXTRELAY_ALLOW_NAMED_SESSIONS=1 in the environment. See Runtime sessions and worktrees and the Environment variables reference.

codex-mcp

ctxrelay codex-mcp install   # Register the ContextRelay MCP tools with Codex
ctxrelay codex-mcp status    # Show the current registration
ctxrelay codex-mcp remove    # Remove the registration
ctxrelay codex-mcp server    # stdio entrypoint Codex launches (not run by hand)

install registers ContextRelay's MCP tools globally for Codex. Because it is a Codex MCP registration, a normal codex window opened in the project can load the same tools and attach to the project daemon - you are not limited to ctxrelay codex. Use remove to scope Codex participation back to ctxrelay codex only. The MCP tools themselves are documented in the MCP tools reference.

pair

ctxrelay pair                # Launch Claude + Codex terminals, then open the TUI
ctxrelay pair --dry-run      # Print the launch commands without running them

pair starts Claude and Codex in separate terminal sessions and keeps the control TUI open unless --no-tui is set. --port-base <port> overrides the port group; --session <id> launches a named runtime pair.

Inspection and diagnostics

doctor

ctxrelay doctor              # Full diagnostics
ctxrelay doctor --no-auth    # Skip the auth-token checks

Diagnoses binaries, auth, state, plugin registration, daemon health, tokens, and stale locks. This is the first command to run when something looks wrong - see Troubleshooting and recovery.

status

ctxrelay status              # Human-readable
ctxrelay status --json       # Machine-readable

Prints daemon, session, connection, ledger, task, autonomy, finality, and backup state.

recover

ctxrelay recover             # Summarize crash-recovery context + a resume prompt
ctxrelay recover --json

Summarizes recent failures, interrupted commands, git status, and a suggested resume prompt after a crash or interruption.

instances

ctxrelay instances

Lists every known project instance and its assigned port group - useful when you run ContextRelay across multiple repos and need to see who owns which ports.

viewer

ctxrelay viewer              # Open the browser Command Deck
ctxrelay viewer --no-open    # Print the URL without launching a browser

Opens the local browser Command Deck (task lanes, artifacts, policy, timeline).

release-gate

ctxrelay release-gate            # Run build/check readiness, record an artifact
ctxrelay release-gate --json
ctxrelay release-gate --smoke    # Add optional observation-only runtime evidence

Runs the release-readiness checks and records a release_gate artifact in the ledger for sign-off.

gate-check

ctxrelay gate-check --why    # "active - <reason>" or "dormant - <reason>"
ctxrelay gate-check --json   # {"active":true,"reason":"..."}
ctxrelay gate-check --status # "active" or "dormant"

Resolves whether ContextRelay is active for this session from pure file, env, and marker reads (no daemon calls). The exit code is the contract: 0 = active, 1 = dormant. The SessionStart / UserPromptSubmit hooks consult the bundled equivalent to decide whether to engage. The flags are diagnostics only.

Activation fails open

If gate-check hits an unexpected error it exits 0 (active) on purpose, so a bug there can never silently suppress the collaboration loop.

Policy configuration

coordinator

ctxrelay coordinator status            # Show the current coordinator
ctxrelay coordinator codex             # Make Codex the coordinator (git owner)
ctxrelay coordinator codex --scope both

Sets the manual coordinator - the agent that owns git writes - in .contextrelay/config.json and rewrites the managed instruction blocks to match. The value is one of claude, codex, or human. See Coordinator and git-write policy.

permissions

ctxrelay permissions status            # Show the mediated policy
ctxrelay permissions readonly on       # Block writes/shell/network/git/etc.
ctxrelay permissions deny shell        # Deny a single capability
ctxrelay permissions allow shell       # Re-allow it
ctxrelay permissions reset             # Restore defaults
ctxrelay permissions deny git --agent codex   # Per-agent override

Configures the ContextRelay-mediated permission policy. The eight capabilities are read, write, shell, network, git, secrets, browser, and external_api. --agent <agentId> scopes an allow / deny / reset to one agent. See Read-only by default.

instructions

ctxrelay instructions status                   # Show which files carry a block
ctxrelay instructions install --scope project  # Write/refresh the managed block
ctxrelay instructions remove --scope project   # Remove it

Manages the ContextRelay collaboration blocks in CLAUDE.md, AGENTS.md, ~/.claude/CLAUDE.md, and ~/.codex/AGENTS.md. --scope is project, global, or both.

finalize

ctxrelay finalize status     # Show the current mode (default: manual)
ctxrelay finalize manual     # Finality requires human acceptance
ctxrelay finalize auto       # Allow Claude to auto-finalize when criteria hold

Controls whether finality can be recorded automatically. The default is manual. See Finality and human sign-off.

usage

ctxrelay usage status    # Show preset, context, hook, and ledger dry-run state
ctxrelay usage lean      # Practical daily lower-usage mode
ctxrelay usage strict    # Aggressive mode for expensive/parallel sessions
ctxrelay usage off       # Disable tool-result shaping while keeping hook compact

Presets update both layers users normally care about:

Preset	Shared-context tools	Claude hook
off	off	compact
lean	lean	compact
strict	strict	count

Advanced subcommands let you tune one layer without changing the other:

ctxrelay usage context off|lean|strict|status
ctxrelay usage hook status|verbose|compact|count|set
ctxrelay usage ledger compact --dry-run
ctxrelay usage ledger compact --apply
ctxrelay usage ledger clear --dry-run
ctxrelay usage ledger clear --apply

hook-compaction

ctxrelay hook-compaction status    # Show the current mode
ctxrelay hook-compaction compact   # Reduce repeated hook context
ctxrelay hook-compaction verbose   # Full context
ctxrelay hook-compaction count     # Size-only
ctxrelay hook-compaction set       # Set an explicit value

Compatibility alias for ctxrelay usage hook .... Configures the UserPromptSubmit hook token mode that controls how much repeated context the hook injects.

Automation

Automation is read-only and off by default

Backup-agent autonomy is off by default, the idle scanner is off by default, and autonomous edits (act:write) are off by default behind several layered gates. Nothing below acts on its own until you explicitly enable it. See Read-only by default and Autonomy and safe automation.

autonomy

ctxrelay autonomy status     # Show the full autonomy config
ctxrelay autonomy on         # Allow explicit read-only backup-agent requests
ctxrelay autonomy off

Controls whether explicit, read-only backup-agent requests (ask_codex_backup / ask_claude_backup) may run. Off by default.

idle-scanner

ctxrelay idle-scanner status
ctxrelay idle-scanner status --why  # Gate table + live daemon dispatch diagnostics
ctxrelay idle-scanner check         # Gate table; exits non-zero when act cannot dispatch
ctxrelay idle-scanner off        # Disabled (default)
ctxrelay idle-scanner suggest    # Record idle-opportunity artifacts only
ctxrelay idle-scanner ask        # May prompt agents (requires autonomy)
ctxrelay idle-scanner act        # May dispatch read-only workers (requires autonomy)

Configures the deterministic idle opportunity scanner. The modes escalate from recording suggestions, to prompting agents, to dispatching bounded read-only workers. ask and act require autonomy to be on.

Every failing act gate prints a ↳ satisfy: hint naming the exact command, env export, or config key that makes it pass. status --why additionally reports the running daemon's dispatch diagnostics: agent states, the strict-idle result, any pending deferred dispatch, the last detected opportunity, and the last skip reason. The full act:write enablement recipe lives in ctxrelay write-mode --help.

idle-budget

ctxrelay idle-budget status            # Show resolved read-only idle-action budgets
ctxrelay idle-budget reset --confirm   # Reset live usage counters

Shows the resolved read-only idle-action budgets (from config plus env overrides), or resets live usage with reset --confirm.

idle-eval

ctxrelay idle-eval status
ctxrelay idle-eval compare              # Plan a single-vs-fleet probe (dry-run)
ctxrelay idle-eval compare --execute \
  --quality-margin 0.1 \
  --agreement-threshold 0.6 \
  --max-cost-ratio 2.0

Manually plans or runs a single-vs-fleet value-probe evaluation. compare is dry-run by default; --execute is additionally gated by idle-evaluation env vars. The deterministic scoring uses the configurable --quality-margin, --agreement-threshold, and --max-cost-ratio thresholds.

write-mode

ctxrelay write-mode status   # Show the act:write surface (default: off)
ctxrelay write-mode off
ctxrelay write-mode suggest
ctxrelay write-mode ask
ctxrelay write-mode act      # Highest mode - still gated by env/budget/containment

Configures the default-off act:write gates (autonomy.writableAction.mode). Setting the config mode is not sufficient on its own: a hard env flag, a positive daily spend cap, allowlists, strict idle conditions, and worktree containment must all also pass before any edit happens, and the worker never commits, merges, or pushes. See Enabling act:write safely.

Sessions, activation, and lifecycle

session

ctxrelay session list                  # Active runtime sessions
ctxrelay session list --archived       # Include archived sessions
ctxrelay session create side --label "review" --worktree ../cr-side
ctxrelay session select side
ctxrelay session archive side
ctxrelay session rebind side --worktree ../cr-side --json
ctxrelay session prune                 # Preview orphan cleanup (dry-run is the default)
ctxrelay session prune --apply         # Actually reclaim the orphans

Lists, creates, selects, archives, rebinds, and prunes registry-backed runtime sessions. Named sessions isolate live routing and can bind to an alternate git worktree. See Runtime sessions and worktrees.

prune reclaims runtime-session directories that no longer have a registry entry and clears stale named-session Codex runtime hints. It is a dry-run preview unless you pass --apply (--apply and --dry-run cannot be combined); --json prints the plan machine-readably.

attach and detach

ctxrelay attach              # Opt this workspace into ContextRelay in-session
ctxrelay attach feature-x    # Optionally bind a named session
ctxrelay detach              # Opt this workspace back out

attach is the in-session opt-in: it ensures the daemon is running, writes a per-workspace activation marker so the gated hooks re-engage on your next prompt, prints the full collaboration ruleset, and prints how to start the peer agent. detach removes that marker. Neither stops the daemon or Codex - use kill for that. These are the deterministic CLI behind the /contextrelay and /contextrelay:off commands. See Activation: auto-connect vs dormant.

standalone

ctxrelay standalone status                 # Show resolved activation + block states
ctxrelay standalone on                      # Go dormant-by-default for this user
ctxrelay standalone off                      # Restore auto-connect
ctxrelay standalone on --scope both --path ~/work/CLAUDE.md

Per-user dormant-by-default control. on writes the activation flag (activation.autoConnect), slims the always-on CLAUDE.md / AGENTS.md copies in your home and conventional global files, and installs the bare /contextrelay user command; off reverses all three. --scope (project, global, both; default global) targets where the activation flag is written, and --path <file> adds extra instruction files to slim or restore (repeatable).

The shipped default is auto-connect

ContextRelay ships with auto-connect on. Only running standalone on makes it dormant for you. The current repo's committed CLAUDE.md / AGENTS.md are never slimmed unless you pass them explicitly with --path (this keeps the project's own instruction checks green).

detach-claude

ctxrelay detach-claude

Clears a stale active Claude foreground connection. It does not kill Codex or the daemon - reach for this when a previous Claude attachment is lingering.

kill

ctxrelay kill                    # Stop this project instance
ctxrelay kill --all              # Emergency: stop every known instance
ctxrelay kill --session side     # Stop one named session's Codex runtime

Stops ContextRelay processes. kill with no flag stops the current project instance; --all is the emergency stop across every project.

Next steps

• MCP tools reference - the tools Claude and Codex call inside a session.
• config.json reference - every key these commands read and write.
• Environment variables reference - env overrides, including named-session and write-mode gates.
• Daily operation: launch, inspect, stop - the small set of commands you use every day.