@use-crux/local

# Install
npm install -g @use-crux/local
# or download the binary from the releases page

Overview

The Crux local runtime is a Go binary that hosts the HTTP API, WebSocket/SSE subscriptions, React devtools UI, TUI, SQLite-backed observability and Review services, index services, Eval coordination, and lint presentation. File-backed observability databases use SQLite WAL, busy timeouts, and pooled connections for concurrent flush/read workloads; in-memory databases stay single-connection for tests. Node.js is used only for bounded helper workers such as Project Index indexing, source resolution, and Eval execution.

All query commands support a --json flag for machine-readable output. Table output is the default for human consumption.

crux dev

Start the devtools server. On a capable interactive terminal, the workbench TUI is selected automatically. Browser launch is always explicit.

crux dev
crux dev --port 4500
crux dev --tui            # Require the interactive terminal dashboard
crux dev --no-tui         # Server and plain terminal output only
crux dev --open           # Open browser devtools after startup
crux dev --tunnel         # Create a public tunnel

The Go server owns HTTP, WebSocket/SSE, read models, and UI serving. If the port is already in use, it automatically tries the next available port (up to +9).

Requires: Node.js >= 24 for helper workers that import project TypeScript.

On startup, crux dev generates or reuses a scoped observability ingest token at .crux/devtools/ingest-token and prints it as CRUX_DEVTOOLS_TOKEN=.... Use that token with a public tunnel origin when cloud runtimes need to post records back to your local server.

The listener and TUI appear before Project Index and Runtime-file warmup finish. That warmup runs in the background, so a configuration or source problem does not make the workbench disappear. The diagnostic view explains what could not be refreshed, preserves the last working generated files, and retries after the next relevant save.

The local HTTP API, in-process DirectClient, and WebSocket snapshot payloads share the same backend read-model registry. This keeps route parameters, query parsing, not-found handling, live invalidation messages, and initial snapshot payloads aligned between custom tooling and the embedded devtools UI.

Run-detail reads also expose optional currentProjectHealth context. Crux Local correlates the run's recorded definition references with materialized lint findings from the current Project Index snapshot, preserving active/suppressed state and complete directive evidence. The context is deliberately read-time: it is not historical run telemetry, creates no suppression span, and does not change run status. No available Index omits the field; an available Index with no related findings returns zero counts and an empty list.

Observability and Eval run lists are newest-first pages by default so live web/TUI refreshes stay responsive on large local histories. Observability lists read ingest-time count and usage rollups from SQLite; the web devtools runs table groups by root sessionId and displays those token, cost, and graph-count rollups directly. Single-run detail endpoints remain exact, while focused streaming spans read token.chunk text through the lazy span-events endpoint instead of loading every chunk into the run-detail graph. Use explicit limit/offset query parameters on the HTTP list endpoints when building custom local tooling that needs a different page size.

For retained PromptText input evidence, the observability service persists the normal messages artifact and reconstructs one strict Run Detail userPrompt record after restart. Its segments must reproduce the captured text exactly; invalid provenance is omitted, allowing Devtools to use the captured plain prompt instead. No extra database payload, preview cache, or provider request is created.

crux lsp

Run Crux lint diagnostics and suppression actions in editors over the Language Server Protocol. The server uses stdio and either attaches to a matching crux dev process or indexes the workspace itself. See the dedicated crux lsp reference for editor setup, settings, and handover behavior.

When the VS Code PromptText commands are used with an attached crux dev, Local also owns two transient browser routes:

• exact preview discovers a currently published configure({ prompts }) target and dispatches observational preview() only after explicit confirmation;
• latest Run resolves the current Prompt owner and newest captured operation at click time, or shows the Prompt's Catalog empty state.

Both routes are loopback-only Devtools facades with no-store responses, custom-header protection, strict bounded schemas, and cancellation on navigation. Exact-preview inputs and results are not written to observability, cache, Project Index, URLs, browser storage, logs, or WebSocket broadcasts. The exact-preview page renders system composition, user-prompt provenance, token totals/budget, dropped and excluded contexts, and validation issues as structured Devtools content; raw JSON is secondary disclosure only. See PromptText editor support for the complete user workflow and limitations.

crux editor install

Install the editor extension from the GitHub Release matching the running CLI:

crux editor install vscode
crux editor install cursor
crux editor install vscode --download-only ./artifacts

The explicit target is required. Normal mode downloads crux-vscode-<version>.vsix and SHA256SUMS, verifies the exact checksum, and then invokes code or cursor with --install-extension ... --force. --download-only <directory> writes the verified VSIX atomically without requiring or executing an editor. It refuses to replace a different existing file.

