Mars Terminal

Born from Rio. Built for Mars.

Mars is a Rio-derived Rust terminal fork maintained by the author of Yazelix.

The project keeps Rio close enough to upstream to rebase deliberately, while giving Yazelix a terminal stack it can control, test, package, and adapt when terminal behavior matters. Mars aims for practical Ghostty parity, strong Kitty protocol support, good Nix/runtime integration, and small measured changes instead of broad fork drift.

Mars is the default packaged terminal for Yazelix, with Ghostty as a strong alternative.

Mars exists so the Rust terminal/runtime boundary can move with Yazelix if and when protocol, cursor, graphics, and packaging work needs it.

Mars adopts (carefully) agent-driven development with plenty of testing.

• The source tree is based on upstream Rio and still carries Rio crate names in many Rust packages
• The first-class Nix package is .#mars; .#default points at the same package
• The package wraps the upstream Rio binary as bin/mars, installs Mars desktop metadata and icons, and sets the app id to mars
• The package exposes passthru.marsPackageMetadata and installs the same data at share/mars/package-metadata.json
• The package includes generated Mars config roots for Yazelix: share/mars, share/mars/baseline, share/mars/profiles/shaders, and share/mars/emoji/twitter
• The package metadata advertises MARS_APPEARANCE, MARS_EMOJI_FONT, MARS_EMOJI_FONT_SOURCE, MARS_PROFILE, and YAZELIX_CURSOR_CONFIG as the runtime environment contract consumed by Yazelix
• Mars config accepts [mars.appearance] preset = "dark", "light", or "auto"; MARS_APPEARANCE overrides that config value for package consumers
• When YAZELIX_CURSOR_CONFIG points to a Yazelix Cursors TOML file, Mars loads it once and renders the resolved fixed, random, custom mono/split, or disabled cursor using its native cursor and trail primitives. Without the variable, standalone Mars keeps its normal cursor behavior
• On Linux, the Nix wrapper provides a package-owned default Vulkan ICD path when VK_ICD_FILENAMES is unset, while preserving explicit user overrides
• Rio package outputs remain exposed as .#rio, .#rio-msrv, .#rio-stable, and .#rio-nightly for comparison and upstream maintenance work

The full fork audit trail lives in docs/yazelix/change_scorecard.md. The table below is the README-sized feature view.

Mars renders Yazi image previews through Kitty graphics in the Yazelix runtime:

Build the Mars package with Nix:

nix build github:Yazelix/mars#mars
./result/bin/mars

Install it into a Nix profile:

nix profile install github:Yazelix/mars#mars
mars

Build from a local checkout:

nix build .#mars
./result/bin/mars

The Cargo workspace still follows upstream Rio's crate layout. Use Cargo for source-level development and CI parity:

cargo build --release --features wgpu

Yazelix consumes Mars through the Nix package contract, not by guessing Rio internals. The package metadata tells Yazelix where Mars configs live, which emoji presets and appearance modes are supported, and which wrapper command to launch.

The source tree also publishes the versioned docs/yazelix/config_inventory.v1.json catalog of public Mars settings, defaults, choices, structured shapes, and platform constraints. Consumers read this small artifact from their exact pinned Mars source revision; using it does not retain or link the terminal runtime.

Package metadata exposes the current runtime environment contract to Yazelix:

Packaged Mars config roots are immutable bases with their theme and font assets. MARS_CONFIG_HOME may point at a sparse user override; Mars merges it over the base without copying package paths into mutable state.

For local Yazelix dogfooding, use the private launcher:

tools/mars_private_yazelix.py

Local dogfooding helpers also accept focused overrides:

The Cargo workspace follows upstream Rio's crate layout and MSRV. Nix exposes the Mars package and comparison Rio packages. Repository workflow rules live in AGENTS.md.

Useful project docs:

• docs/yazelix/fork_plan.md
• docs/yazelix/upstream_maintenance.md
• docs/yazelix/clean_rio_rebuild_gate.md
• docs/yazelix/non_nix_graphics_launch_support.md

Mars keeps reproducible dogfooding tools in the repo. The performance gate launches Mars with deterministic workloads and writes artifacts under artifacts/dogfooding/.

Run the default suite:

tools/mars_perf_gate.py --suite --seconds 20

Run one scenario:

tools/mars_perf_gate.py --suite --scenario pty_flood --seconds 20

Enable gated internal PTY/render metrics for suite-launched Mars:

tools/mars_perf_gate.py --suite --scenario pty_flood --seconds 20 --internal-metrics

Trace a launch boundary:

mars-launch-trace -- mars -e true

Useful local checks:

cargo fmt -- --check --color always
cargo clippy --all-targets --all-features
cargo test --features wgpu
nix build .#mars --no-link --print-build-logs
actionlint .github/workflows/release.yml

The GitHub Test workflow runs native Linux, macOS, and Windows Rust checks, plus MSYS2 release builds for MINGW64, UCRT64, and CLANG64.

The GitHub Nix Build workflow builds the flake package on Linux ARM.

Nix and source builds are the validated first-party Mars surfaces. Inherited Rio release packaging still needs Mars-specific identity, smoke tests, and support decisions before it is described as supported.

Packaging follow-ups are tracked in public issues:

Runtime dogfooding is strongest on Linux through Yazelix and Nix. The test workflow runs Rust checks on Linux, macOS, and Windows, and MSYS2 release-build checks on Windows, but interactive macOS validation and broad Windows runtime validation remain limited.

The release workflow is intentionally limited to v*.*.* tags and manual dispatch. It uses inherited GoReleaser Pro release machinery, requires GORELEASER_KEY for release execution, and only configures Apple signing when signing secrets are present.

The release-secrets decision is tracked in #7 and Bead yzt-c2d. Until that is resolved, treat Nix builds and source builds as the validated first-party surfaces, and treat inherited Rio release packaging as a path to evaluate instead of a public Mars guarantee.

Mars inherits substantial code and history from Rio. Rio is an incredible project, and Mars is grateful to Raphael Amorim, Rio's creator, and to everyone who has contributed to Rio.

Upstream Rio remains the baseline for terminal behavior, renderer fixes, and cross-platform packaging context. Mars should upstream generic fixes when they are useful beyond Yazelix.

Like Rio's creator, I was also born in Rio de Janeiro.

Mars follows Rio's MIT licensing.