RedBear-OS/local/recipes/shells/brush/source/docs/reference/experimental.md

Experimental Features

brush ships several features that are intentionally marked as experimental. They are usable today, but their interface or behavior may evolve based on feedback before being stabilized. This page is the canonical index of what's currently experimental and how to opt in.

Experimental features fall into two categories:

1. Build-time experiments — additional functionality gated behind Cargo feature flags. To get them, you build brush-shell with the relevant feature(s) enabled.
2. Run-time experiments — features that ship in standard builds but are off by default and enabled through configuration.

Names, defaults, and semantics of experimental features may change between releases.

---

Build-time experiments (Cargo features)

These are flags on the brush-shell crate. You can enable them individually, or pull in the whole set with the umbrella experimental feature.

# Enable everything experimental
cargo install --locked brush-shell --features experimental

# Or pick and choose
cargo install --locked brush-shell --features experimental-bundled-coreutils

experimental-bundled-coreutils

Bundles a configurable subset of uutils/coreutils implementations directly into brush-shell as builtins. Useful when:

• shipping brush into containers, embedded systems, or other environments where a standalone coreutils package is inconvenient or unavailable,
• distributing a single self-contained brush binary that doesn't rely on host utilities being present.

When enabled (via the umbrella experimental feature, or directly), the full set of supported utilities is bundled. When building the brush-coreutils-builtins crate directly, individual utilities can be selected via coreutils.<name> features (e.g., coreutils.cat, coreutils.ls); the coreutils.all feature enables all of them.

Bundled utilities run in-process and take precedence over external executables of the same name on PATH when invoked unqualified. As with any builtin, you can bypass the in-process implementation with command <name> or by giving an explicit path.

experimental-builtins

Pulls in the brush-experimental-builtins crate, which provides additional builtins that are too new or too narrow-purpose to ship in the default builtin set. Currently this includes:

• save — serializes the current shell state to JSON on stdout. Primarily intended for debugging and tooling. ⚠️ The serialized state may include sensitive information (variable values, command history, environment).

experimental-load

Enables serde-based serialization support in brush-core, and adds a --load <FILE> command-line flag that restores shell state from a JSON file previously produced by the experimental save builtin (or by other tooling that emits the same format). State loaded this way overrides non-UI command-line options. Useful for tooling built on top of brush-core that wants to snapshot or transfer shell state.

experimental-parser

Switches on the in-development winnow-based parser scaffolding in brush-parser, and adds an --experimental-parser command-line flag that selects it at runtime. This parser is not yet the production parser; the existing PEG parser remains the default. Enable this only if you're contributing to or experimenting with the parser work.

---

Run-time experiments (configuration)

These features ship in standard builds but are off by default. Each one can be enabled either through the optional TOML configuration file (under the [experimental] section, persistent across sessions) or through a command-line flag at startup (one-shot).

When both are specified, command-line flags take precedence over the configuration file.

[experimental]
zsh-hooks = true
terminal-shell-integration = true

Feature	TOML setting ([experimental])	Command-line flag
zsh-style hooks	zsh-hooks = true	--enable-zsh-hooks
Terminal shell integration	terminal-shell-integration = true	--enable-terminal-integration

zsh-hooks

Enables zsh-style preexec and precmd hook functions. When set:

• A function named preexec (if defined) is invoked before each interactively-entered command runs, with the command line as $1.
• A function named precmd (if defined) is invoked just before each prompt is displayed.

This is convenient for prompt frameworks, command timing, and integrations that expect zsh-style hook conventions. Equivalent behavior in stock bash typically requires DEBUG/PROMPT_COMMAND plumbing.

Enable persistently with zsh-hooks = true under [experimental] in config.toml, or per-invocation with brush --enable-zsh-hooks.

terminal-shell-integration

Emits standard terminal shell-integration escape sequences (semantic prompt and command boundary marking) that modern terminal emulators — including VS Code, iTerm2, WezTerm, and others — use to enable features like command navigation, exit-status display, and selective output copying. This is off by default to avoid emitting escape sequences in terminals that don't recognize them.

Enable persistently with terminal-shell-integration = true under [experimental] in config.toml, or per-invocation with brush --enable-terminal-integration.

---

Reporting feedback

Experimental features are the place where your feedback is most valuable — they exist precisely because we want to iterate on them before stabilizing. If you try one and find a rough edge, missing capability, or behavior that surprises you, please file an issue.