The running crux --version is the only release selector. Development builds, missing releases, malformed or absent checksum entries, oversized downloads, checksum mismatches, missing editor CLIs, and failed editor installations all fail without selecting another version. Temporary installation files are removed after success, failure, or cancellation.

GitHub Releases are currently the only extension distribution channel; the extension is not yet published to Visual Studio Marketplace or Open VSX. See VS Code & Cursor for installation, verification, upgrades, and the PromptText workflow.

crux traces

List recent traces or show trace detail.

crux traces                        # List all recent traces
crux traces <trace-id>             # Show full trace detail
crux traces --prompt editor.seo    # Filter by prompt ID
crux traces --session abc123       # Filter by session ID
crux traces --live                 # Tail traces in real-time
crux traces --json                 # Output as JSON

Table columns: TIME, STATUS, PROMPT, MODEL, DURATION, TOKENS, COST

Detail view (with trace ID argument) shows: trace ID, provider, duration, session, role, error, token breakdown (input/output/cache), cost, fallback attempts, streaming metrics (TTFT, throughput), and tool calls.

crux stats

Show aggregate statistics across all traces.

crux stats              # Show current stats
crux stats --live       # Continuously update on new events
crux stats --json       # Output as JSON

Shows: execution counts (success/error/running), average duration, error rate, total tokens, total cost, average cost per call, streaming metrics, memory read/write counts, compaction counts, budget level, agent coordination stats (handoffs, delegates, blackboard updates), tool call counts, and security warnings.

Also displays a per-prompt usage breakdown table with call counts, errors, average duration, and total cost.

crux cost

Show tracked model spend from the latest cost report.

crux cost            # Show the cost breakdown
crux cost --json     # Output as JSON

Prints the total spend and event count, then per-model and per-prompt breakdowns, followed by any threshold warn/limit events. Requires withCostTracking() in your Crux config (without it, no cost events are recorded and the command says so).

crux config

Render the effective Crux configuration: every domain config() accepts, with each value resolved and tagged by where it came from. crux config inspect imports your crux.config.ts in inert CRUX_INDEX=1 mode (no runtime side effects: no observability transport, no bridge, no store) so the view reflects your explicit overrides, not just defaults. For the full option surface, see Config.

crux config inspect
crux config inspect --json
crux config inspect --cwd packages/backend
crux config inspect --config crux.config.ts

The view is organized by config() domain, in interface order:

• Project: root and package name
• Config file: the resolved file, how it was located, its load status, and any import error
• generation: autoEscape, securityWarnings, and whether a tokenizer / middleware is bound
• indexer: extension trust mode and configured extensions
• observability: enabled, serverUrl, token presence, and whether a custom transport is bound
• devtools: serverUrl and whether a bridge is configured
• persistence: whether a global store is bound
• lint: selected profile and rule-override count
• plugins: installed plugin names
• Discovered: a compact count of authored definitions / relations / Evals (context, not config; the full index lives behind crux index)
• Diagnostics: config-load and project-model findings

Every value carries a dim origin tag so a zero-config project reads as "these are the defaults Crux applied": (default) for a built-in default, (config) for an explicit value from crux.config.ts, (package.json) for package-derived values, and (set) for a bound non-serializable value (store, tokenizer, middleware, transport). The config-file status uses a colored glyph (✓ loaded, ✗ missing/import-failed, ● unrecognized). Paths are normalized for readability: the project root collapses to ~ and every other path is shown relative to it (.crux/evals, evals/...).

On an interactive terminal an animated loader is shown while the config resolves; color and the loader are suppressed under --no-color, NO_COLOR, or a non-TTY pipe, and --json emits the machine-readable form (each setting as { value, origin }, full absolute paths preserved). Worker lifecycle logs are silenced for this one-shot command. Set CRUX_STARTUP_DEBUG=1 to surface them when troubleshooting.

A broken config never makes inspection fail: an import error degrades to an all-defaults view with an import-failed config status and the error surfaced under Diagnostics.

crux setup

Inspect project-level setup contributed by Crux subsystems and safely apply fixes.

crux setup                 # Read-only inspection (same as --check)
crux setup --check
crux setup --apply         # Apply safe-additive actions, then re-inspect
crux setup --json          # Stable machine-readable report
crux setup --cwd packages/backend

Every planned action carries a classification, and apply mode runs only actions classified as safe-additive. It never automatically performs destructive migrations, paid provisioning, production mutations, credentials, or ambiguous edits; actions requiring approval remain findings with exact remediation steps. Apply mode reinspects after safe actions and refreshes generated Runtime files only when the final setup report has no error. Check mode never writes.

Findings may include a docs URL, a copy-paste remediation, and a privacy-safe coding-agent prompt. They never include environment values, credentials, or connection strings.

Safe-additive setup is idempotent. A failed later action does not roll back earlier successful actions; rerun crux setup --apply after correcting the reported problem.

