zshrs — Documentation

>_ZSHRS REFERENCE

The most powerful shell ever created. No-fork architecture, AOP intercept, worker thread pool, bytecode caching, fusevm compiled execution.

SHELL SCRIPTS AT MACHINE CODE SPEED.

NO FORK. NO INTERPRETER. JUST BYTECODES.

forks in hot path

100%

bytecode compiled

worker threads

145+

builtins ported

118K

lines of Rust

1st

compiled Unix shell

1st

shell with AOP

1970

year Unix was born

For the first time in the history of computing — since the dawn of Unix at Bell Labs in 1970 — a shell compiles to executable bytecodes and runs them on a virtual machine with fused superinstructions. Every interactive command line, every shell script, every function invocation, every source’d file compiles to fusevm bytecodes and executes at near-machine-code speed. No tree-walking interpreter. No fork. No parsing at runtime if bytecodes are cached.

Compiled bytecodes are cached in SQLite. Function invocations deserialize cached bytecodes in microseconds — skipping the lexer, parser, and compiler entirely. source’d scripts and interpreted scripts follow the same path: compile once, cache, execute from bytecode forever. This has never been achieved in a Unix shell.

[0x00] THE COMPILATION PIPELINE

Every path through zshrs ends at the same place: fusevm bytecode execution.

┌─────────────────────────────────────────────────────────────────┐ │ THREE EXECUTION PATHS │ │ │ │ ┌─────────────┐ Interactive command line │ │ │ REPL Input │──► Parser ──► ShellCompiler ──► fusevm::Op │ │ └─────────────┘ │ │ │ ▼ │ │ ┌─────────────┐ Shell script / source file VM::run() │ │ │ Script File │──► Parser ──► ShellCompiler ──► │ │ │ └─────────────┘ │ │ │ │ └──► SQLite bytecode ──────┘ │ │ (cached on first compile) │ │ │ │ ┌─────────────┐ Autoload function (compinit) │ │ │ SQLite DB │──► bincode::deserialize ──► fusevm::Chunk ──► │ │ │ .bytecode │ (no lexer, no parser, VM::run() │ │ └─────────────┘ no compiler — microseconds) │ └─────────────────────────────────────────────────────────────────┘

Path	Lex	Parse	Compile	Execute	Cache
Interactive command	Yes	Yes	Yes	fusevm	No (ephemeral)
Script file (first run)	Yes	Yes	Yes	fusevm	Yes → SQLite
Script file (cached)	No	No	No	fusevm	Hit → deserialize
Autoload function (cached)	No	No	No	fusevm	Hit → deserialize
Plugin source (cached)	No	No	No	fusevm	Delta replay → µs

[0x01] ARCHITECTURE

zshrs Architecture ┌─────────────────────────────────────────────────────┐ │ REPL / ZLE │ │ reedline + syntax highlighting + autosuggestions │ └──────────────────────┬──────────────────────────────┘ │ ┌──────────────────────▼──────────────────────────────┐ │ ShellExecutor (19K lines) │ │ parser ─► compiler ─► fusevm bytecode dispatch │ │ 145 builtins │ AOP intercept │ trap/signal │ └──────┬─────────┬─────────┬─────────┬────────────────┘ │ │ │ │ ┌──────▼───┐ ┌───▼────┐ ┌─▼──────┐ ┌▼──────────────┐ │ Worker │ │ SQLite │ │ fusevm │ │ compsys │ │ Pool │ │ Caches │ │ VM │ │ completion │ │ [2-18] │ │ │ │ │ │ engine │ │ threads │ │history │ │ Op enum│ │ │ │ │ │compsys │ │ fused │ │ MenuState │ │ glob │ │plugins │ │ super- │ │ MenuKeymap │ │ rehash │ │bytecode│ │ instr │ │ SQLite FTS5 │ │ compinit │ │ │ │ JIT ► │ │ │ │ history │ │ │ │Cranelft│ │ │ └──────────┘ └────────┘ └────────┘ └───────────────┘

[0x02] NO-FORK ARCHITECTURE

[0x01] NO-FORK ARCHITECTURE

Every fork is a full process copy. On macOS, fork() costs 50-500µs and duplicates the entire shell's address space. zsh forks for every $(...), <(...), subshell, and completion. zshrs forks for none of them.

