ZY

A Unix shell built entirely from scratch in C: lexer, parser, executor, line editor, prompt renderer, job control, signal handling, tab completion, history, audit logging, policy enforcement, and a structured data pipeline. No readline, no libedit, no yacc. Every subsystem is hand-written.

What began as a tamper-evident command logger grew into a full interactive shell with 356+ builtins, Nushell-style typed data pipelines, 18 truecolor themes, a built-in test framework, terminal data visualization, cheatsheet engine, script debugger, and a security stack with SHA-256 hash-chain audit logging and a policy engine. It runs as a daily-driver shell.

Expand

Get Started

sudo dpkg -i zy_1.0.9_amd64.deb

After Installation

Set zy as your default shell:

chsh -s /usr/bin/zy

Log out and back in, or start a new terminal. Every new session will launch zy.

Or try it without committing:

zy

This drops you into an interactive zy session inside your current shell. Type exit to return.

On first launch, zy runs a one-time setup: detects your terminal font (offers to install a Nerd Font if none is found), creates ~/.zyrc with sensible defaults, and opens the customize wizard for theme, prompt style, and feature toggles.

At a Glance

Architecture

SQLite is the only external dependency, powering three subsystems: audit ledger, frecency history, and directory jump rankings. Everything else is standard libc and POSIX.

Data Pipeline

Nushell-style structured data operations inside a POSIX-compatible shell. Values flow through pipes as typed data, no text parsing between stages.

ls | where size > 20kb | sort-by modified | first 5

The ZyValue tagged union supports: null, bool, int, float, string, list, record, table, filesize, and duration. Builtin-to-builtin chains never serialize to text; data flows as pointers through a global side-channel. When an external command enters the pipeline, zy auto-serializes (tables become TSV for awk/cut compatibility).

Prompt & Themes

Five prompt styles, 18 truecolor themes, and 13 configurable segments, all live-previewable through the customize wizard.

Expand

Security

Policy Engine

Sits between the parser and the executor. Every parsed command is checked against a rule list before execution.

policy add deny "rm -rf /*" "blocked: recursive root delete"
policy add warn "sudo *" "elevated privilege - are you sure?"
policy add rate_limit "curl *" --rate 10 "max 10 requests per minute"
policy restrict    # lock down all capabilities

Expand

Audit Logging

Every command goes into a local SQLite database with: command text, working directory, username, exit code, duration, timestamp, risk level, session ID, and device fingerprint. Each entry carries a SHA-256 hash computed over its full record plus the previous entry's hash, creating a tamper-evident chain.

audit verify       # check the hash chain end to end
audit log          # recent entries
audit export out   # dump as JSON
audit search sudo  # search for specific commands
audit risk         # show high-risk commands

Benchmarks

49 tests timed with hyperfine (--runs 10 --warmup 3 --shell none). Every test is a standalone POSIX #!/bin/sh script. Every shell runs the exact same file. Correctness is verified first: all three shells must produce identical output before any timing begins.

Run It Yourself

Install zy via the .deb package, then benchmark on your own machine. Copy-paste this self-contained 12-test script:

#!/usr/bin/env bash
# zy-quickbench.sh — 12-test benchmark: bash vs zsh vs zy
# Requires: hyperfine (sudo apt install hyperfine), bash, zsh, zy
set -euo pipefail
DIR=$(mktemp -d); trap 'rm -rf "$DIR"' EXIT
for sh in bash zsh zy; do
  command -v "$sh" &>/dev/null || { echo "Missing: $sh"; exit 1; }
done
command -v hyperfine &>/dev/null || { echo "Install: sudo apt install hyperfine"; exit 1; }
 
mk() { local f="$DIR/$1.sh"; cat > "$f"; chmod +x "$f"; echo "$f"; }
 
