XSHELF (formerly CX)

XSHELF is a deterministic Rust runtime for LLM-assisted repository work. It wraps repo commands with bounded capture, schema-checked outputs, explicit execution policy, and replayable telemetry.

Use it when free-form agent output is too loose for automation, CI, or operator workflows that need stable JSON contracts and inspectable failure paths.

Trust and naming:

• XSHELF/CX is an independent open-source project and is not affiliated with or endorsed by OpenAI.
• XSHELF is the primary project name.
• CX remains a supported compatibility command surface during migration (./bin/cx ...).

Try It

Start with read-only checks. They do not change repository configuration.

./bin/xshelf version
./bin/xshelf task check --json
./bin/xshelf core --json
./bin/xshelf diag --json --window 20

What should be visible:

• version prints the XSHELF runtime version.
• task check --json reports task orchestration readiness.
• core --json prints machine-readable runtime and backend state.
• diag --json prints recent machine-readable diagnostics.
• JSON output remains parseable by automation.

The short alias is available as ./bin/xs ...; the compatibility alias remains available as ./bin/cx ....

Requirements

Minimum local requirements:

• bash
• git
• jq for JSON inspection in examples
• Rust toolchain for development and local validation: cargo, rustfmt, clippy

Optional backend tools:

• ollama for the optional local backend path
• llama-cli from llama.cpp for the optional llamacpp local backend
• mlx-lm in a Python environment for the optional macOS mlx backend

Install shell functions and man pages:

./bin/xshelf-install
./bin/xs-install
man xs
man xshelf
man cx

Then check backend health:

./bin/xshelf llm check
./bin/xshelf doctor
./bin/xshelf health

Run cxo only after readiness and backend checks are healthy. A safe first command is a read-only repository inspection:

./bin/xshelf cxo git status

Operator Pipeline

The Rust pipeline is intentionally strict:

1. Capture repository output.
2. Reduce context.
3. Enforce budget.
4. Run the selected backend.
5. Validate structured output.
6. Quarantine invalid results.
7. Append telemetry.

Current compatibility storage path:

• repo-scoped runtime state currently lives under .cx/
• schemas: .cx/schemas/
• logs: .cx/cxlogs/
• quarantine: .cx/quarantine/
• state/tasks/runtime metadata: .cx/

Capabilities

Runtime state:

./bin/xshelf core --json
./bin/xshelf mode --json | jq .
./bin/xshelf broker show --json | jq .

core/version/diag/scheduler JSON surfaces now include backend_capabilities.runtime, a typed capability envelope with explicit nulls for unknown support lanes.

Task graph:

./bin/xshelf task add "Implement parser hardening" --role implementer
./bin/xshelf task fanout "Ship release notes improvements" --from staged-diff
./bin/xshelf task check --json | jq .
./bin/xshelf task run-all --status pending --mode mixed
./bin/xshelf task run-all --status pending --mode parallel --max-workers 2
./bin/xshelf task run-all --status pending --events-jsonl --json
./bin/xshelf task events --limit 20 --json

--events-jsonl writes additive task-events.v1 progress events to stderr and .codex/cxlogs/task_events.jsonl, so final stdout JSON remains parseable.

Policy and telemetry:

./bin/xshelf policy show --json | jq .
./bin/xshelf telemetry 50 --json | jq .
./bin/xshelf logs stats 200 --json | jq .
./bin/xshelf logs validate --fix=false
./bin/xshelf optimize 200 --json | jq .
./bin/xshelf quota probe 30 --json | jq .

Structured output:

./bin/xshelf schema list
./bin/xshelf schema list --json | jq .
./bin/xshelf next git status
./bin/xshelf diffsum-staged | jq .
./bin/xshelf commitjson | jq .

Backend Selection

./bin/xshelf llm show
./bin/xshelf llm check
./bin/xshelf llm use primary
./bin/xshelf llm use ollama llama3.1
./bin/xshelf llm use llamacpp ggml-org/Qwen3-0.6B-GGUF:Q4_0
./bin/xshelf llm use mlx local_mlx
./bin/xshelf llm models list --json | jq .
./bin/xshelf llm models add local_mlx --backend mlx --model "$MLX_MODEL_ID"
./bin/xshelf llm models inspect local_mlx --json | jq .
./bin/xshelf llm models inspect local_mlx --disk-usage --json | jq .
./bin/xshelf llm verify mlx --profile smoke --json | jq .
./bin/xshelf llm verify mlx --profile benchmark --ctx 8192 --json | jq .
./bin/xshelf llm resident show --json | jq .
CX_PROVIDER_ADAPTER=http-curl \
CX_HTTP_REQUEST_PROFILE=openai_json \
CX_HTTP_PROVIDER_URL=http://127.0.0.1:11434/v1/chat/completions \
  ./bin/xshelf llm resident probe-models --json | jq .
./bin/xshelf llm smoke "Respond with OK only."
./bin/xshelf llm unset model

When the selected model token matches a local-model registry alias or ID for the active backend, runtime execution resolves it to the record's resolved_model. llm show prints both alias and resolved model when applicable. llm models inspect uses cheap path checks by default; recursive directory accounting runs only when --disk-usage is provided. llm resident exposes explicit resident-server capability state and an optional /v1/models probe on opt-in HTTP adapter profiles.

llamacpp accepts either a local .gguf path or a llama.cpp Hugging Face repo specifier. The default smoke recipe uses ggml-org/Qwen3-0.6B-GGUF:Q4_0, a small Apache-2.0 GGUF model whose Q4_0 file is about 429 MB.

brew install llama.cpp
./scripts/llamacpp_smoke.sh

