Hypershell is a small language for writing shell-script-like programs in Rust, built with Context-Generic Programming (CGP), a language extension for Rust with pluggable trait implementations at compile-time. A Hypershell program is a Rust type, and the context that runs it is its interpreter: a type whose wiring chooses how each piece of the program behaves. So both the language's syntax and its meaning can be extended without editing the crates that define them.
Hypershell is an experimental proof of concept. It shows how CGP builds a modular language in Rust, and it is not meant to replace a shell.
Project page · Examples · CGP quickstart · Introduction post
This is the smallest Hypershell program. It runs echo hello world! and prints the output:
use hypershell::prelude::*;
pub type Program = hypershell! {
SimpleExec<
StaticArg<"echo">,
WithStaticArgs["hello", "world!"],
>
| StreamToStdout
};
#[tokio::main]
async fn main() -> Result<(), Error> {
HypershellCli
.handle(PhantomData::<Program>, Vec::new())
.await?;
Ok(())
}Program is a type alias, not a value. Each piece of it, such as SimpleExec or StreamToStdout,
is an empty struct that says nothing about how it runs, and the hypershell! macro only rewrites
the shell-like surface into that type: the | becomes a pipeline, the brackets a type-level list,
and each string a type-level string.
Running the program is one handle call on a context. HypershellCli is the context here, and this
is its entire definition:
pub struct HypershellCli;
delegate_components! {
HypershellCli {
namespace HypershellNamespace;
}
}The one line joins HypershellNamespace, which routes each piece of syntax to the implementation,
or provider, that interprets it. The compiler resolves every choice while it type-checks the
program, so the call compiles to direct calls to those providers, with no interpreter running at run
time. A context of your own can join the same namespace, add fields that a program reads, such as a
URL, or join a namespace that extends the language with new syntax.
Add hypershell, cgp, and an async runtime to your Cargo.toml:
[dependencies]
cgp = "0.8.0"
hypershell = "0.2.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }The hypershell! macro expects hypershell::prelude::* in scope, and its expansion names the cgp
crate, so a program's crate depends on both.
The library crates build on stable Rust, and so does a small program such as the one above. Large
programs can need nightly Rust with the next-generation trait solver. On stable Rust 1.98.1, the
repository's two compare examples, which nest whole programs inside others, grew rustc to about
7 GB while type-checking and were stopped; on nightly with -Z next-solver=globally, a fresh check
of one of them took about 9 seconds and 460 MB. A crate with programs of that size can copy the
repository's rust-toolchain.toml and .cargo/config.toml, which select a dated nightly and turn
the solver on.
Hypershell is split into crates by backend, so a program compiles only the libraries it uses:
hypershell: the main crate, withHypershellNamespace, the error wiring, theHypershellCliandHypershellHttpcontexts, and the prelude a program imports.hypershell-macro: thehypershell!macro, which provides the shell-like syntax.hypershell-components: the syntax, such asSimpleExecandStreamingExec, and the CGP components and traits the language builds on.hypershell-tokio-components: running external commands, files, and streams, on Tokio.hypershell-reqwest-components: HTTP requests, such asSimpleHttpRequestandStreamingHttpRequest, onreqwest.hypershell-json-components: JSON encoding withEncodeJsonand decoding withDecodeJson.hypershell-hash-components: an extension with native checksums (Checksum) and hex encoding (BytesToHex).hypershell-tungstenite-components: an extension with native WebSockets.
The two extensions are not part of HypershellNamespace, so a program that uses them joins an
extended namespace or wires them on its context, as the examples show. The unpublished
hypershell-examples crate holds the examples below.
Each example is a runnable program, run from the repository's root with
cargo run -p hypershell-examples --example <name>. Most need the network and a few common
command-line tools.
hello.rs: runsecho hello world!throughSimpleExec.hello_name.rs: passes a value from a field of the context to a shell command withFieldArg.http_checksum_cli.rs: fetches a URL withcurland pipes the output tosha256sumandcutas streaming commands.http_checksum_client.rs: fetches the URL with the native HTTP client, then pipes the response through the same commands.http_checksum_native.rs: the same checksum in native stages, from a language extended withChecksum.nix_manual.rs: combines a native HTTP request with external command-line tools.save_webpage.rs: downloads a webpage as a stream and writes it to a file.github_issues.rs: calls a JSON web API and decodes the result into a Rust type.rust_playground.rs: sends a Rust snippet to the Rust Playground API as JSON and decodes the response.bluesky.rs: connects to the Bluesky firehose throughnix-shellandwebsocat, then filters the stream withgrep.bluesky_websocket.rs: the same firehose, with native WebSockets added to the language.compare_and_branch.rsandparallel_compare.rs: compare the outputs of pipelines and branch on the result, with syntax the examples crate adds.
Hypershell is a demonstration, and these are the costs to weigh first:
- Large programs need nightly. As Installation describes, the library and small programs build on stable Rust, and programs that nest others deeply can need nightly with the new trait solver.
- Programs are fixed at compile time. A program is a type, so it cannot be loaded or changed while the application runs. Values a program needs at run time, such as a URL, come from fields of its context.
- Error messages are long. A mistake in a program is a compile error, and the compiler's raw
message lists every step it took before it failed. Checking the program with
check_components!and reading the error withcargo cgp checkhelps:cargo cgp checkleads with the root cause for the classes it recognizes, and the tool does not yet reshape every class. - It is lightly tested. Its value is as a worked example rather than a tool for production, and the limitations page describes where the design stops and when a shell script or plain Rust fits better.
These are the commands CI runs:
cargo build --workspace --all-targets
cargo test --workspaceThe workspace pins nightly-2026-11-16 in rust-toolchain.toml, because .cargo/config.toml turns
on the next-generation trait solver with -Z next-solver=globally, so cargo selects that nightly
in the repository. Contributors and agents start from AGENTS.md, which names these
checks.
The project page explains Hypershell: its examples as short tutorials, the design one idea at a time, and guides to writing and debugging a program. For CGP itself, start with the quickstart, then the tutorials and the concepts, and the type-level DSLs page explains the technique behind Hypershell with a smaller language. The CGP knowledge base records the project in depth for contributors and agents.