Bash-compatible. Embeddable. Extensible.

Website · Install · Compatibility · Release notes · Discord

---

brush is a Bash-compatible shell written in Rust.

Run it as your everyday shell. It loads your existing .bashrc, aliases, functions, and completions, runs the scripts you already have, and adds some modern shell amenities: history-based suggestions and live syntax highlighting.

Build with it. brush-core is a tested implementation of Bash semantics that your own Rust software can embed and extend. brush-parser, which turns shell source into a syntax tree, is used on its own by other projects, including Zed, Vite+, and oh-my-pi, to parse shell commands.

Why brush

Bash is the shell most of us already know. It's in our fingers, our scripts, and our team's runbooks. brush keeps that behavior as it is, and adds suggestions, highlighting, and the other modern conveniences for those who want them. Keeping that promise means being faithful, so every change is tested against Bash itself.

The brush shell and its libraries are the same code. Embedding brush-core gives your software the behavior the shell has, and an improvement to one is an improvement to the other. brush is written in Rust with extension points designed in: custom builtins already plug in alongside the standard ones, and we intend to open more of the shell's internals the same way, so that tools can observe and extend it natively.

Get started

Install the latest release on Linux or macOS:

curl --proto '=https' --tlsv1.2 -fsSL https://brush.sh/install.sh | sh

Or with Homebrew or cargo:

brew install brush                    # Homebrew, on macOS or Linux
cargo install --locked brush-shell    # build from crates.io
cargo binstall brush-shell            # prebuilt, via cargo-binstall

Packagers have also brought brush to Homebrew, Arch Linux, Fedora via Terra, MSYS2, Nix, and more. See all install options for details.

Then run brush. It reads the same startup files Bash does, so it picks up your Bash setup as it is. To give brush a look of its own, add a ~/.brushrc.

Use the shell

• Your configuration comes with you. .bashrc, .bash_profile, aliases, functions, PS1, PROMPT_COMMAND, and prompt tools like starship all work as they do in Bash.
• Programmable completion. Works with the bash-completion package you already have installed, so git, docker, systemctl, and the rest complete as usual.
• Job control. Background jobs, suspend and resume, fg, bg, and jobs.
• Auto-suggestions. History-based hints as you type, on by default. Powered by reedline.
• Syntax highlighting. Live, as you type, one setting away: brush --enable-highlighting or syntax-highlighting = true under [ui] in brush's TOML config file.
• Scripts, too. The builtins, expansions, arrays, redirections, and options your scripts already use, with set -e, pipefail, extglob, globstar, and friends.
• Experimental extras. zsh-style precmd and preexec hooks, and terminal shell integration for VS Code, iTerm2, and other supporting terminals. Both are off by default; see experimental features.

Not everything is there yet. Most notably, select, wait -n, disown, some traps, and a set of edge cases are still missing. The compatibility reference lists what works, what's partial, and what isn't implemented. If you spot something that doesn't look right, please let us know by filing an issue.

Build with the engine

The same implementation that runs the shell is available as a set of crates. Create a shell, run Bash-compatible code in it, and inspect the result:

let mut shell = brush_core::Shell::builder().build().await?;

let result = shell
    .run_string(
        r#"greet() { echo "Hello, $1!"; }; greet world"#,
        &brush_core::SourceInfo::default(),
        &shell.default_exec_params(),
    )
    .await?;

assert!(result.is_success());

For more, see the examples: register a builtin written in Rust alongside the standard ones, call a shell function from Rust with control over its I/O, or parse a script and serialize its syntax tree. The examples guide describes each one and when it's useful.

Crate	API docs	What it provides
brush-core	docs.rs	The shell runtime: expansion, execution, jobs, completion, and the Shell API. Start here to embed.
brush-parser	docs.rs	Tokenizer and parser for Bash and POSIX shell syntax, with an optional serde AST. Usable independently from the other crates.
brush-builtins	docs.rs	The standard builtins, usable as a set. Depends on brush-core.
brush-interactive	docs.rs	Line editing, highlighting, suggestions, and completion UI, built on reedline. Depends on brush-core.
brush-shell	docs.rs	The brush binary and its command line. Depends on everything else.

Optional crates add bundled coreutils builtins and experimental builtins.

How we test it

• Compatibility suite. More than 2,500 test cases run the same script under brush and Bash and compare stdout, stderr, exit status, and filesystem side effects. Every pull request runs them on Linux (x86_64 and aarch64) and macOS, and inside Arch Linux, Debian, Fedora, NixOS, openSUSE, and Azure Linux containers.
• Real tools, real tests. End-to-end suites exercise brush with the tools people pair with a shell: fzf, atuin, starship, zoxide, mise, and others. Where a project has its own shell-integration tests, those run against brush; where it doesn't, we've added some.
• Everything else. CodeQL, dependency auditing, and benchmarks on every pull request, plus fuzz targets for the parser and the highlighter.
• Verifiable releases. Binaries are built by the release workflow with signed build provenance. The install script checks each download's SHA-256 checksum and, when the GitHub CLI is available, its attestation.

Platforms

Tier	Platforms	What that means
Supported	Linux: x86_64, aarch64 (glibc, musl) macOS: aarch64	Prebuilt binaries for every release, the full test suite on Linux x86_64 and aarch64 (glibc) and macOS aarch64, build checks for Linux musl and macOS x86_64, and daily-driver quality.
Preview	Windows: x86_64, aarch64	Windows receives build and static checks in CI along with a small brush-specific test suite; prebuilt binaries are on the way. Parts of the shell are still missing or limited but it's functional for basic usage, particularly when paired with Microsoft's build of coreutils for Windows.
Experimental	WASI 0.2	WASI builds run under wasmtime in CI. There are many significant gaps; more of a starting point for further experimentation.
Builds only	Android, FreeBSD, NetBSD, OpenBSD	Cross-compiled in CI so they keep compiling. No official tests, binaries, or validation.

Community and contributing

brush started as a curiosity-driven project, and that curiosity is still what drives it. Most contributors arrived the same way: tried brush, hit something unexpected, and helped fix it. However much time you have, there's a way in.

• Try it and tell us what you find. A script or command that behaves differently in Bash is the most useful report we get. File a compatibility bug, or a feature request if brush could do more for you.
• Say hello on Discord, whether you have a question, an idea, or a shell setup you'd like to see work. Or just come to chat and hang out.
• Pick up an issue. Issues labeled "good first issue" are intended for newcomers, and "help wanted" tag additional items where an extra pair of hands would help. Draft pull requests are welcome; if you ask us, we'll take an early look before you polish.
• Read the contribution guidelines for the workflow, and the technical docs for how brush is built and tested. Everyone here is expected to follow the code of conduct.

A star, a mention in your own project's README, or a post about brush all help too.

Curious how brush relates to other shells? See related projects.

Contributors

brush is shaped by everyone who has given it their time: bug reports with a reproducer, reviews that caught what we missed, packages for distributions we'd never touched, and a good deal of patient chat. Thank you, all of you. It's appreciated more than a line in a README can say.

There's room here for you, too.

Credits

brush stands on the shoulders of excellent open source projects, including (but not limited to):

• reedline for line editing and interactive features
• clap for command-line parsing
• fancy-regex for regular expressions
• tokio as the async runtime
• nix for accessing Unix and POSIX APIs
• criterion.rs for benchmarking
• bash-completion for its completion test suite

---

Released as open source under the MIT license. Built in the open by the brush community.