// POWERLINERS — RUST POWERLINE

Why a port?

• Python interpreter startup adds ~100 ms per render — on every keystroke that triggers a zsh `precmd` redraw, every tmux statusline tick, every shell continuation line.
• At zpwr scale (256-thread workstation, 100+ zsh-in-tmux sessions), powerline-status compounds into seconds of cumulative latency per minute.
• Rust gives a static binary, microsecond startup, zero runtime deps, cross-arch builds, and predictable memory.
• The upstream theme grammar (JSON files in powerline/config/) is preserved verbatim — users keep their themes unchanged.

Targets

Port discipline

Every fn name landed in src/ported/ must exist in upstream powerline Python source. Enforced by tests/ported_fn_names_match_py.rs against docs/powerline_py_functions.txt (currently 624 names extracted from github.com/powerline/powerline). Maintainer-approved Rust-only exemptions live in tests/data/fake_fn_allowlist.txt.

# regenerate the upstream allowlist
./scripts/regen_py_functions.sh

# audit will fail with a list of any invented fn names
cargo test --test ported_fn_names_match_py

This pattern mirrors the zshrs ported_fn_names_match_c.rs enforcement — the audit test is load-bearing and must not be weakened.

Status

Port is structurally complete at the function level. 134 of 137 upstream Python files are at DONE tier per the citation-density classifier (scripts/gen_port_checklist.py); the 3 remaining NEAR files are Python lipstick — zero-fn class shells (renderers/shell/readline.py and renderers/shell/zsh.py each hold two escape-marker string constants and a class alias; bindings/i3/powerline-i3.py's single render fn is already 100% ported per docs/port_report.html). No behavioral surface left to port — the classifier's py_fn_total == 0 denominator just can't promote 0/0 → DONE. The Rust port spans ~66,043 LOC across src/ported/ with 2,436 lib tests + 2 audit tests + 462 parity tests passing. Parity tests pipe identical inputs through the upstream Python interpreter (via the vendored powerline-status) and the Rust port, asserting byte/value-identical results — 11 real port bugs were surfaced by this harness and fixed in-tree (ThreadedSegment.daemon, Spec.did_type, encoding locale lookup, _clear_special_values UB, Spec.ident regex, Spec.context_message recursion, Spec.tuple bounds, Spec.unknown_msg/_spec dispatch, NON_PRINTABLE_RE inversion, Spec.printable/unsigned). Every fn name under src/ported/ traces to one of 624 upstream Python fn names (or to tests/data/fake_fn_allowlist.txt for maintainer-approved exemptions); every ported body carries // py:NNN line-citations against upstream powerline/. End-to-end statusline rendering against a real .json theme tree runs through the Powerline orchestrator chain (Powerline class + Theme + Renderer base + segment dispatcher) in both powerline-render and powerline-daemon via the shared render_runtime::render_once entry — byte-identical output with upstream python3 powerline-render is asserted across 45 daemon-parity fixtures (tests/daemon_parity.rs) on top of the 462 unit-parity tests. Watch tags for milestone bumps.

Install

# source + build
git clone https://github.com/MenkeTechnologies/powerliners.git
cd powerliners
cargo build
ls target/debug/powerliners target/debug/powerline-{render,lint,config,daemon}

Five binaries land in target/debug/: powerliners (demo CLI for ported leaf utilities), powerline-render, powerline-lint, powerline-config, and powerline-daemon. The daemon lifecycle (UNIX socket bind, daemonize, pidfile lock, accept loop, EOF shutdown) is fully functional and the render path is wired end-to-end through render_runtime::render_once — same code path as powerline-render, with per-ext Configs caching and is_stale() mtime-reload (py:851-866). powerline-render / powerline-config shim through the ported scripts/ module mains and drive real theme JSON tree resolution; powerline-lint still has the markedjson loader + Spec checks behind the argparse, with the full orchestrator-integrated lint pipeline as the remaining substrate.

CLI reference

The suite ships five binaries. powerline is the hot-path client; the rest are management / fallback tools. All are 1:1 ports of the upstream scripts/ and client/ entry points.

powerline <EXT> — extensions

The first positional after the optional --socket PATH selects the extension to render. Stock extensions (from man powerline):

render-request flags

Everything after <EXT> is forwarded to the daemon and parsed by parse_client_argv (src/ported/scripts/powerline_daemon.rs). Each long flag has the upstream short alias:

powerline-daemon — process flags

powerline-config — subcommands

Environment variables

Per-UID socket path: /tmp/powerline-ipc-$UID on macOS / BSD, abstract \0powerline-ipc-$UID on Linux (no filesystem path — invisible to ls / fuser). Pidfile lock at /tmp/powerline-ipc-$UID.pid.

Shell & tmux integration

The wire format is byte-compatible with upstream's C client, so existing .tmux.conf / .zshrc invocations work unchanged once $POWERLINE_COMMAND resolves to this powerline binary.

tmux (~/.tmux.conf)

set -g status-interval 2
set -g status-left  "#(powerline tmux left)"
set -g status-right "#(powerline tmux right)"

# or the install-method-agnostic helper:
run-shell "powerline-config tmux setup"
run-shell -b "powerline-daemon -q &>/dev/null || exit 0"

zsh (~/.zshrc)

powerline-daemon -q   # start once at login
function powerline_precmd() {
    PS1="$(powerline shell left --last-exit-code=$? --jobnum=$(jobs -p | wc -l))"
}
precmd_functions+=(powerline_precmd)

verify against a config root

Point the daemon at a copy of your real config and confirm the rendered tmux markup matches upstream before swapping anything:

# spawn on a throwaway socket
POWERLINE_CONFIG_PATHS=~/.config/powerline \
  ./target/release/powerline-daemon --foreground --socket /tmp/powerliners-probe &

# render the right side via the wire protocol
powerline --socket /tmp/powerliners-probe tmux right

# compare against upstream Python (powerline-status installed)
powerline-render tmux right -p ~/.config/powerline

Custom segments

Upstream Python lets you drop a .py file in ~/.config/powerline/segments/ and reference it by dotted path; __import__ makes it callable. The Rust binary has no dynamic import, so the dispatch layer in src/extensions/exec_segment.rs provides two equivalent surfaces that fall through to a subprocess.

Pattern A — explicit exec adapter

Reference the built-in exec adapter directly in theme JSON when you want the script path, args, and format string spelled out inline:

{
  "function": "exec",
  "args": {
    "command": "/usr/local/bin/cpu_temp.sh",
    "args": ["--unit", "C"],
    "format": "%s°C",
    "highlight_groups": ["cpu_load"]
  }
}

Pattern B — dotted-path filesystem dispatch

Reference your segment by dotted path and drop the script under <config_path>/segments/. The daemon resolves myseg.cpu_temp → <config_path>/segments/myseg/cpu_temp.{sh,py,rb,pl,lua,js,executable} (first hit wins; order in src/extensions/exec_segment.rs::SCRIPT_EXTENSIONS):

{ "function": "myseg.cpu_temp" }

mkdir -p ~/.config/powerline/segments/myseg
cat > ~/.config/powerline/segments/myseg/cpu_temp.sh <<'EOF'
#!/bin/sh
echo "$(osx-cpu-temp | sed 's/°C//')"
EOF
chmod +x ~/.config/powerline/segments/myseg/cpu_temp.sh

Dotted-path resolution honors the full config-path cascade (POWERLINE_CONFIG_PATHS, --config-path, ~/.config/).

Output protocol

Both patterns parse the script's stdout on the first non-whitespace byte:

Highlight-group caveat (Rust-port divergence)

The current Rust gen_segment_getter (src/ported/segment.rs) uses the segment's function_name as the only highlight group for "type": "function" segments — it ignores the theme's "highlight_groups" override (upstream Python respects it). Practical fix: name your colorscheme group to match the function name ("exec" for Pattern A, "cpu_temp" for Pattern B), or emit explicit highlight_groups inline via a JSON-array stdout.

Migration & rollback

Drop-in replacement for the Python powerline-daemon — same wire format, same EOF\0\0 shutdown sentinel, same socket path. The C client shipped with powerline-status talks to this daemon unchanged.

The Python C client at ~/.local/bin/powerline does not need replacing — it speaks the same wire protocol to whichever daemon owns the socket. No config, .tmux.conf, or shell-rc edits.

Vim setup

Vim statusline + tabline rendering ships in the same powerline binary — no +python3 requirement, no pip install powerline-status. The bundled powerline.vim plugin is embedded via include_str! and extracted to ~/.cache/powerliners/vim/powerline.vim on first source. Works on vim 7.4+, vim 9, and neovim (vim8-compatible syntax only — no vim9script lock-in).

Step 1 — source the plugin from .vimrc

One-line install — extracts and sources the plugin on every launch:

if executable('powerline-config')
  execute 'source' trim(system('powerline-config vim source-path'))
endif

powerline-config vim source-path extracts the bundled plugin and prints its path; the :execute 'source' … then sources it. Caches in $XDG_CACHE_HOME/powerliners/vim/ (default ~/.cache/powerliners/vim/) so subsequent launches re-source from disk.

Or the manual two-step (pin the path, skip the per-launch fork):

# one-time extraction
$ powerline-config vim source-path
/Users/<you>/.cache/powerliners/vim/powerline.vim

" .vimrc
set runtimepath+=~/.cache/powerliners/vim
source ~/.cache/powerliners/vim/powerline.vim

Step 2 — pre-start the daemon

The plugin shells out via system('powerline vim left …') on every statusline refresh. With the daemon running that's a microsecond Unix-socket round-trip; without it every refresh fork-execs powerline-render (~30 ms cold per call). Start the daemon once at shell login (.zshrc / .bash_profile):

powerline-daemon -q

The -q flag double-forks and detaches; vim sees the socket immediately. No per-vim daemon — one process per UID handles tmux, shell prompts, and every running vim simultaneously.

Step 3 — verify

Open a fresh vim session and check:

:echo &statusline
" expected: a %#Pl_…# markup string ending in segment chunks

:PowerlinersRefresh
" manually re-runs the refresh; useful for debugging

:messages
" no errors; if 'powerline: write() to daemon failed' shows up,
" the daemon isn't reachable — re-run `powerline-daemon -q`

The plugin sets laststatus=2 automatically so the statusline shows even in single-window sessions.

What the plugin wires up

Triggered autocmds (augroup powerliners):

Per-request keys sent to the renderer (matches upstream's powerline.bindings.vim so theme JSON written for Python upstream renders identically): mode (mode(1)), bufnr (bufnr('%')), winnr (winnr()), buf_name (expand('%:p'), omitted when empty).

Override the binary name

If you've installed under a non-default name or want to test a build from target/release/, set the global before sourcing:

let g:powerliners_binary = expand('~/code/powerliners/target/release/powerline')
if executable(g:powerliners_binary)
  execute 'source' trim(system(g:powerliners_binary . '-config vim source-path'))
endif

Customize the theme

The vim statusline pulls from ~/.config/powerline/themes/vim/default.json plus ~/.config/powerline/colorschemes/vim/default.json. Bundled defaults live under src/ported/config_files/themes/vim/ and src/ported/config_files/colorschemes/vim/; copy any of them into ~/.config/powerline/ and edit. Same JSON shape as upstream — segments listed under segments.left / segments.right, inheritance via extends, per-mode highlight overrides via mode_translations.

Troubleshooting

Bundled segments

src/extensions/ ships net-new segments above upstream powerline-status, dispatched as standard built-ins via the daemon's ADAPTERS table. All accept a format theme arg and ship NF-default icons with Unicode + ASCII fallbacks (controlled by POWERLINERS_ICONS).

All segments live under src/extensions/<module>.rs and register through the daemon's ADAPTERS table in src/bin/shared/render_runtime.rs — see the audit section below for the live icon → segment cross-reference.

Cache-size segments — shared resolution chain & token surface

The four cache-size segments — powerliners.fusevm.jit_cache, powerliners.zshrs.rkyv_cache, powerliners.stryke.rkyv_cache, powerliners.awkrs.rkyv_cache — share a deliberately uniform contract so the same theme JSON works across all four. Each segment is a pure filesystem probe; no subprocess, no daemon RPC.

Resolution chain (4-level fallback, first hit wins). For <NAME> ∈ {ZSHRS, STRYKE, AWKRS} the rkyv segments resolve path as:

1. $<NAME>_RKYV_CACHE — explicit override, used verbatim
2. $<NAME>_HOME/scripts.rkyv
3. $XDG_DATA_HOME/<name>/scripts.rkyv — used only when the file exists; otherwise falls through
4. ~/.<name>/scripts.rkyv — final fallback

The fusevm.jit_cache sibling uses the directly-analogous 3-level chain ($FUSEVM_JIT_CACHE → $XDG_CACHE_HOME/fusevm-jit → ~/.cache/fusevm-jit) but recursively walks a cache directory rather than stat-ing a single archive, and also exposes an {entries} token for the recursive file count. Symlinks count as a single entry and are never followed — avoids infinite loops across re-symlinked cache dirs. The precedence chains are unit-tested via a pure-functional default_path_with(get_env, path_exists) seam in src/extensions/{zshrs,stryke,awkrs}_rkyv.rs and a matching default_root_with(get_env) seam in src/extensions/fusevm_jit.rs — every precedence level pinned without mutating the process env.

Format tokens (identical across all four segments):

Missing-archive behavior. When the target file doesn't exist (the runtime never ran on this machine, or the archive hasn't been written yet), the segment returns None by default and renders no chunk. Setting "show_when_empty": true in the segment args makes it render with zeroed stats (0B/0) so the chunk stays present as a UI affordance.

Highlight-group chain. Every cache-size segment ships a 3-level highlight chain — <segment>_rkyv_cache → <segment> → information:regular. The trailing information:regular is a neutral fallback so the chunk renders in any colorscheme even when the segment-specific groups are absent (see fusevm_jit::jit_cache() for the rationale that motivated this convention).

Glyph rendering

Every glyph below is a real Nerd Font codepoint loaded into this page via the @font-face block in docs/hud-static.css. The font is the official SymbolsNerdFont subset (~270 KB) served from jsdelivr CDN, with a unicode-range directive gating the load to PUA ranges only (U+E000-F8FF + U+F0000-FFFFD):

@font-face {
  font-family: 'SymbolsNerdFont';
  font-display: swap;
  src: url('https://cdn.jsdelivr.net/gh/ryanoasis/nerd-fonts@master/patched-fonts/NerdFontsSymbolsOnly/SymbolsNerdFont-Regular.ttf') format('truetype');
  unicode-range: U+E000-F8FF, U+F0000-FFFFD;
}

Body text and code blocks continue to render in Share Tech Mono / Orbitron — only PUA codepoints resolve through the NF subset, so the font swap has no layout impact. The same chain operates at runtime via POWERLINERS_ICONS: unset/default → NF glyph, =unicode → text-presentation Unicode fallback (e.g. ✓ ✗ 🐳 ⎈ ⛁), =ascii → label-style ASCII (e.g. OK FAIL D: k8s: D:).