CLIarity

Clarity for your local AI toolchain.

CLIarity is a Windows-first desktop utility that diagnoses local AI coding-agent
toolchains: what is installed, where it actually resolves from, what version it
reports, and which entries on your PATH are shadowing each other.

CLIarity is read-only. It inspects and reports. It does not edit PATH,
write to the registry, install software, or modify any agent configuration.

Status: first slice implemented. CLIarity detects Git, Node.js, npm, and Claude
Code, builds on Windows, and passes its test suite. It has not been through a release,
and the GUI has not yet been driven interactively end to end. See docs/ROADMAP.md for
what is verified and what is not.

Why

Broken agent toolchains on Windows usually fail for unglamorous reasons: a
.cmd shim earlier on PATH than the real executable, two Node installs
disagreeing about which npm wins, a tool that is installed but not on PATH at
all. The failure surfaces as a confusing error inside an agent, far from the
cause.

CLIarity answers the boring questions directly, in one place, without asking you
to paste environment variables into a chat window or run a script you have not
read.

What it does

• Reports OS family, CPU architecture, and the configured command processor.
• Detects Git, Node.js, npm, and Claude Code.
• For each tool: resolution status, the executable path actually selected,
  the parsed version, and warnings when multiple candidates are found on PATH.
• Shows a per-tool status of Found, Missing, Warning, Timeout, or Error, so one
  slow or broken tool never hides the rest of the results.
• Produces a sanitized report you can copy to the clipboard and paste into a bug
  report, with home-directory paths rewritten to %USERPROFILE%.

It resolves executables the way a shell does, trying PATHEXT extensions before the
bare filename. That is what makes npm and claude resolve to their runnable .cmd
shims rather than to the extensionless Bash scripts sitting beside them. See
docs/adr/0003-windows-executable-resolution-order.md.

What it will not do

Not in the first slice, and some of it not ever:

• Edit PATH or any environment variable.
• Write registry values.
• Install, update, or remove software.
• Read .env files, ~/.claude, credential stores, or authentication tokens.
• Modify agent configuration files.
• Save reports to disk (the first slice keeps the report in memory; you copy it
  deliberately).
• Send anything anywhere. There is no telemetry, no account, and no network
  dependency.

Repair features are planned for a later phase and will require preview,
validation, backup, and rollback before any write happens. See docs/ROADMAP.md.

How it stays trustworthy

The security posture is structural rather than promised:

• The frontend has no process or filesystem API. Everything crosses a typed
  Tauri command boundary into Rust.
• CLIarity never constructs user-controlled shell command strings. Commands are
  resolved to absolute paths and invoked with static, separately supplied
  arguments. Windows .cmd and .bat execution may internally use the Windows
  command processor through Rust's protected batch-script handling.
• Every spawned command has a timeout and a bounded amount of retained output.
• Raw stdout and stderr never reach the frontend and never appear in an export.
  The report is built from an explicit allowlist of fields.

docs/THREAT-MODEL.md documents the trust boundaries and the risks that are
accepted rather than mitigated.

Requirements

• Windows 10 or 11
• WebView2 Runtime (preinstalled on Windows 11)

To build from source you additionally need a Rust MSVC toolchain, Microsoft C++
Build Tools, Node.js LTS, and pnpm. See CONTRIBUTING.md.

Development

pnpm install

pnpm tauri dev

To see the diagnostic core's real output without building the desktop shell, run the
headless example. It prints the same report the interface consumes, which is the quickest
way to check a detector you are working on:

cargo run --example diagnose --manifest-path src-tauri/Cargo.toml

The full verification suite, which must pass before a pull request, is listed in
CONTRIBUTING.md.

Documentation

Contributing

See CONTRIBUTING.md. Adding a detector for a new tool is designed to be a
self-contained first contribution.

Security

Report vulnerabilities privately. See SECURITY.md.

Licence

MIT. See LICENSE.