# Equivalent manual smoke:
./bin/xshelf llm use llamacpp ggml-org/Qwen3-0.6B-GGUF:Q4_0
CX_CMD_TIMEOUT_SECS=600 \
CX_LLAMA_CPP_ARGS="-n 64 --temp 0 -c 2048 --simple-io" \
  ./bin/xshelf cxo printf 'xshelf llamacpp smoke\n'

Configuration Essentials

Important runtime knobs:

• budgeting: CX_CONTEXT_BUDGET_CHARS, CX_CONTEXT_BUDGET_LINES, CX_CONTEXT_CLIP_MODE, CX_CONTEXT_CLIP_FOOTER
• timeout: CX_CMD_TIMEOUT_SECS
• backend/model: CX_LLM_BACKEND, CX_OLLAMA_MODEL, CX_LLAMA_CPP_MODEL, CX_LLAMA_CPP_BIN, CX_LLAMA_CPP_ARGS, CX_MLX_MODEL, CX_MLX_PYTHON, CX_MLX_ARGS, CX_MLX_MAX_TOKENS, CX_MODEL
• output mode: CX_JSON_DEFAULT, CX_JSON_AUTO
• execution mode: CX_MODE, CX_SCHEMA_RELAXED
• HTTP adapter policy: CX_HTTP_PROVIDER_URL, CX_HTTP_PROVIDER_TOKEN, CX_HTTP_AUTH_PROFILE, CX_HTTP_AUTH_HEADER, CX_HTTP_AUTH_VALUE, CX_HTTP_AUTH_VALUE_FILE, CX_HTTP_AUTH_USERNAME, CX_HTTP_AUTH_PASSWORD, CX_HTTP_AUTH_PASSWORD_FILE, CX_HTTP_PROVIDER_TOKEN_FILE, CX_HTTP_REQUEST_PROFILE, CX_HTTP_PROVIDER_MODEL, CX_HTTP_PROVIDER_FORMAT, CX_HTTP_REQUIRE_HTTPS, CX_HTTP_ALLOW_LOCAL_HTTP, CX_HTTP_ALLOWED_HOSTS, CX_HTTP_CA_BUNDLE, CX_HTTP_CLIENT_CERT, CX_HTTP_CLIENT_KEY, CX_HTTP_TLS_PINNEDPUBKEY, CX_HTTP_TLS_MIN_VERSION, CX_HTTP_FOLLOW_REDIRECTS, CX_HTTP_MAX_REDIRECTS

Useful state/config commands:

./bin/xshelf mode
./bin/xshelf broker show --json | jq .
./bin/xshelf quota guard show
./bin/xshelf quota catalog show --json | jq .

Entrypoints

Canonical runtime:

• engine: rust/cxrs
• primary entrypoint: bin/xshelf
• short alias: bin/xs
• compatibility alias: bin/cx
• compatibility shell shim: lib/cx.sh

Runtime vs development:

• end users should use doctor, health, and command JSON surfaces
• maintainers and CI run the Rust suite, compat checks, and guardrails

Documentation

Operator docs:

• docs/README.md - documentation index
• docs/manuals/00_README.md - manual entrypoint
• docs/manuals/02_web/index.html - web manual index
• docs/manuals/02_web/CX_MANUAL_MASTER.html - tracked HTML reader mirror
• docs/manuals/01_pdf/CX_MANUAL_MASTER.pdf - generated master manual PDF
• docs/providers/HTTP_PROVIDER_TLS.md - HTTP/TLS operator guidance

Maintainer docs:

• docs/project/REPO_ROLE_CONTRACT.md
• docs/project/ROADMAP.md
• docs/project/RELEASE_CADENCE.md
• docs/project/PUBLIC_SURFACES.md
• docs/project/XSHELF_RENAME_MIGRATION.md
• CONTRIBUTING.md

Planning and history:

• docs/orchestration/ - phase plans, work queues, and milestone notes
• docs/turboquant/ - TurboQuant experiment archive
• docs/project/RUST_FIRST_MIGRATION.md
• docs/project/SECURITY_HISTORY_REWRITE.md

Validation

Runtime-facing validation:

./bin/xshelf doctor
./bin/xshelf health
./bin/xshelf logs validate --fix=false

Maintainer validation:

./scripts/compat_local.sh --quick
./scripts/compat_local.sh --full --out .cx/compat/latest.json
./scripts/compat_all.sh --quick
./scripts/compat_all.sh --full --out .cx/compat/all_latest.json
./bin/cx-compat-local --quick

Rust maintainer path:

cd rust/cxrs
cargo fmt --check
cargo clippy --all-targets -- -D warnings -D clippy::too_many_arguments
cargo test --tests -- --test-threads=1

Git hook guardrails:

./bin/cx-enable-githooks
git push

Development Notes

Repository layout:

• bin/xshelf - canonical runtime entrypoint
• bin/xs - short runtime alias
• bin/cx - compatibility runtime alias
• rust/cxrs/src/main.rs - Rust binary entry
• rust/cxrs/src/app/mod.rs - routing/orchestration
• rust/cxrs/src/modules/*.rs - runtime modules
• lib/cx.sh - shell compatibility shim

Current design discipline:

• Rust is authoritative for runtime behavior, contracts, and telemetry
• no automatic checks during shell startup
• diagnostics go to stderr; pipeline output stays on stdout
• capture is internal-native only

Versioning:

• machine-readable current version: VERSION
• release history: CHANGELOG.md, tags, and VERSION_HISTORY.md

Contributing And Security

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• docs/contributing/GOOD_FIRST_ISSUES.md