A fast, modular Zsh configuration framework. Layer 0 bootstrap → Layer 3 plugin runtime.
ziro-shell manages your Zsh config as a layered framework instead of a
monolithic .zshrc. Each layer has one responsibility and a strict performance
budget. The hot path — sourced on every shell start — targets < 5ms
(Layer 0 bootstrap target).
~/.zshrc ← entrypoint (sources integration.zsh)
~/.ziro/integration.zsh ← Layer 0: bootstrap
~/.ziro/lib/ ← shared helpers
~/.ziro/commands/ ← Zsh CLI command modules
~/.ziro/core/ ← Python core (cold-path only)
~/.ziro/vendor/ ← vendored runtimes (znap, ziro-defer)
~/.ziro/prompts/ ← prompt themes
~/.ziro/themes/ ← color schemes
| Layer | Responsibility | Location |
|---|---|---|
| 0 | Shell bootstrap | integration.zsh |
| 1 | Config parsing & plugin analysis | Python core (core/) |
| 2 | Plugin resolution & generation | Python core → plugins.gen.zsh |
| 3 | Plugin runtime | vendor/znap/ |
The full layer model and the reasoning behind the Python/Zsh split are recorded in ADR-003.
Ziro does not write its own plugin manager. It builds on two proven projects:
- znap — the permanent runtime backend. Installed at
~/.ziro/znap/, exposed atvendor/znap/znap.zshvia a symlink. - ziro-defer — a fork of upstream
zsh-deferwith additional features. Ziro's canonical deferral engine.
The deferral fallback chain in integration.zsh (ADR-002 / ADR-004):
ziro-defer.plugin.zsh → zsh-defer.plugin.zsh → zsh-defer command → eager stub
See ADR-002 for the
benchmark (command_lag 0.04ms for znap + zsh-defer vs 17.2ms for zinit
turbo) and the decision record.
Requirements: Zsh ≥ 5.8, git. Python is optional — only needed for the plugin analyzer and Rich progress bars (ADR-003).
git clone https://github.com/<user>/ziro-shell.git ~/.ziro
ln -sf ~/.ziro/.zshrc ~/.zshrc # or source it from your existing ~/.zshrcThen start a new shell. Ziro is idempotent — the (( ${+ZIRO_LOADED} )) guard
makes re-sourcing safe.
- Hot path (
integration.zsh): sourced every shell start. No Python, no subprocess, no network. Stays under the 5ms budget. - Cold path (
core/Python core): heavy analysis, tag resolution, file generation. Invoked via subprocess only when needed. - CLI (
commands/,lib/,ziro.zsh): always available, sourceable standalone, minimal overhead. - Generated files (
*.gen.zsh): machine-written, never hand-edited.
Official architecture decisions are recorded in docs/wiki/sources/ as ADRs:
| ADR | Topic |
|---|---|
| ADR-002 | znap permanent backend + ziro-defer |
| ADR-003 | Two-layer Python/Zsh architecture |
| ADR-004 | ziro-defer fork timing |
| ADR-005 | ziro-defer directory placement |
| ADR-006 | Ghost architecture decisions |
| ADR-007 | Versioning policy & release tier discipline |
| ADR-008 | Roadmap phases 7-9 & per-plugin repositories |
MIT