Commands

The cxc and codexclaw binaries are the same thin delegator over the compiled component CLIs. The live dispatch set is enable, disable, uninstall, status, orchestrate, freeze, metric, divergence, loop, goalplan, plan, scan, doctor, reset, hooks, subagents, map, provider, chat, memory, skill, gui, serve, and service.

Two CLI tiers

For v0.1.1 the plugin payload ships its own dispatcher at bin/cxc.mjs, so every marketplace install has a working terminal surface: node "<pluginRoot>/bin/cxc.mjs" <command>. When cxc is not on PATH, the SessionStart banner prints the exact resolved invocation, and injected directives use it. A PATH-level cxc / codexclaw binary remains a repo-checkout convenience (npm link or a shell alias to bin/codexclaw.mjs). The payload dispatcher excludes gui and map (repo-checkout-only) and prints a pointer for those instead.

Live commands

Command	Delegates to	Purpose
cxc enable	config-guard	Turn on the Codex feature flags codexclaw declares, back up config.toml, and write the install manifest. (Skills, hooks and MCP are registered by plugin.json, not by this command.)
cxc disable / cxc uninstall	config-guard	Revert exactly what codexclaw turned on, per flag and per managed key, and opt out of SessionStart self-heal.
cxc status	config-guard	Report the live enabled-state of the declared feature flags.
cxc orchestrate <verb>	pabcd-state	Drive PABCD phase state (see below).
cxc freeze	pabcd-state	Freeze the interview plan and surface the goal-activation handoff.
cxc metric <verb>	pabcd-state	Record/show true-objective metrics for emergence-harness loops.
cxc divergence <verb>	pabcd-state	Record divergence mode and grounded candidate archive entries.
cxc loop <verb>	pabcd-state	Manage the project-local durable goalplan: init, show, validate, steer, ready, add-criterion, add-work-phase, add-task, complete-task, and meet-criterion.
cxc goalplan <verb>	pabcd-state	Deprecated alias for cxc loop <verb>.
cxc plan init <slug>	pabcd-state	Scaffold the devlog/_plan unit the P→A plan gate verifies.
cxc scan record	pabcd-state	Record an interview contradiction-scan round (see below).
cxc doctor	cxc-ops	Component health plus ocx detection status.
cxc reset	cxc-ops	Clean up codexclaw operational state.
cxc hooks retrust	cxc-ops	Re-trust plugin hook hashes after editing hook JSONs.
cxc gui	gui	Start the local dashboard (Vite).
cxc subagents	subagent-config	Read/write per-role subagent model and prompt config.
cxc map	repo-map	Generate a ranked repository map from the repo-map skill.
cxc provider	provider-bridge	Show read-only opencodex (ocx) provider status (detect mode).
cxc chat search / cxc chat index	recall	Search or index read-only Codex rollout history under CODEX_HOME / ~/.codex.
cxc memory search	recall	Search read-only Codex memory artifacts under CODEX_HOME / ~/.codex.
cxc memory status [--json] [--home PATH]	recall	Read job-history counts and explicitly unknown extraction route/startup guard; no quota bypass or backlog inference.
cxc memory allow-write	pabcd-state	Record a one-shot grant so the next memory write in that session passes the PreToolUse memory-write gate (cxc memory allow-write --session <id>).
cxc skill search / cxc skill show	skill-search	Search or show remote dormant skills from jaw, hermes, clawhub, or GitHub sources.
cxc serve	messenger-bridge	Start the opt-in loopback dashboard/API/messenger bridge on 127.0.0.1.
cxc service	messenger-bridge	Install, uninstall, or inspect the macOS launchd service for cxc serve.

Note

The former hyphenated chat-search wrapper is not a live command. Recall is exposed as cxc chat search, cxc chat index, and cxc memory search.

reset sub-grammar

cxc reset [--state|--generated|--goalplans|--all]

orchestrate sub-grammar

cxc orchestrate <I|P|A|B|C|D|status|reset> [--session <id>] [--cwd <path>] [--json] [--attest '<json>']

Verb	Meaning
I	Enter the Interview phase.
P A B C D	Advance the PABCD cycle (forward transitions need --attest).
status	Print the current phase and flags.
reset	Return the phase to IDLE.

status and reset here are phase-control commands, distinct from the top-level cxc status (config-guard) and cxc reset (cxc-ops).

Attest shape

{ "from": "P", "to": "A", "did": "what you actually did this phase" }
// C -> D additionally requires:
{ "from": "C", "to": "D", "did": "...", "checkOutput": "<test/build tail>", "exitCode": 0 }

metric sub-grammar

cxc metric record --session <id> --name <metric> --value <number> [--source operator-entered|evaluate.sh] [--work-phase <id>] [--json]
cxc metric ingest --session <id> [--source evaluate.sh] [--work-phase <id>] [--json] < output.txt
cxc metric show --session <id> [--json]
cxc metric kind --session <id> [satisfy|maximize] [--json]

metric ingest reads METRIC name=value lines from stdin. Remote judge scores are operator-entered; local harness output should use source=evaluate.sh.

divergence sub-grammar

cxc divergence mode --session <id> on|off [--cwd <owner-root>] [--collapse P|D] [--reason <text>]
cxc divergence candidate add --session <id> [--cwd <owner-root>] --kind strong-1|add-1|alternative --title <text> --rationale <text> --source <url> [--source <url>...]
cxc divergence candidate list --session <id> [--cwd <owner-root>] [--json]

