zshrs — Documentation

SHELL SCRIPTS AT MACHINE CODE SPEED.

NO FORK. NO INTERPRETER. JUST BYTECODES.

0

forks in hot path

100%

bytecode compiled

18

worker threads

180+

builtins

23

coreutils builtins

100x

warm start speedup

2000x

fork avoidance speedup

1st

compiled Unix shell

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 │ │ 180+ 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│ │ │ └──────────┘ └────────┘ └────────┘ └───────────────┘

[0x01] ANTI-FORK ARCHITECTURE

Every fork is a full process copy. On macOS, fork() costs 2-5ms including exec + ld.so + libc init. zsh forks for every $(...), <(...), cat, grep, subshell, and completion. zshrs forks for none of them.

Operation	zsh	zshrs	Speedup
`cat file`	fork + exec /bin/cat	Builtin — zero fork	2000-5000x
`head`/`tail`/`wc`	fork + exec	Builtin — zero fork	2000-5000x
`sort`/`find`/`uniq`	fork + exec	Builtin — zero fork	2000-5000x
`date`/`hostname`/`uname`	fork + exec	Direct syscall	3000-8000x
`sleep`/`mktemp`/`touch`	fork + exec	Builtin — zero fork	2000-5000x
`xattr` operations	fork + exec xattr	Direct syscall	2000-5000x
`pmap`/`pgrep`/`peach`	fork N times to sh -c	VM execution — zero fork	Nx
`$(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	—
`rehash`	Serial `readdir` per PATH dir	Parallel scan across pool	—
Autoload function	Read file + parse every time	Bytecode deserialization from SQLite (µs)	100x

Coreutils Builtins (23 commands, zero fork)

cat  head  tail  wc  sort  find  uniq  cut  tr  seq  rev  tee
basename  dirname  touch  realpath  sleep  whoami  id  hostname
uname  date  mktemp

Every invocation of these commands is 2000-5000x faster than forking to the external binary.

[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 and Cranelift JIT. The same VM that powers stryke (which beats LuaJIT on benchmarks). No tree-walking interpreter remains. Hot bytecodes compile to native x86-64 machine code.

stryke source ───► stryke compiler ──┐ ├──► fusevm::Op ──► VM::run() ──► JIT ──► native zshrs source ───► shell compiler ──┘ │ ├── Linear JIT: straight-line code ├── Block JIT: loops, conditionals └── Cranelift codegen → x86-64

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

Parallel Primitives (VM-executed, zero fork)

Builtin	Description
`async` / `await`	Ship work to pool, collect result
`pmap`	Parallel map with ordered output — compiles to bytecode, runs on VM, zero forks
`pgrep`	Parallel filter — compiles to bytecode, runs on VM, zero forks
`peach`	Parallel for-each, unordered — compiles to bytecode, runs on VM, zero forks
`barrier`	Run all commands in parallel, wait for all

AOP / Debugging

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

Coreutils (Anti-Fork)

Builtin	Description	Speedup vs fork
`cat`	Concatenate files — no fork	2000-5000x
`head` / `tail`	First/last N lines — no fork	2000-5000x
`wc`	Line/word/char count — no fork	2000-5000x
`sort` / `uniq`	Sort and dedupe — no fork	2000-5000x
`find`	Walk directories — no fork	2000-5000x
`cut` / `tr` / `rev`	Text manipulation — no fork	2000-5000x
`seq` / `tee`	Number sequences, copy stdin — no fork	2000-5000x
`date`	Current date/time — direct strftime	3000-8000x
`sleep`	Delay — std::thread::sleep	2000-5000x
`mktemp`	Create temp file/dir — no fork	2000-5000x
`hostname` / `uname`	System info — direct syscall	3000-8000x
`id` / `whoami`	User info — direct syscall	3000-8000x
`touch` / `realpath`	File ops — no fork	2000-5000x
`basename` / `dirname`	Path manipulation — no fork	2000-5000x
`zgetattr` / `zsetattr`	xattr ops — direct syscall	2000-5000x

[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.

// ZSHRS — COMPILED SHELL

>_ZSHRS REFERENCE