T01=$(mk while50k <<'S'
#!/bin/sh
i=0; while [ $i -lt 50000 ]; do i=$((i+1)); done; echo $i
S
)
T02=$(mk arith100k <<'S'
#!/bin/sh
i=0; while [ $i -lt 100000 ]; do i=$((i+1)); done; echo $i
S
)
T03=$(mk strconcat <<'S'
#!/bin/sh
s=""; i=0; while [ $i -lt 5000 ]; do s="${s}x"; i=$((i+1)); done; echo ${#s}
S
)
T04=$(mk funcall <<'S'
#!/bin/sh
f() { :; }; i=0; while [ $i -lt 20000 ]; do f; i=$((i+1)); done; echo $i
S
)
T05=$(mk arrayiter <<'S'
#!/bin/sh
a=""; i=0; while [ $i -lt 500 ]; do a="$a $i"; i=$((i+1)); done
j=0; while [ $j -lt 100 ]; do for x in $a; do :; done; j=$((j+1)); done; echo done
S
)
T06=$(mk ifsplit <<'S'
#!/bin/sh
line="one:two:three:four:five:six:seven:eight"
i=0; while [ $i -lt 10000 ]; do
  old="$IFS"; IFS=":"; set -- $line; IFS="$old"; i=$((i+1))
done; echo $i
S
)
T07=$(mk pipeline <<'S'
#!/bin/sh
i=0; while [ $i -lt 300 ]; do echo hello | cat >/dev/null; i=$((i+1)); done; echo $i
S
)
T08=$(mk subshell <<'S'
#!/bin/sh
i=0; while [ $i -lt 300 ]; do (echo hello) >/dev/null; i=$((i+1)); done; echo $i
S
)
T09=$(mk filetest <<'S'
#!/bin/sh
i=0; while [ $i -lt 20000 ]; do [ -f /etc/hostname ]; i=$((i+1)); done; echo $i
S
)
T10=$(mk echo20k <<'S'
#!/bin/sh
i=0; while [ $i -lt 20000 ]; do echo "hello" >/dev/null; i=$((i+1)); done; echo $i
S
)
T11=$(mk deepnest <<'S'
#!/bin/sh
i=0; while [ $i -lt 20000 ]; do
  if [ $((i%3)) -eq 0 ]; then if [ $((i%5)) -eq 0 ]; then if [ $((i%7)) -eq 0 ]; then
    :; fi; fi; fi; i=$((i+1))
done; echo $i
S
)
T12=$(mk mixed <<'S'
#!/bin/sh
c=0; t=0; i=0
while [ $i -lt 10000 ]; do
  x=$((i*3+7)); s="item_${i}_${x}"
  if [ $((i%2)) -eq 0 ]; then c=$((c+1)); fi
  t=$((t+x)); i=$((i+1))
done; echo "$c $t"
S
)
 
run() {
  echo "--- $1 ---"
  hyperfine --warmup 3 --runs 10 --shell none \
    -n bash "bash $2" -n zsh "zsh $2" -n zy "zy $2"
  echo
}
 
echo "=== zy Quick Benchmark (12 tests) ==="
echo "bash $(bash --version | head -1 | grep -oP '\d+\.\d+\.\d+'), \
zsh $(zsh --version | awk '{print $2}'), \
zy $(zy --version 2>&1 | grep -oP '\d+\.\d+\.\d+' || echo '?')"
echo
 
run "While loop 50K"         "$T01"
run "Arithmetic 100K"        "$T02"
run "String concat 5K"       "$T03"
run "Function call 20K"      "$T04"
run "Array iterate 500x100"  "$T05"
run "Word split IFS 10K"     "$T06"
run "Pipeline 300x"          "$T07"
run "Subshell 300x"          "$T08"
run "File test 20K"          "$T09"
run "Echo 20K"               "$T10"
run "Deep nesting 20K"       "$T11"
run "Mixed workload 10K"     "$T12"

Resource Footprint

The Line Editor

Custom terminal line editor: no readline, no libedit. Raw termios, custom cursor management, bracketed paste support.

• Syntax highlighting as you type: green for valid commands, red for missing, cyan for flags, magenta for variables, yellow for strings
• Autosuggestions: ghost text from history + Nushell-style dropdown menu
• Auto-pairing: brackets and quotes auto-close, backspace deletes both
• Magic space: !! + space expands to the last command inline
• Undo: Ctrl+_ with a 64-state deep stack

Expand

Tab Completion

Context-aware with fuzzy scoring. Two-pass: strict prefix first, then fuzzy fallback with a 9-factor weighted algorithm.

Expand

Expand

Built-in completion data for 15+ tools: git, docker, apt, ssh, systemctl, rg, fd, tmux, gh, jq, fzf, stow, make, npm, kubectl, compiled directly into the binary, no subprocess calls needed.

History & Navigation

Smart History

SQLite-backed with frecency scoring (frequency × recency), per-directory context, and duration tracking.

history            # show with timestamps
Ctrl+R             # fuzzy reverse search (9-factor scoring)
fc -l              # list entries
fc -e vim          # edit and re-execute

Full ! expansion: !!, !$, !^, !*, !n, !-n, !str, !?str?, ^old^new. With histverify, expansions are loaded into the editor for review before executing.

Navigation

cd /path           # standard
/some/path         # auto-cd: just type a directory name
...                # expands to ../..
z proj             # frecency jump to most-visited match
zi                 # interactive fuzzy directory picker

Expand

Scripting

Full POSIX sh compatible control structures plus zsh and Nushell extensions.

if [[ -f config.yaml ]]; then source config.yaml; fi
 
for f in *.c; do gcc -c "$f"; done
for (( i=0; i<10; i++ )); do echo "$i"; done
while [[ $retry -gt 0 ]]; do try_connect && break; (( retry-- )); done
 
select opt in "Build" "Test" "Deploy" "Quit"; do
    case $opt in Build) make ;; Quit) break ;; esac
done

# zy-native named parameters
def greet(name, greeting) { echo "$greeting, $name!" }
def --env setup(dir) { cd "$dir"; export ROOT="$PWD" }
 