Operation	zsh	zshrs
`$(cmd)`	fork + pipe + exec	In-process stdout capture via `dup2`
`<(cmd)` / `>(cmd)`	fork + FIFO	Worker pool thread + FIFO
Glob `*/.rs`	Single-threaded `opendir`	Parallel `walkdir` per-subdir on pool
Glob qualifiers `*(.x)`	N serial `stat` calls	One parallel metadata prefetch, zero syscalls after
`rehash`	Serial `readdir` per PATH dir	Parallel scan across pool
`compinit`	Synchronous fpath scan	Background scan on pool + bytecode pre-compilation
History write	Synchronous `fsync` blocks prompt	Fire-and-forget to pool
Autoload function	Read file + parse every time	Bytecode deserialization from SQLite (µs)
Plugin source	Parse + execute every startup	Delta replay from SQLite cache (µs)

[0x02] WORKER THREAD POOL

Persistent pool of warm threads. Bounded crossbeam channel with backpressure. Panic recovery keeps workers alive. Task cancellation on Ctrl-C. Instant shutdown on exit.

# ~/.config/zshrs/config.toml
[worker_pool]
size = 8            # 0 = auto (num_cpus clamped [2, 18])

[completion]
bytecode_cache = true  # compile autoload functions to fusevm bytecodes

[history]
async_writes = true # write history on worker pool

[glob]
parallel_threshold = 32   # min files before parallel metadata prefetch
recursive_parallel = true # fan out **/ across worker pool

Tasks shipped to the pool:

compinit

Background fpath scan + bytecode compilation of 16K+ functions

Process Sub

<(cmd) and >(cmd) on pool threads instead of fork

Parallel Glob

**/ recursive walk split per-subdir across pool

Metadata Prefetch

Glob qualifiers: one parallel stat batch, zero syscalls after

PATH Rehash

Parallel readdir across every PATH directory

History Writes

SQLite inserts on pool thread — prompt never waits

[0x03] AOP INTERCEPT

The first shell ever with aspect-oriented programming. Hook before, after, or around any command or function — at machine code speed, no fork. One primitive that replaces defer, profile, memo, retry, and timeout.

# Before — log every git command
intercept before git { echo "[$(date)] git $INTERCEPT_ARGS" >> ~/git.log }

# After — show timing for completion functions
intercept after '_*' { echo "$INTERCEPT_NAME took ${INTERCEPT_MS}ms" }

