@cruxai/cli

better agentic engineering.

crux reads the session logs your AI coding assistants already write and turns them into analytics — either locally, as a self-contained HTML report you open from disk, or in your organization's own cloud, where the crux dashboard aggregates them across a team.

The package is @cruxai/cli; the command it installs is crux.

npm i -g @cruxai/cli
crux report --open

That first run touches no network and needs no account — it parses the logs already on your machine and writes an HTML report you open from disk. Everything else is opt-in.

Node.js 20+. No runtime dependencies; the CLI ships as a single bundled file.

crux --help prints the full command list; crux <command> --help does the same without running the command. crux --version prints the bare version and nothing else.

Harnesses it reads

Claude Code, Codex, OpenCode, Cursor, GitHub Copilot (CLI and app), Xcode, and VS Code agents. crux finds their logs in the default locations each tool writes to — there is nothing to configure and nothing to point it at.

crux is read-only on those files. It never modifies, moves, or deletes a session log.

Start here: a local report

crux report

Writes ./crux-report/ — four files (index.html, app.js, analyzer.js, styles.css) — and prints the path. Open index.html in any browser.

The report makes no network calls: not while generating, not when you open it. No CDN, no analytics beacon, not even a webfont, so it renders identically on a plane and on your desk. Both halves of that promise are pinned by tests, not just intent.

Secrets are stripped by default. Pass --no-redact to keep raw session text — useful when debugging your own logs. The banner at the top tells you which mode ran. Either way the output is a copy of your session history sitting on disk: keep crux-report/ out of git, and think before forwarding it.

crux report [--out <dir>] [--open] [--no-redact]
            [--from <date>] [--to <date>] [--workspace <name>] [--harness <name>]

| Flag | Description | |------|-------------| | --out <dir>, -o | Write somewhere other than ./crux-report | | --open | Open the report in your browser when it finishes | | --no-redact | Keep raw session text instead of stripping secrets | | --from / --to | Restrict to a date range (YYYY-MM-DD) | | --workspace <name> | Open scoped to one workspace | | --harness <name> | Only sessions from one assistant, e.g. --harness Claude |

Sections: Dashboard, Timeline, Output, Patterns, Insights, Workflows, Anti-Patterns (with the rule browser, coverage heatmap, and DSL reference), Context Health, and SDLC.

Not in the report, because a static file cannot support them: the rule editor and playground (they write rules back to disk), and the learning pages (they need a language model). Rules render read-only — edit one in your rules directory and re-run crux report.

Other local commands

These read your logs and print to the terminal. Like crux report, they make no network calls at all.

crux context-health

Score how well you are feeding context to your assistants: agentic-readiness checks and an audit of your instruction files (CLAUDE.md, .github/copilot-instructions.md, and friends).

crux context-health [--workspace <id>] [--from <date>] [--to <date>]
                    [--harness <name>] [--json] [--no-color]

Team analytics: enroll and sync

Everything above is local and account-free. enroll and sync are the two commands that send anything anywhere — they upload a redacted envelope to storage your organization owns, where the crux dashboard turns it into per-person and per-team analytics.

crux enroll

Link this machine to your organization, once. Opens a browser page where you approve the device; the returned device token goes into the OS keychain, never into a file in your project.

crux enroll [--no-open] [--json]

crux sync

Parse, redact, and upload.

crux sync [--dry-run] [--full] [--scheduled] [--json]

| Flag | Description | |------|-------------| | --dry-run | Print exactly what would be uploaded — schema version, session count, byte counts, date range, destination prefix — and upload nothing | | --full | Ignore the sync watermark and re-send everything, not just what is new | | --scheduled | Unattended mode, used by the scheduled agent | | --json | Machine-readable output |

Start with crux sync --dry-run. Only enrolled machines can sync; nothing is uploaded before you run crux enroll.

crux agent

Install, inspect, or remove a scheduled unattended sync, so nobody has to remember to run it.

crux agent install|status|uninstall [--json]

Environment variables

| Variable | Purpose | |----------|---------| | CRUX_API_URL | Override the control-plane URL used by enroll and sync | | CRUX_DEVICE_TOKEN | Supply a device token instead of reading the keychain (CI) | | NO_COLOR | Disable ANSI color, as per no-color.org |

Privacy

• Read-only — crux never modifies your session files
• Nothing leaves unenrolled — crux enroll is the one moment you opt this machine in, and crux sync is the only command that uploads. crux sync --dry-run shows the payload first
• Redacted before it leaves — secrets are stripped on your machine, before the upload, not after it arrives
• Your storage — on the aws provider the bucket and the processing worker live in your own AWS account, so raw session content never reaches crux's infrastructure. The hosted provider trades that guarantee for zero setup, and says so
• No telemetry — crux collects nothing about your use of crux itself
• No third parties — the CLI calls no LLM and no external service. enroll and sync talk to your control plane and your storage, and nothing else does

Links

• Source, issues, and the hosted side of crux: github.com/ronka/crux-mono
• License: MIT

crux originated as a fork of the MIT-licensed microsoft/AI-Engineering-Coach. It is an independent project and is not affiliated with, endorsed by, or sponsored by Microsoft.