Use --cwd <owner-root> when recording from a child worktree so the owner worktree keeps the single candidate archive.

candidate add also accepts --status proposed|built|checked|kept|discarded, --change-class parameter-tweak|branch-toggle|state-space-redesign|evaluator-change, --killed-at-phase P|A|B|C|D, --worktree <path>, and --json.

freeze sub-grammar

cxc freeze [--dry-run] [--cwd <path>] [--session <id>]

scan sub-grammar

cxc scan record --session <id> [--contradictions N] [--high N]

scan record records one interview contradiction-scan round. It performs both halves of the recording contract: it appends a scan_completed event to the per-session interview ledger (.codexclaw/interviews/<id>.jsonl) and increments the tracker’s scanRounds / lastScanRoundId counters via session state. Recorded rounds are what the I→P readiness gate reads, so scans count toward the gate without an override. --session is required; there is no latest-session fallback for mutating commands.

loop / goalplan sub-grammar

cxc loop init --objective <text> [--session <id>] [--criterion <text>]... [--schema-version <n>] [--cwd <path>]
cxc loop show (--slug <slug> | --objective <text> | --session <id>) [--cwd <path>]
cxc loop validate (--slug <slug> | --objective <text> | --session <id>) [--cwd <path>]
cxc loop steer --session <id> --batch-json <path-or-json> [--cwd <path>]
cxc loop add-criterion --session <id> --criterion <text> [--surface logic|web|tui|desktop] [--cwd <path>]
cxc loop add-work-phase --session <id> --id <id> --title <text> [--depends-on <id>]... [--cwd <path>]
cxc loop ready (--slug <slug> | --objective <text> | --session <id>) [--json] [--cwd <path>]
cxc loop add-task --session <id> --work-phase <id> --id <id> --title <text> [--depends-on <task-id>]... [--cwd <path>]
cxc loop complete-task --session <id> --work-phase <id> --id <id> --outcome <text> [--cwd <path>]
cxc loop meet-criterion --session <id> --id <id> --evidence <text> [--cwd <path>]
cxc loop --help

Unknown flags, stray positionals, missing values, and flags on the wrong verb are rejected before dispatch. Every value flag also accepts --flag=value; use that form for a value that starts with --. cxc goalplan <verb> is a deprecated alias that dispatches to the same component and parser.

map sub-grammar

cxc map [path] [--map-tokens N|--budget N] [--chat-files <path>...] [--mentioned-idents <name>...] [--verbose]

map runs the repo-map skill’s vendored tree-sitter/PageRank mapper. It is a stateless overview command for unfamiliar repositories and degrades to an install hint when Python dependencies are missing.

skill sub-grammar

cxc skill search "<query>" [--source jaw|hermes|clawhub|gh|all] [--limit N] [--json] [--refresh]
cxc skill show <id> [--source jaw|hermes|clawhub] [--json] [--refresh]

skill delegates to the skill-search component for remote dormant-skill search/show. It caches catalog fetches under the user-level codexclaw cache and can serve stale cache entries if a remote source is unavailable.

recall sub-grammar

cxc chat search "<query>" [--days N] [--cwd PATH] [--role user|assistant|tool] [--source main|subagent|all]
                         [--limit N] [--context N] [--any] [--all] [--no-tools]
                         [--recent] [--rank] [--scan] [--no-refresh] [--json] [--full] [--home PATH]
cxc chat index [--rebuild] [--status] [--json] [--home PATH] [--index-path PATH]
cxc memory search "<query>" [--days N] [--limit N] [--any] [--no-synonyms]
                          [--cwd PATH] [--cwd-only PATH] [--no-chat] [--json] [--home PATH]
cxc memory allow-write --session <id>

--rank names the default relevance order. Memory --days defaults to 0 (full history); chat --days defaults to 7. cxc enable turns on memories.dedicated_tools so the native memories.search / read / list / add_ad_hoc_note tools appear. The write tool still needs an explicit user request or cxc memory allow-write.

Recall commands are read-only against Codex data. cxc chat index writes only the derived codexclaw sidecar index.

cxc chat search ranks by relevance: a BM25 lane and a trigram lane are fused with reciprocal rank fusion, and freshness breaks ties among comparable matches. --recent restores plain newest-first ordering. The raw scan path (--scan) has no lane scores and is always newest-first.

subagents sub-grammar

cxc subagents
cxc subagents register <architect|executor>
cxc subagents get <explorer|reviewer|executor|architect>
cxc subagents set <explorer|reviewer|executor|architect> --mode default|model [--model <id>] [--prompt <text>|--clear-prompt]

serve / service sub-grammar

cxc serve [--port <n>] [--cwd <path>]
cxc service install [--port <n>]
cxc service uninstall
cxc service status

serve / service are the messenger bridge’s opt-in loopback surface: a local 127.0.0.1 dashboard/API server plus messenger adapters that relay to stock codex exec. They are not an external orchestrator server.

Memory status observation scope

cxc memory status reads the native jobs database without changing it. The JSON fields effectiveExtractionRoute and startupGuardDecision remain unknown: a successful job or a quota-like error cannot prove the current startup guard. observationSource: "jobs-db" names the collector, not successful database access; read state and detail for availability. Existing recall/chat fallback remains independent of native memory generation. Provider-bridge’s default provider does not establish the provider or account used for a memory extraction.