Polyglot Intermediate Representation & Toolchain
crushlang.org ยท Language Guide
Crush is a capability-based, polyglot programming language and virtual runtime. This repository hosts the standalone Crush implementation: providing the CAST intermediate representation, tree-sitter grammar, polyglot walkers, compiler frontend, VM runtime, package manager, and installer.
๐ crushlang.org for the landing page and a live example, or docs.crushlang.org for the full language guide (syntax, capability system, polyglot programming, stdlib, CAST/CASM, worked examples).
cargo install crush-lang-sdk # crush, crushc, crush-run, crush-repl, crush-compile, crush-diff, crush-debugNot
cargo install crushโ thecrushcrate on crates.io is an unrelated project. The toolchain is published ascrush-lang-sdk(pluscrush-pkg,crush-installer, and the library crates). There is nocrush-astcrate; that's this repository's name.
Prebuilt binaries. Starting with v0.9.0, every vX.Y.Z tag has a GitHub pre-release with a
Linux x86_64 tarball (crush, crushc, crush-run, crush-compile, crush-repl, crush-debug,
crush-pkg, crush-gui), the browser runtime (crush-web-<ver>-pkg.tar.gz) and SHA256SUMS, so
cargo binstall crush-lang-sdk downloads instead of compiling. (Pre-releases until 1.0: see
docs/planning/RELEASE-1.0-CRITERIA.md.)
Updating. crush update (= crush-installer update; needs cargo install crush-installer)
replaces the binaries of a tarball/crush-installer install with the newest release: it checks the
download against the release's SHA256SUMS before extracting and swaps every binary in with an
atomic rename (a failure leaves the old set), so it can replace the running crush. Linux x86_64
only; a cargo install is refused โ update that with cargo install crush-lang-sdk.
crush update --check # exit 0 = up to date, 10 = update available; writes nothing
crush update # newest release; never downgrades
crush update --version 0.9.0 # pin (the only way to downgrade)
crush update --dir ~/opt/crush # default: crush's own dir if crush-installer manages it, else ~/.crush/binFile types and editors. So file managers, file(1) and editors recognise .crush, .cast.json,
.casm, .cvm1, capsule.toml and the rest: crush-installer install --desktop-integration
(opt-in) registers the MIME types and magic(5) rules, and contrib/ has
Vim/Neovim, Helix, Emacs and Zed support plus the tree-sitter queries.
All crates are released together at the workspace version in Cargo.toml.
| Command | What it does |
|---|---|
crush / crush repl |
interactive REPL |
crush run FILE |
run a program: .crush, CAST (.cast.json/.castb), CASM (.casm), .cvms, .cvm1 |
crush build FILE |
compile to .cvm1 (--emit casm|cvms|cast|ast for the other forms) |
crush cast CMD FILE |
CAST tools: validate, pack, unpack, format, diff |
crush debug FILE --step --inspect |
breakpoints by source line, step, watch, print (grant-gated) |
crush gui run FILE --ui |
run a program that draws a window with ui.* (needs crush-gui) |
crush doctor |
check the host runtimes polyglot blocks need |
crush update [--check] |
update to the newest GitHub release (needs crush-installer) |
crates/
โโโ crush-errors/ # Unified error types (leaf crate)
โโโ crush-cast/ # CAST โ Crush Abstract Syntax Tree IR
โโโ crush-cosm/ # COSM โ Crush Object Semantic Model: Kind declarations, C3, validation (structs/impl/trait/@kind)
โโโ crush-caison/ # CAISON (formerly CSON) format + `caison.parse` VM capability
โโโ crush-cson-shim/ # retired `crush-cson` name: re-exports crush-caison
โโโ casm/ # CASM โ Crush Assembly bytecode format
โโโ tree-sitter-crush/ # Tree-sitter grammar for the Crush language
โโโ crush-diagnostics/ # Shared diagnostics/wire-format types
โโโ crush-index/ # Cross-crate symbol/reference index
โ
โโโ crush-walker-core/ # LanguageAdapter trait + shared walker utilities (renamed from walker-core)
โโโ cli/ # crush-walker โ CLI that auto-detects source language and dispatches a walker
โโโ crush-lang-python/ # Python โ CAST (bin: python_walker)
โโโ crush-lang-rust/ # Rust โ CAST (syn-based; refuses what it can't prove exact)
โโโ crush-lang-js/ # JavaScript โ CAST
โโโ crush-lang-go/ # Go โ CAST
โโโ crush-lang-c/ # C โ CAST
โโโ crush-lang-zig/ # Zig โ CAST
โโโ crush-lang-bash/ # Bash โ CAST
โโโ crush-lang-zsh/ # Zsh โ CAST
โโโ crush-lang-wasm/ # WebAssembly walker โ parses Wasm modules into CAST IR
โโโ crush-lang-dart/ # Dart โ CAST
โโโ crush-lang-nepali/ # Nepali (Sona) โ CAST
โโโ crush-lang-java/ # Java โ CAST (skeleton)
โโโ crush-lang-custom/ # Custom/user-defined language adapter scaffold
โ
โโโ crush-frontend/ # Crush language parser, semantic analyzer, optimizer, and CASM compiler
โโโ crush-lang-sdk/ # Rust SDK for hosting the CVM1 runtime (bins: crush, crushc, crush-run, crush-compile, crush-repl, crush-diff, crush-debug)
โโโ crush-vm/ # CVM1 bytecode assembler, disassembler, and sandboxed interpreter (incl. polyglot exec + capability gates)
โโโ crush-vm-capi/ # C API shared library for embedding CrushVM in C/C++ programs
โโโ crush-vm-py/ # Python extension module (PyO3) exposing the canonical CVM1 VM (outside the workspace)
โโโ crush-jit/ # Cranelift-based JIT backend (native execution tier)
โโโ crush-aot/ # AOT: CASM โ Rust (rustc) or C (gcc/clang) โ native .so (bins: crush-aotc, crush-walk-run)
โโโ crush-aotc/ # Typed AOT compiler library: CASM โ C source โ shared library (.so)
โโโ crush-ptx/ # CASM โ PTX (NVIDIA GPU assembly) emission backend
โโโ crush-web/ # Browser WebAssembly runtime (outside the workspace; its pkg ships with each tag's pre-release)
โโโ crush-ffi/ # C-ABI plugin interface
โโโ crush-plugin-example/ # Example native plugin built on crush-ffi
โโโ crush-python/ # PyO3 bindings exposing crush-cast to Python
โโโ crush-debugger/ # Debugger engine over crush-vm (breakpoints, step, watch, grant-gated inspection); `crush debug` / `crush-debug`
โโโ crush-lint/ # Static lint pass over CAST/CASM
โโโ crush-macros/ # Proc-macros shared across the workspace
โโโ crush-net/ # Raw TCP/TLS sockets as `tcp.*` capabilities (`--tcp`, `--tcp-listen`)
โโโ crush-tui/ # Terminal UI front-end
โโโ crush-gui/ # Desktop GUI: `ui.*` capabilities on arniko/bliss (`crush gui run`, `--ui`; not a default member, needs fontconfig)
โโโ crush-pkg/ # Package manager โ cargo-like build tool for Crush (uses buckets for sandboxed script runtimes)
โโโ crush-installer/ # Toolchain installer and uninstaller
You need Rust 1.95 or newer (the MSRV that CI checks; rust-toolchain.toml selects stable). crush-pkg and crush-vm path-depend on
nixpt/buckets, so clone it next to this
repo first (CI does the same):
git clone https://github.com/nixpt/buckets ../buckets# Build the core SDK and package manager (`cargo build` alone builds every
# default member; `crush-gui` is left out because it needs `libfontconfig1-dev`)
cargo build -p crush-lang-sdk -p crush-pkg
# Install to ~/.crush using the included installer
cargo run --bin crush-installer -- install --bin-dir target/debug# Check compiler options
cargo run --bin crushc -- --help
# Run a Crush script directly
cargo run --bin crush-run -- run my-program.crushA first program, with what it prints (verified against faeb86e8, 2026-10-31):
fn make_counter() {
let c = 0
return || {
c = c + 1
return c
}
}
let next = make_counter()
next()
print(next())
2
Capabilities are opt-in per run. The standard library (str.*, math.*,
json.*, โฆ) is on by default; everything that touches the host needs a flag
(--fs, --net, --tcp, --env, --time, --process, --polyglot, โฆ), and a program
that needs an ungranted capability is refused before it runs.
crush-run caps FILE shows what a program needs without running it.
Raw sockets (tcp.*, crate crush-net) have their own grants: --tcp for
outbound client sockets and a separate, stronger --tcp-listen for being a
server; --net is HTTP-client only and grants neither.
The Crush pipeline seamlessly converts polyglot source code down to execution-ready bytecode through an interconnected set of stages.
graph TD
A[Source File<br/>.crush, .py, .rs, .go, .c, .js, .sh, .zig, .wasm] --> B
B(Walker<br/>Language-specific tree-sitter โ CAST) --> C
C[CAST<br/>Crush AST โ .cast.json / CBOR .castb] --> D
D(Crush Compiler<br/>crates/crush-frontend) --> E
E[CASM<br/>Crush Assembly IR โ JSON .casm / MessagePack .casmb] --> G
G[CVM1 bytecode<br/>.cvm1 โ assembly text .cvms] --> F
F((CVM1 VM<br/>Execution))
classDef file fill:#2d3436,stroke:#74b9ff,stroke-width:2px,color:#fff
classDef process fill:#0984e3,stroke:#74b9ff,stroke-width:2px,color:#fff
class A,C,E,G file
class B,D,F process
Every extension, its encoding, version constant and who reads/writes it:
docs/FILE-FORMATS.md.
examples/crush/ holds 50+ .crush programs, from language-feature smoke
tests (arithmetic.crush, control_flow.crush, exception_test.crush, ...) to full self-playing
programs written by several different LLMs given the same "learn this language" prompt โ two
hosted-language interpreters (forth.crush, brainfuck.crush), self-playing games
(tictactoe.crush, lights_out.crush, pong.crush, breakout.crush), an IDA*-based 15-puzzle
solver (fifteen_puzzle.crush), and Conway's Game of Life. The story behind that particular set โ
which model wrote what, and the real language constraints/bugs each one hit โ is documented in
nixpt/awesome-crush.
- The Crush Language Guide (docs.crushlang.org) โ language reference, examples, CAST/CASM specifications. Every example in it is run against a pinned crush-ast commit, and its
examples/verified/corpus keeps one small program per language behaviour with its exact output. - Comprehensive crate-level documentation is available in the respective
crates/*/README.mdfiles.
Licensed under either of MIT or Apache License 2.0 at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work shall be dual-licensed as above, without any additional terms or conditions.