crux runtime generate

Refresh generated Runtime files once using the same canonical pipeline as setup, development warmup, and build integrations.

crux runtime generate
crux runtime generate --cwd packages/backend
crux runtime generate --json

Use this command for CI, recovery, or direct inspection. Ordinary callable Evals remain valid and run in the local coordinator; Crux automatically puts only host-required Eval arms in host artifacts. During normal development, crux dev keeps files fresh and retries after relevant saves, so manual generation is not a prerequisite for each start.

crux runtime worker

Run exactly one generated Runtime program in a supervised Node process. The exact syntax is crux runtime worker [flags] and positional arguments are rejected.

crux runtime worker
crux runtime worker --cwd packages/backend

The command accepts no positional arguments. It requires Node.js, a current .crux/generated/runtime/{manifest.json,program.ts} pair, and project config that resolves to node({ store: postgres() }) or an equivalent in-process Runtime with durable maintenance ownership.

Startup fails actionably when the project root cannot be resolved, Node or the embedded worker cannot start, config import fails, the Runtime is missing or host-bound, durable ownership is unavailable or already held, artifacts are missing/stale/invalid/incompatible, a target import times out, or program targets do not match the manifest. It never starts maintenance with a partial artifact set.

SIGINT and SIGTERM prevent future maintenance ticks and allow the Node worker 10 seconds to settle ownership acquisition or the active tick and release ownership. The Go supervisor forwards shutdown to the process tree and force-stops it after 11 seconds.

See the Node execution worker guide and operational recipes.

crux catalog

Inspect the current authored Catalog through the running local server. Catalog responses are deterministic, omit opaque compiler metadata, and keep unknown backend, watch, cache, or manifest state explicit.

crux catalog                         # List every definition kind
crux catalog list --kind agent       # Filter by exact definition kind
crux catalog show agent:writer       # Definition, relations, Health, Eval, Runs
crux catalog status                  # Compiler, cache, watch, and manifest state
crux catalog explain agent:writer    # Why the compiler recognized this definition
crux catalog import ./manifest.json  # Verify and retain immutable history

catalog list sorts by kind and definition ID. show returns the safe current read model with source references, incoming/outgoing relations, applicable diagnostics and lints, Eval summary, and bounded runtime activity. explain uses durable compiler fact provenance and reports unresolved relations only when compiler diagnostics establish them; it never guesses from source text or extractor names. When contributor attribution is present, the reason names each canonical extension@version/extractor (or first-party extractor) while the producer continues to identify the phase worker/backend. It never exposes raw AST/checker objects. Source paths are repository-relative and fail closed when they are outside the project.

Catalog and Index Health present active and suppressed lint findings as separate totals. Active-only severity, rule, affected-definition, badge, and default verdict counts never include suppressed rows. Retained suppressed rows remain auditable with an explicit state plus distinct finding source and directive location, scope, and optional reason.

catalog status reports indexing phases, semantic execution mode, cache hit and age, watch plan/fallback and changed/affected counts, last indexing error, manifest count, and a current identity when a verified default artifact or one unambiguous imported manifest exists. Unavailable values render as unknown or are omitted in JSON.

The v1 CLI explains the current Catalog. Historical selector flags are not yet available; run detail continues to resolve exact named deployment manifests without falling back to the current checkout.

crux index (compatibility)

crux index remains available during the beta. Its default list and definition detail delegate to the canonical Catalog projections; category keywords and the explicit daemon rebuild command remain compatible.

crux index                  # Delegates to crux catalog list
crux index prompts          # List prompts only
crux index contexts         # List contexts only
crux index tools            # List tools only
crux index definitions      # List all discovered definitions
crux index diagnostics      # List index diagnostics
crux index reindex          # Rebuild source definitions and local Eval records
crux index agent:writer     # Delegates to crux catalog show
crux index --json           # Output as JSON

Use crux catalog for new automation. crux index reindex still requires the running dev server and forces a source/Eval rebuild; crux check and crux manifest are daemon-free CI/build surfaces. crux dev indexes source files and local Eval records at startup, then watches source/config files for debounced incremental refreshes.

crux inspect

Show token breakdown for a prompt from recent traces.

crux inspect <prompt-id>     # e.g., crux inspect editor.seo
crux inspect editor.seo --json

Finds the most recent successful trace for the given prompt ID and displays: system parts breakdown (source and token count per part), dropped contexts (with priority), and total prompt tokens.

crux lint

Check authored Crux project health against a lint profile. The default path indexes the project once and does not require crux dev; use --server only for compatibility when you intentionally want the running daemon snapshot.