# POSIX / bash / zsh syntax all work
greet() { echo "Hello, $1!"; }
() { local tmp="scoped"; echo "$tmp"; }  # anonymous function

# Nushell-inspired match
match $status {
    200 => { echo "OK" }
    404 => { echo "Not found" }
    _   => { echo "Status: $status" }
}
 
# case with 3 fall-through modes: ;; / ;& / ;;&
case $input in *.tar.gz) tar xzf "$input" ;; esac

try {
    mount /dev/sda1 /mnt
    do_risky_operation
} catch {
    echo "Error: $error"
} finally {
    umount /mnt
}

27 parameter expansion forms matching zsh: ${#var}, ${var:-default}, ${var//pat/repl}, ${var:offset:length}, ${var^^}, ${(s:d:)var}, and more.

Globbing

Standard globs plus extended patterns and zsh-style qualifiers:

*.c                # wildcard
**/*.h             # recursive globstar
{a,b,c}            # brace expansion
^pattern           # negation
*.c~test*          # exclusion
*(.)               # regular files only (qualifier)
*(/)               # directories only
*.c(:r)            # remove extension (modifier)

Built-in .gitignore support via setopt globfilter gitignore.

Files & Directories

zy follows XDG conventions and keeps a clean separation between configuration, data, and system-wide policy. Here is everything it touches on disk.

Configuration Files

SQLite Databases

SQLite is the only external dependency. Four databases live under ~/.local/share/zy/, all using WAL mode for crash safety.

Plain Text History

Directories

System-Wide Files

Login Shell Profiles

Installed Binaries

Marker Files

Configuration

customize          # interactive 4-step wizard with live preview
config set theme neon
config set prompt_style edge
config list        # show all 50+ settings

Expand

Help System

390+ help entries covering all 356+ builtins, organized into 30 categories. Built into the binary, no man pages, no external files.

Expand

help                  # overview
help --all            # everything
help <command>        # detailed usage
help --search <word>  # full-text search

Testing & Developer Tools

Eight subsystems built into the shell — no plugins, no external dependencies. Every feature ships in the same 5 MB binary.

Built-in Test Framework

Write assertions inline or in .zytest files and run them with test-run:

assert-eq (1 + 1) 2              # pass — values match
assert-true (echo hello | str contains "hello")
assert-type "42" "int"           # type checking
assert-error { bad-command }     # expects failure
test-run tests/math.zytest       # run a test file, report pass/fail/skip

Terminal Visualization

Render data directly in the terminal — no external plotting tools needed:

[3, 7, 2, 9, 5, 1, 8] | sparkline          # ▃▇▂█▅▁▇
seq 1 5 | wrap value | chart bar             # vertical bar chart
curl -s api/progress | progress --total 100  # ████████░░░░ 67%

Script Debugger

dbg script.zy launches an interactive debugger with gdb-style commands:

Cheatsheet Engine

50+ built-in cheatsheets, searchable with cheat <topic> or the Ctrl+H popup:

cheat git        # common git recipes
cheat tar        # tar flags you always forget
cheat zy-pipe    # zy pipeline operators

File Watcher, Task Runner, Session Recording

fs-watch src/ --glob "*.c" --exec "make"   # rebuild on file change
task build                                  # run task from .zytasks
record --output demo.json                   # start recording
replay demo.json                            # replay session
env-save work && env-restore work           # snapshot/restore env

Also Included

• Aliases: regular, global (-g, expands anywhere), suffix (-s, maps file extensions to handlers)
• Job control: full POSIX: fg, bg, wait, disown, process groups, Ctrl+Z
• Plugin system: auto-loads .so from ~/.zy/plugins/, plugins register builtins
• Shell options: errexit, nounset, xtrace, pipefail, noclobber, correct, 59 total
• I/O: all POSIX redirections + &>, <<<, <(), >()
• zsh compat: emulate, zmodload, strftime, zstat, compinit, autoload, and more
• "Did you mean?": Damerau-Levenshtein suggestions on command-not-found
• Nerd Font detection: auto-detects installed Nerd Fonts, falls back to Bare style if missing
• Built-in test framework: assert-eq, assert-ne, assert-true, assert-false, assert-error, assert-type, and test-run for running .zytest files
• Terminal visualization: sparkline, chart (bar/horizontal), progress bar — all in-shell, no external tools
• Cheatsheet engine: cheat command with 50+ built-in cheatsheets, Ctrl+H popup in the line editor
• Script debugger: dbg launches an interactive debugger with breakpoints, step, continue, variable inspection, and stack traces
• File watcher: fs-watch uses inotify to watch files/directories with glob patterns, debounce, and callback commands
• Task runner: task reads .zytasks files with dependency resolution — a built-in Make alternative for shell workflows
• Session recording: record / replay captures full pipeline I/O to JSON for auditing, demos, or debugging
• Environment snapshots: env-save / env-restore / env-snapshots — snapshot and restore environment state across sessions

Design Decisions

Download