# Around — memoize expensive function
intercept around expensive_func {
    local cache=/tmp/cache_${INTERCEPT_ARGS// /_}
    if [[ -f $cache ]]; then cat $cache
    else intercept_proceed | tee $cache; fi
}

# Around — retry with backoff
intercept around flaky_api {
    repeat 3; do intercept_proceed; [[ $? == 0 ]] && break; sleep 1; done
}

# Fat binary — stryke code at machine code speed
intercept after 'make *' { @pmaps { notify "done: $_" } @(slack email) }

Variables available in advice:

Variable	Available	Description
`$INTERCEPT_NAME`	all	Command name
`$INTERCEPT_ARGS`	all	Arguments as space-separated string
`$INTERCEPT_CMD`	all	Full command string
`$INTERCEPT_MS`	after	Execution time in milliseconds (nanosecond source)
`$INTERCEPT_US`	after	Execution time in microseconds
`$?`	after	Exit status

[0x04] SQLITE CACHING LAYER

Three SQLite databases power the shell. WAL mode, mmap_size=256MB, cache_size=64000 pages. FTS5 for instant fuzzy search.

compsys.db

Completion cache: autoloads with source text + compiled bytecodes, comps mapping, services, patcomps, PATH executables with FTS5 index

history.db

Command history: frequency-ranked, timestamped, duration, exit status, working directory. FTS5 search.

plugins.db

Plugin delta cache: functions, aliases, variables, exports, arrays, completions, fpath, hooks, bindkeys, zstyles, options, autoloads. Source once, replay microseconds.

Browse caches without SQL:

dbview                      # list all tables + row counts
dbview autoloads             # dump autoloads: name, body size, ast size
dbview autoloads _git        # single row: source, body, ast status, preview
dbview comps git             # search comps for "git"
dbview executables rustc     # search PATH cache
dbview history docker        # search history

[0x05] BYTECODE CACHING

Every autoload function in fpath gets compiled to fusevm bytecodes during compinit. The bytecodes are serialized to bincode and stored in SQLite. Subsequent loads skip lexing, parsing, and compilation entirely — pure deserialization to executable bytecodes in microseconds.

First call to _git: fpath/_git (source text) │ ▼ ShellParser::parse_script() ~1ms │ ▼ ShellCompiler::compile() ~0.5ms │ ▼ fusevm::Chunk (bytecodes) │ ├──► VM::run() native dispatch │ └──► bincode::serialize() ~0.1ms │ ▼ SQLite autoloads.bytecode (stored) Every subsequent call: SQLite autoloads.bytecode │ ▼ bincode::deserialize() ~0.05ms │ ▼ fusevm::Chunk (no lexer, no parser, no compiler) │ ▼ VM::run() native bytecode dispatch

[0x06] FUSEVM BYTECODE TARGET

100% lowered. Every shell construct compiles to fusevm bytecodes — a language-agnostic VM with fused superinstructions. The same VM that powers stryke (which beats LuaJIT on benchmarks). No tree-walking interpreter remains. Cranelift JIT will compile hot bytecodes to native machine code.

stryke source ───► stryke compiler ──┐ ├──► fusevm::Op ──► VM::run() zshrs source ───► shell compiler ──┘

Shell constructs already lowered to fusevm bytecodes:

Arithmetic

$(( )) — full precedence, ternary, assignment, hex/octal, bitwise

Loops

for, for(()), while, until, repeat

Conditionals

if/elif/else, case, [[ ]] with all file tests and comparisons

Commands

Exec, ExecBg, pipelines, redirects, here-docs, here-strings

Functions

Definition, Call/Return, PushFrame/PopFrame

Fused Ops

AccumSumLoop, SlotIncLtIntJumpBack, PreIncSlotVoid — single-dispatch loop execution

[0x07] EXCLUSIVE BUILTINS

Builtins that only exist because they need access to the runtime internals. Can't be external tools. Can't be shell functions.

Builtin	Description
`intercept`	AOP before/after/around advice on any command. Glob pattern matching. Nanosecond timing. Stryke `@` dispatch in advice (fat binary).
`intercept_proceed`	Call original command from around advice.
`doctor`	Full diagnostic: worker pool metrics, cache stats, bytecode coverage, option count, startup health.
`dbview`	Browse SQLite caches without SQL. Tables: autoloads, comps, executables, history, plugins.
`profile`	In-process command profiling. Nanosecond `Instant::now()` accuracy. No fork overhead in measurement. Function-level call tree.

[0x08] INSTALL

# Lean build — pure shell, all features, no stryke
cargo install --path zsh

# Fat build — shell + stryke runtime (@ prefix, AOP stryke advice)
cargo install strykelang

# From source
git clone https://github.com/MenkeTechnologies/strykelang
cd strykelang
cargo build --release -p zsh    # target/release/zshrs

# Set as default shell
sudo sh -c 'echo /Users/$(whoami)/.cargo/bin/zshrs >> /etc/shells'
chsh -s /Users/$(whoami)/.cargo/bin/zshrs

# Tab completion for zshrs itself
cp completions/_zshrs /usr/local/share/zsh/site-functions/

[0x09] DIAGNOSTICS

# Full health check
zshrs --doctor

# In-session diagnostics
doctor

# Browse cache
dbview
dbview autoloads _git

# Profile a command
profile 'compinit'
profile -s 'for i in {1..1000}; do echo $i > /dev/null; done'

# Show intercepts
intercept list

[0xFF] THE PHILOSOPHY

Shells haven't fundamentally improved since the 1990s. bash is a GNU rewrite of the Bourne shell from 1979. zsh added features but kept the fork-based C architecture. fish focused on UX and abandoned POSIX. nushell reinvented the data model but lost compatibility.

zshrs takes a different approach: keep everything that makes zsh powerful — glob qualifiers, parameter expansion flags, the completion system, ZLE, zstyle, modules — and replace the runtime with modern systems engineering. Rust instead of C. Thread pool instead of fork. SQLite instead of flat files. Bytecode VM instead of tree-walker. AOP instead of monkey-patching.

The result is the first shell that gets faster as you add more plugins, because the plugin cache means each plugin is only parsed once. The first shell where **/*.rs scales with your CPU count. The first shell where you can intercept any command with nanosecond-accurate timing and zero overhead.

The result is the first shell where every command — interactive or scripted — compiles to bytecodes and executes on a VM with fused superinstructions. The first shell where autoload functions load from pre-compiled bytecodes in microseconds. The first shell where source ~/.zshrc can skip the lexer, parser, and compiler entirely because the bytecodes are cached in SQLite.

Since the Bourne shell at Bell Labs in 1970, through csh, ksh, bash, zsh, and fish — every Unix shell has been an interpreter. zshrs is the first to be a compiler. Shell scripts at machine code speed. Achieved in alpha.

THE FIRST COMPILED UNIX SHELL. THE MOST POWERFUL SHELL EVER CREATED.