Quantex CLI

Quantex is a human-friendly + agent-friendly lifecycle CLI for AI coding agents. It gives Claude Code, Codex, Gemini, Kilo Code, Cursor, OpenCode, and other assistant CLIs a shared surface for installation, inspection, updates, removal, execution, and machine-readable automation. This README uses the shorter qtx form as the recommended entry point, while quantex remains the fully equivalent long command name.

Why Quantex

• Manage multiple AI agents from one CLI: install, ensure, inspect, update, uninstall, and run.
• Designed for scripts and coding agents: stable --json, --output ndjson, --non-interactive, and --dry-run contracts.
• Tracks real install sources: update --all groups updates by recorded source instead of guessing from PATH alone.
• Supports Quantex self-upgrade across Bun, npm, and standalone binary installs.

Agent Quick Start

If you are using a coding agent with Quantex, start by installing the repo-provided Quantex skill:

npx skills add Drswith/quantex-cli --skill quantex-cli -a codex -a claude-code -a opencode -y

To preview the skills exposed by this repository:

npx skills add Drswith/quantex-cli --list

Then let the agent discover Quantex's stable commands and output contracts:

npm exec --yes --package quantex-cli -- qtx capabilities --json
npm exec --yes --package quantex-cli -- qtx commands --json
npm exec --yes --package quantex-cli -- qtx schema --json

If the agent is contributing inside this repository, use this as the bootstrap prompt:

Read AGENTS.md, openspec/README.md, and skills/quantex-cli/SKILL.md first.
For non-trivial changes, use the OpenSpec / OPSX workflow.
Before finishing, run bun run lint, bun run format:check, and bun run typecheck.
If command behavior changed, also run bun run test.

The repo-local Quantex skill lives in skills/quantex-cli/. It can be installed from GitHub through skills.sh with npx skills add, but this repository remains the publishing source; it is not a separate npm package. See the skill distribution notes for installation and sync options.

Install

With Bun:

bun add -g quantex-cli

With npm:

npm i -g quantex-cli

You can also download standalone binaries from GitHub Releases, or use the install script:

curl -fsSL https://raw.githubusercontent.com/Drswith/quantex-cli/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/Drswith/quantex-cli/main/install.ps1 | iex

After installation, prefer qtx for the shortest copyable path. If you prefer the explicit long form, quantex is fully equivalent.

Try It Without Installing

If your environment already provides the runtime Quantex currently expects, you can try read-only commands before doing a global install:

bunx quantex-cli list
npx --yes --package quantex-cli qtx capabilities --json
npm exec --yes --package quantex-cli -- qtx inspect codex --json
pnpm --package=quantex-cli dlx qtx doctor

Notes:

• These commands are intended for read-only and discovery-oriented flows such as list, info, inspect, doctor, capabilities, commands, and schema.
• The currently published package executes its CLI entrypoint through bun, so npx / npm exec / pnpm dlx still require a working bun on PATH.
• For install, ensure, update, uninstall, upgrade, or any flow that should record install-source state, prefer a normal install first.

Quick Start

Install and run an agent:

qtx install claude
qtx exec claude --install if-missing -- --help

Ensure an agent is available, which is useful for scripts and other agents:

qtx ensure codex --json

Inspect agent state and resolve its executable:

qtx inspect codex --json
qtx resolve codex --json

Update one agent or all installed agents:

qtx update claude
qtx update --all

Upgrade Quantex itself:

qtx upgrade
qtx upgrade --check
qtx upgrade --channel beta

Note: qtx upgrade follows the registry actually used by the current Bun/npm self-upgrade path. If you use a mirror and it lags behind npm, the newest upstream release may not be installable from that registry yet. In that case, retry later or set selfUpdateRegistry / QTX_SELF_UPDATE_REGISTRY so Quantex self-upgrade uses a different registry without affecting your other projects.

Common Commands

Supported Agents

If you prefer the explicit long form, replace qtx with quantex in the examples above.

Automation And Agents

Quantex is not a workflow orchestration platform. Its core job is to provide a stable lifecycle surface for AI coding assistant CLIs. For automation, prefer explicit structured flags:

quantex inspect claude --json --refresh
quantex install claude --json --dry-run
quantex exec claude --install if-missing --yes -- --help

Useful contracts:

• --json / --output <human|json|ndjson> controls output format.
• --non-interactive, --yes, and --quiet are designed for CI and agent calls.
• --dry-run previews install or update plans.
• --refresh / --no-cache controls version and release metadata caches.
• stdout is reserved for structured results; stderr carries logs, warnings, and underlying installer output.

For upper-layer agent integrations, start with capability and schema discovery:

quantex capabilities --json
quantex commands --json
quantex schema --json

Configuration And State

User configuration lives at ~/.quantex/config.json:

{
  "defaultPackageManager": "bun",
  "npmBunUpdateStrategy": "latest-major",
  "selfUpdateChannel": "stable",
  "selfUpdateRegistry": "https://registry.npmjs.org",
  "networkRetries": 2,
  "networkTimeoutMs": 10000,
  "versionCacheTtlHours": 6
}

selfUpdateRegistry only affects the registry used when Quantex upgrades itself through Bun/npm. It does not change the default install source for your other projects. For a one-off override, use the QTX_SELF_UPDATE_REGISTRY environment variable.

Runtime state lives at ~/.quantex/state.json. Quantex records the actual install source for agents and itself, which powers grouped update --all execution, doctor recovery guidance, and self-upgrade source detection.

Releases

Quantex uses release-please Release PRs. GitHub Releases are the canonical release notes:

• GitHub Releases
• docs/releases.md
• CHANGELOG.md

Maintainers And Agent Collaboration

If you are contributing to this repository or letting a coding agent work here, start from these entry points:

• AGENTS.md: repository-level execution handbook with workflow guardrails, validation gates, and trigger-based pointers.
• docs/README.md: project docs for ADRs, runbooks, sessions, and postmortems.
• openspec/README.md: OpenSpec / OPSX change workflow.
• docs/github-collaboration.md: Issue, PR, and Discussion collaboration flow.
• skills/quantex-cli/SKILL.md: repo-native skill for agents using Quantex.

Common local development commands:

bun install
bun run dev
bun run lint
bun run format:check
bun run typecheck
bun run test
bun run build

License

Apache-2.0