rux

The unified toolchain for Rust. One CLI for your toolchain, your build output and your everyday commands, built for humans and AI agents.

rux install stable      # built-in installer: no rustup needed
rux check               # cargo fmt --check + clippy, one pass/fail summary
rux check --json        # structured diagnostics for agents
rux status              # what is stored, how big, when last used
rux gc                  # evict least-recently-used build output to stay under budget
rux mcp                 # MCP server for AI agents

Why

• Build output never piles up. Cargo's target/ directories grow to tens of GB per project, and AI agents working in many git worktrees multiply that. rux keeps all build output in one managed store (~/.rux/targets), shares it across all worktrees of a git repo, and evicts least-recently-used entries automatically to stay under a size budget (default 40 GB). No target/ directory appears in your projects.
• One tool for the toolchain. rux downloads Rust from static.rust-lang.org, verifies SHA-256 checksums from the official channel manifest, and installs per rust-toolchain.toml. Installs are lock-guarded, so parallel agents don't race.
• Agent-friendly. Every report command has --json with structured diagnostics (level, code, message, file, line, col), deduplicated and bounded. rux mcp exposes the same to MCP clients.
• Cargo-compatible. rux orchestrates cargo, rustc, clippy, rustfmt and (if installed) nextest and sccache. It does not fork or replace the compiler, and relies on Cargo's own fingerprinting, so builds stay correct.

Install

curl -fsSL https://raw.githubusercontent.com/spacecorps/rux/main/install.sh | sh
# or from source
cargo install --git https://github.com/spacecorps/rux

Commands

Command	Does
rux install [ver]	Install a toolchain: stable, beta, nightly, 1.85.0, nightly-2026-01-01. No arg: the project's
rux use <ver>	Pin for this project (writes rust-toolchain.toml)
rux default <ver> / list / uninstall <ver> / which [tool] / env	Manage and inspect toolchains
rux dev	Watch sources, re-run cargo check on change
rux check [--fix]	cargo fmt --check + cargo clippy --all-targets
rux build / run / test / lint / fmt	Cargo commands inside the resolved toolchain and managed target dir (test uses nextest when installed)
rux add / remove / new / cargo ... / exec -- cmd	Passthroughs
rux status	Toolchains, build output, budget
rux gc [--max 40GB] [--dry-run] [--toolchains]	LRU eviction
rux scan <path> [--delete --yes]	Find existing target/ directories (read-only unless --delete --yes)
rux clean	Remove this project's build output from the store
rux doctor / mcp / completions <shell>	Diagnostics, MCP server, shell completions

Trailing arguments pass through to cargo: rux build --release, rux test -- --nocapture. --json works on check, build, lint, fmt, test, status, gc, scan, list. Exit codes: 0 ok, 1 the check/build/test failed, 2 rux itself failed.

Configuration

~/.rux/config.toml (all optional):

max_cache   = "40GB"     # budget for build output; env: RUX_MAX_CACHE
target_mode = "shared"   # shared | project | local; env: RUX_TARGET_MODE
sccache     = true       # default: use sccache if it is on PATH

• shared: one build dir per git repo (and path within it), reused by every worktree.
• project: one build dir per workspace path.
• local: Cargo's normal ./target.

Toolchain resolution: RUX_TOOLCHAIN > rust-toolchain(.toml) found walking up from the current directory > rux default > stable. Set RUX_HOME to relocate the store. Set RUX_NO_AUTO_GC=1 to disable the background GC that runs after build commands.

MCP

claude mcp add rux -- rux mcp

or in any MCP client config: {"mcpServers": {"rux": {"command": "rux", "args": ["mcp"]}}}. Tools: rux_check, rux_build, rux_test, rux_lint (all take optional cwd, args), rux_status, rux_gc.

Cleaning up what you already have

rux scan ~/git                  # list every cargo target/ dir and its size
rux scan ~/git --delete --yes   # delete them (build output only; rebuildable)

Status

Early (0.1). Working and tested: toolchain install/resolve/pin, shared build store with LRU GC, structured reports, MCP server, watch mode. Not built yet: a content-addressed per-crate artifact cache (v0.1 relies on Cargo's own fingerprinting and optional sccache), a build daemon, Windows testing.

Development: cargo test (unit + CLI tests), cargo test -- --ignored (downloads a real toolchain). Website sources are in site/.

License

MIT. See LICENSE.