crux lint                          # Run the recommended profile
crux lint --profile strict         # Use a stricter profile
crux lint --fail-on warning        # Exit 1 if any warning (or error) is found
crux lint --include-suppressed     # Also show source-comment suppressed findings
crux lint --json                   # Output as JSON
crux lint --root packages/app      # Check another project without a daemon
crux lint --server                 # Read the running devtools snapshot

Lists findings sorted by severity (error · warning · info), each with its rule id, target definition, source file:line, and (when available) the problem, rationale, suggested fix, and docs link. With --fail-on, a matching active finding sets exit code 1 so the command can gate CI. Suppressed findings are hidden by default; --include-suppressed shows their directive scope, location, and optional reason without allowing them to fail the gate.

crux check

Compile the same Project Index pipeline once and apply an explicit CI gate. Unlike crux lint, check defaults to --fail-on error. It groups compiler diagnostics separately from authored-system findings and never requires a running daemon.

crux check
crux check --profile strict --fail-on warning
crux check --root packages/app --config crux.config.ts
crux check --project-id storefront --json

Exit 0 means compilation completed without a selected finding meeting the gate. Exit 1 means the gate matched. Exit 2 means configuration, compiler, protocol, cache integrity, or another operational failure prevented a trustworthy check. JSON v1 excludes timestamps and durations; incidental worker diagnostics remain on stderr. Check summaries and gates count active findings only, even when --include-suppressed adds retained rows to the displayed finding list.

crux manifest

Compile a privacy-safe, content-addressed deployment manifest without a running daemon. --project-id is required and identifies the logical project; it is intentionally outside the content hash.

crux manifest --project-id storefront
crux manifest --project-id storefront --root packages/app --out dist/project-index.manifest.json --json

The default output is <root>/.crux/project-index.manifest.json. The command uses the same one-shot pipeline as crux check, waits for semantic indexing, and writes atomically only after verifying the compiler artifact. Operational or compiler failure exits 2 and leaves any previous valid artifact untouched. JSON mode writes one deterministic v1 summary to stdout; the output file always contains the full manifest.

crux catalog import

Verify and persist an immutable historical manifest in the current project's local Catalog store:

crux catalog import .crux/project-index.manifest.json
crux catalog import /tmp/build-manifest.json --json

Import is idempotent for an existing (projectId, manifestId) with identical content. Invalid hashes, malformed artifacts, and tuple collisions exit 2 without changing the store.

crux eval

Discover and run one default Eval export per *.eval.ts file. The shorthand crux eval [selector...] is equivalent to crux eval run [selector...].

crux eval
crux eval support --case refund --variant cheaper
crux eval list
crux eval show <run-id>
crux eval diff <run-a> <run-b>
crux eval baseline set <run-id> [--variant <name>]

Selectors match Eval ids or source paths. Every run includes Current. Pass --variant at most once to make one named Variant blocking alongside Current; repeat --case to select multiple Cases.

Run flags

A plan can make one authenticated, read-only Runtime manifest request when remote work is required. If credentials are absent it reports the remote work as unverified and prints setup instructions. --offline --plan never accesses the network.

The Devtools Run Eval action invokes this same coordinator through the project-local server. It explicitly confirms unknown-cost external calls, keeps the same Runtime readiness and preflight checks, and opens the persisted run.

Commands and exit codes

list performs discovery without execution. show inspects a saved run, diff compares two saved runs, and baseline set accepts one complete run arm as the Eval's explicit Baseline.

Files and privacy

Crux writes private run and evidence data under .crux/evals/; keep that directory gitignored. Commit authored Eval files, sibling .cases.jsonl Case files, explicit files referenced by caseFile(), and .baseline.json Baseline pointers when they are intended to be shared.

See the Eval guide, Eval API reference, and Runtime host setup.

crux flows

List runtime flow sessions.

crux flows            # List all flow sessions
crux flows --json     # Output as JSON

Table columns: TIME, NAME, STATUS, SESSION

crux completion

Generate a shell completion script for crux. Pipe it into your shell's completion system, or source it from your shell profile.

crux completion bash         # Print a bash completion script
crux completion zsh          # Print a zsh completion script
crux completion fish         # Print a fish completion script
crux completion powershell   # Print a PowerShell completion script

# Example: load zsh completions for the current session
source <(crux completion zsh)

Run crux completion <shell> --help for shell-specific installation steps.

Configuration

The CLI discovers the devtools server by connecting to localhost on the configured port (default 4400). Remote observability and cloud upload targets must be configured explicitly by project code. The Eval coordinator resolves the project from --cwd or the current project context, then loads that project's installed @use-crux/core so discovery, execution, and observability share one runtime instance.

Set the CRUX_STARTUP_DEBUG=1 environment variable to show startup timing diagnostics without the --startup-debug flag.

Related

• Guide: Devtools
• Guide: Evals