Quantex CLI

Manage AI coding assistant CLIs from one lifecycle-focused command line.

English | 简体中文

Quantex is a human-friendly + agent-friendly lifecycle CLI for AI coding agents. It gives Amp, 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 user-facing Quantex CLI 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:

Activate Superpowers if available, then read AGENTS.md, openspec/README.md, skills/quantex-agent-runtime/SKILL.md, and skills/quantex-cli/SKILL.md.
For non-trivial changes, use OpenSpec through the Quantex agent runtime.
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 user-facing Quantex CLI 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. The separate skills/quantex-agent-runtime/ directory is contributor-facing runtime for agents working inside this repository, not the normal external user skill. See the skill distribution notes for installation and sync options.

Install

With Bun:

bun add -g quantex-cli

With npm (Node.js 20+):

npm i -g quantex-cli

The published JS CLI runs on Node after installation. Bun remains a supported package-manager path for install and self-upgrade, while the standalone binary release remains the zero-runtime option.

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 Node.js 20 or newer, 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.
• npx, npm exec, and pnpm dlx run the published JS CLI through Node and do not require bun on PATH.
• bunx still requires Bun because bunx itself is Bun's launcher.
• 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 codex
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

Preferred Command	Equivalent Long Form	Description
qtx i <agent> [more-agents...]	quantex install <agent> [more-agents...]	Install one or more agents
qtx ensure <agent>	quantex ensure <agent>	Idempotently ensure an agent is installed
qtx u <agent>	quantex update <agent>	Update an agent
qtx update --all	quantex update --all	Update all installed agents
qtx rm <agent>	quantex uninstall <agent>	Uninstall an agent
qtx ls	quantex list	List supported agents
qtx info <agent>	quantex info <agent>	Show agent details
qtx inspect <agent>	quantex inspect <agent>	Return structured agent state
qtx resolve <agent>	quantex resolve <agent>	Resolve the executable entrypoint
qtx exec <agent> -- [args...]	quantex exec <agent> -- [args...]	Run an agent with explicit policy
qtx <agent> [args...]	quantex <agent> [args...]	Shortcut-run an agent
qtx capabilities	quantex capabilities	Show environment capabilities
qtx commands	quantex commands	Show the stable command catalog
qtx schema	quantex schema	Show structured output schemas
qtx config	quantex config	Manage configuration
qtx doctor	quantex doctor	Diagnose environment and recovery guidance

Supported Agents

Agent	Run Command	Description
Auggie CLI	qtx auggie	Augment's official terminal coding agent
Autohand Code CLI	qtx autohand	Autohand's autonomous terminal coding agent CLI
Amp	qtx amp	Sourcegraph's frontier AI coding agent CLI
Claude Code	qtx claude	Anthropic's official AI coding assistant CLI
CodeBuddy Code	qtx codebuddy	Tencent's official AI coding assistant CLI
Codex CLI	qtx codex	OpenAI's official AI coding assistant CLI
Crush	qtx crush	Charmbracelet's terminal AI coding agent CLI
Cursor CLI	qtx cursor	Cursor AI coding assistant CLI
DeepSeek TUI	qtx deepseek	DeepSeek's terminal-native coding agent
Devin for Terminal	qtx devin	Cognition's local coding agent CLI
Droid	qtx droid	Factory AI software engineering agent CLI
ForgeCode	qtx forgecode	Antinomy's AI coding assistant CLI
Gemini CLI	qtx gemini	Google's open-source AI coding assistant CLI
GitHub Copilot CLI	qtx copilot	GitHub Copilot command-line tool
Goose	qtx goose	Block's open-source extensible AI agent CLI
JCode	qtx jcode	High-performance coding agent harness for multi-session workflows
Junie CLI	qtx junie	JetBrains' AI coding agent CLI
Kilo CLI	qtx kilo	Kilo's official AI coding assistant CLI
Kimi Code	qtx kimi	Moonshot AI's coding assistant CLI
Kiro CLI	qtx kiro	Amazon's AI coding agent CLI
Mistral Vibe	qtx vibe	Mistral's open-source CLI coding assistant
OpenHands CLI	qtx openhands	OpenHands' open-source software development agent CLI
OpenCode	qtx opencode	Open-source AI coding CLI
Pi	qtx pi	Minimal and extensible terminal coding agent
Qoder CLI	qtx qoder	Qoder's official AI coding assistant CLI
Qwen Code	qtx qwen	Qwen's AI coding assistant CLI
Reasonix	qtx reasonix	DeepSeek-native terminal coding agent
VTCode	qtx vtcode	Open-source terminal coding agent with robust shell safety

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.
• skills/quantex-agent-runtime/SKILL.md: contributor-facing runtime for agents working inside this repository.

Common local development commands:

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

bun run test:container is the preferred local isolation pass for host-sensitive lifecycle checks when you want a clean Linux environment without installing Modal locally. It runs Quantex's real CLI lifecycle smoke flow for selected agents, including preinstalled-agent adoption and Quantex standalone-binary self checks, not the unit test suite. bun run test:sandbox runs the same smoke flow through Modal and is intended for validating the remote transport or the dedicated GitHub Actions workflow.

License

Apache-2.0