llm-env-check

llm-env-check is a local-only CLI that inspects a small set of system capabilities and recommends local LLM models and runtimes that may fit the detected hardware.

Recommendations are estimates, not guarantees. Actual inference performance depends on runtime configuration, context size, quantization, background load, and hardware drivers.

Requirements

To install and run the CLI, users need:

• Node.js version 18 or newer
• npm, which is included with standard Node.js installations
• Windows, macOS, or Linux

Users can check their installed versions with:

node --version
npm --version

The package declares "node": ">=18" in package.json, so npm can warn users when their Node.js version is unsupported. A specific npm version is not required for normal installation and use.

Install

For local development, run these commands from the project folder:

npm install
npm run build
npm link
llm-env-check

npm link registers the local build as a global command. After linking, you can run llm-env-check from any folder on your machine.

For package consumers:

npm install -g llm-env-check
llm-env-check

Usage

| Command | What it does | | --- | --- | | llm-env-check | Scans the supported system capabilities and shows general local LLM recommendations. The default profile is chat. | | llm-env-check --profile coding | Prioritizes models suited to code completion, programming questions, and repository assistance. | | llm-env-check --profile chat | Prioritizes efficient models for everyday conversations and general questions. | | llm-env-check --profile writing | Prioritizes models suited to drafting, editing, coherence, and longer-form writing. | | llm-env-check --profile agentic | Prioritizes models suited to reasoning and tool-friendly workflows, such as local assistants that perform multi-step tasks. | | llm-env-check --json | Returns the scan as machine-readable JSON instead of formatted terminal text. Use this for scripts, automation, or saving structured reports. | | llm-env-check --safe | Explains the privacy and security boundaries: what is checked, what is never checked, and why the scan is read-only. | | llm-env-check --help | Shows the available options and short examples directly in the terminal. | | llm-env-check --color auto | Uses colors only when output is displayed in an interactive terminal. This is the default. | | llm-env-check --color always | Forces ANSI colors, including when output is redirected. This can help in supported CI systems. | | llm-env-check --color never | Disables ANSI colors. | | llm-env-check --no-color | Disables ANSI colors and overrides other color settings. |

For example:

# Check whether this computer is a good fit for local coding models.
llm-env-check --profile coding

# Review the privacy boundaries without running a hardware scan.
llm-env-check --safe

# Save structured results for another local tool to read.
llm-env-check --json > llm-environment.json

Profiles adjust recommendation order:

| Profile | Focus | | --- | --- | | coding | Code completion and repository assistance | | chat | Conversational efficiency | | writing | Coherence and long-form generation | | agentic | Reasoning and tool-friendly workloads |

Privacy Promise

The tool is local-only, read-only, and has no telemetry, tracking, analytics, cloud dependency, API keys, or subscriptions. It does not upload or transmit data.

Run llm-env-check --safe for a terminal summary of the safety boundaries.

What is checked

• OS name and version
• CPU model when safely available
• CPU architecture
• Total RAM and currently free RAM estimate
• GPU name and VRAM when safely available
• Node.js version
• Whether fixed commands for Ollama, LM Studio, llama.cpp, Docker, Python, and Git appear to be installed

What is never checked

• Arbitrary files or user directories
• Project files, .env files, or git remotes
• Browser data, clipboard data, or shell history
• SSH keys or configuration
• Tokens, credentials, or API keys

The implementation uses Node.js OS APIs and a fixed allowlist of read-only hardware and version commands. It does not pass user input into system commands. It never downloads models, installs software, requests administrator privileges, or mutates system state.

Color And Accessibility

ANSI colors improve terminal readability. The CLI never relies on color alone: every status also includes a symbol and a readable label such as ✓ GOOD, ~ BORDERLINE, or ✗ NOT RECOMMENDED.

By default, colors are emitted only when stdout is a TTY. Redirected output is plain text. NO_COLOR disables automatic color output, FORCE_COLOR=1 enables color for CI output, --color explicitly selects auto, always, or never, and --no-color overrides everything. JSON never contains ANSI escapes.

These conventions follow common CLI ecosystem practices and accessibility principles similar to WCAG guidance:

• NO_COLOR
• Node.js TTY documentation
• WCAG: Use of Color

Sample Output

LLM Environment Check
─────────────────────
Profile: coding

OS: Windows 11
CPU: AMD Ryzen 9 (x64)
RAM: 32 GB total | 18 GB currently free
GPU: NVIDIA GeForce RTX
VRAM: 8 GB

Best fit models:
✓ GOOD — Qwen2.5-Coder 7B Q4
  Estimated memory: 5.5 GB | Best use: Code completion and repository assistance
  Reason: Estimated 5.5 GB requirement fits comfortably with 8 GB detected VRAM.

Privacy:
✓ SAFE — No data uploaded.
✓ SAFE — No files scanned.
✓ SAFE — Local analysis only.

Limitations

• Hardware queries vary across operating systems and vendors. GPU name or VRAM may be unavailable.
• GPU VRAM reported by an operating system can be approximate, especially for shared-memory GPUs.
• Fit ratings use estimated quantized-model memory and do not benchmark the host.
• A model that fits in memory may still be slow for a particular workload or context size.
• Runtime detection only checks whether a known executable responds to a fixed version command.

Development

npm install
npm run build
npm test
npm run lint
npm pack --dry-run

Contributions should preserve the local-only, read-only design. New system checks must be fixed capability queries, must not include user-derived shell arguments, and must be covered by tests.

Publishing To npm

Maintainers need an account on npmjs.com with two-factor authentication enabled. The package name llm-env-check is unscoped, so it must be globally unique on npm.

From the project folder, check whether the name is available:

npm view llm-env-check

If npm returns a 404 Not Found error, the name is available. If it displays an existing package, choose another package name in package.json.

Log in and confirm the active npm account:

npm login
npm whoami

Run the release checks:

npm test
npm run lint
npm pack --dry-run

Review the npm pack --dry-run file list carefully. It shows exactly which files will be published. Then publish the public unscoped package:

npm publish

After publication, anyone can install and run the CLI:

npm install --global llm-env-check
llm-env-check --help
llm-env-check --profile coding

Published name-and-version combinations cannot be reused. For a later bug-fix release, increment the patch version and publish again:

npm version patch
npm publish

Package Link

After publication, the npm package page is:

https://www.npmjs.com/package/llm-env-check