grex — nested meta-repo manager. Pack-based, agent-native, Rust-fast.

What is grex?

grex manages trees of git repositories as a single addressable graph. Each node is a "pack" — a plain git repo plus a .grex/ contract — and every pack is a meta-pack by construction (zero children = leaf, N children = orchestrator of N more packs, recursively). One uniform command surface (sync, add, rm, update, status, import, doctor, teardown, exec, run, serve) operates over the whole graph regardless of depth.

Pack

A pack is a plain git repo plus a .grex/ contract directory. Everything outside .grex/ is opaque payload; everything inside .grex/ is the pack's declared contract (manifest, actions, pack-type metadata). Every pack is a meta-pack by construction — zero-children just means leaf.

Install

Pick one of three paths. All three land the same grex binary (v1.0.0+).

1. cargo install (crates.io)

cargo install grex-cli

The crate is published as grex-cli; the installed binary is grex. If pemistahl's unrelated grex (regex-from-test-cases tool) is already on your PATH, pass --force to cargo install grex-cli or rename the existing binary first to avoid a silent overwrite.

2. Shell installer (Linux / macOS)

curl -LsSf https://github.com/egoisth777/grex/releases/latest/download/grex-cli-installer.sh | sh

3. PowerShell installer (Windows)

powershell -c "irm https://github.com/egoisth777/grex/releases/latest/download/grex-cli-installer.ps1 | iex"

Both installer one-liners are a convenience path — they do NOT verify attestations. For a verified install (SLSA build provenance via gh attestation verify), see man/release.md §Verified install.

Pre-built binaries ship for 5 targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, x86_64-pc-windows-msvc. Anything else falls back to cargo install grex-cli.

Both installer one-liners resolve to the latest GitHub Release, built by cargo-dist on every v*.*.* tag push (see man/release.md).

Man pages

Every release tarball ships a man/ directory with one Unix man page per CLI verb (grex.1 plus grex-<verb>.1). They are auto-generated from the clap::Command tree via clap_mangen and are a passive projection of the CLI surface — never edit them by hand.

If you install via cargo install grex-cli, the man/ directory is not copied into your system man path; install manually after unpacking a release tarball or checking out the repo:

# Linux / macOS — per-user
install -Dm644 man/*.1 -t ~/.local/share/man/man1/

# System-wide (requires sudo)
sudo install -Dm644 man/*.1 -t /usr/local/share/man/man1/

Then man grex, man grex-sync, etc. Fish / zsh completions are tracked for a future release. See the mdBook "Man pages" chapter for the auto-generation flow.

Quickstart

grex init
grex add https://github.com/egoisth777/grex-inst dev/grex-inst
grex sync
grex doctor

Try with the reference pack template

To see a complete, working pack shape end-to-end, install the reference template from the in-tree fixture:

grex add "file://$(pwd)/examples/pack-template"
grex sync

The template ships as examples/pack-template/ in-tree. A standalone mirror repo is also published; you can install via the clone form:

grex add [email protected]:egoisth777/grex-pack-template.git
grex sync

See the mdBook "Pack template" chapter for the ownership / publishing contract.

CLI verbs

Universal flags on every verb: --json, --plain, --dry-run, --parallel <N>, --filter <EXPR>.

Status

v1.1.0 shipped (2026-04). See CHANGELOG.md for release history and milestone.md for the long-term roadmap.

Documentation site

The hosted documentation lives at https://egoisth777.github.io/grex/. It is built from man/ (the human-readable doc home — *.1 man pages plus authored markdown reference) by an mdBook site rooted at grex-doc/. The site deploys to GitHub Pages on every v*.*.* tag push via .github/workflows/doc-site.yml.

API reference (post crates.io publish): https://docs.rs/grex-core / https://docs.rs/grex-mcp.

Local preview:

cargo install mdbook mdbook-linkcheck --locked
cargo run -p xtask -- doc-site-prep
mdbook build grex-doc/
mdbook serve grex-doc/   # http://localhost:3000

Source-of-truth design docs

• openspec/feat-grex/spec.md — active feature spec
• inst/README.md — design-doc index (mdBook site is generated from these)
• progress.md — current state + last endpoint
• milestone.md — phased delivery plan

Changelog

See CHANGELOG.md — Keep-a-Changelog 1.1.0 format, per-release entries categorised by Added / Changed / Deprecated / Removed / Fixed / Security.

Versioning

See man/semver.md — what MAJOR / MINOR / PATCH mean for the four public surfaces (manifest schema, CLI surface, MCP tool surface, pack.yaml schema) plus the deprecation policy.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. See LICENSE for the combined notice.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

lib.rs:

grex-mcp — MCP-native server for grex (M7).

Stage 5 wires the rmcp framework: the server speaks the MCP 2025-06-18 wire protocol over any rmcp::transport (stdio in production, tokio::io::duplex in tests). The handshake + tools/list (returning empty) + transport-close shutdown are live; the 11 tool handlers land in Stage 6, and cancellation in Stage 7.

Stdout discipline

The MCP stdio transport multiplexes only JSON-RPC bytes on stdout. All diagnostics MUST go to stderr. GrexMcpServer::run installs a tracing_subscriber::fmt writer pinned to stderr — idempotently, so test reuse and serve-from-CLI both work. The no_println_lint.rs integration test enforces zero println! / print! macros under src/ to prevent regressions.