https://github.com/egorlem/veil.zsh
Modular Zsh (Z Shell) Configuration System. No magic, just clarity.
https://github.com/egorlem/veil.zsh
shell zsh zsh-configuration zsh-plugins zshell zshrc
Last synced: about 1 month ago
JSON representation
Modular Zsh (Z Shell) Configuration System. No magic, just clarity.
- Host: GitHub
- URL: https://github.com/egorlem/veil.zsh
- Owner: egorlem
- License: wtfpl
- Created: 2025-11-20T10:14:18.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T08:31:04.000Z (2 months ago)
- Last Synced: 2026-04-10T10:33:51.741Z (2 months ago)
- Topics: shell, zsh, zsh-configuration, zsh-plugins, zshell, zshrc
- Language: Shell
- Homepage:
- Size: 157 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Veil [veɪl] — Modular Zsh Configuration System
**Full control. No magic. Just clarity.**
Veil is **not** a plugin manager. It does not pull external tools or hide behavior behind layers of magic. Everything it does is explicit, local, and under your control.
---
## What’s Inside?
Veil breaks your `.zshrc` into **independent modules**, each a plain `.zsh` file that can be **read, modified, or disabled independently**.
Out of the box, it provides a ready-to-use Zsh environment for **everyday terminal work**, with sensible defaults for history, completion, navigation, aliases, keybindings, and common tools. The included **Ultima** theme shows VCS state, SSH connections, and command status in a clean, unobtrusive prompt.
---
## Quick Start
```shell
# Clone Veil repository
git clone https://github.com/egorlem/veil.zsh "$HOME/.zsh/veil"
# Source Veil in your .zshrc (includes Ultima theme)
echo 'source "$HOME/.zsh/veil/veil.zsh"' >> "${ZDOTDIR:-$HOME}/.zshrc"
```
Included by default:
* Core module loader
* Modules: `less`, `ls`, `completion`, `history`, `navigation`
* [Ultima](https://github.com/egorlem/ultima.zsh-theme) minimalist theme
> For detailed module configuration, see [Tier 2 Documentation](./components/README.md)
---
## Why Veil?
Traditional `.zshrc` files often grow into tangled, hard-to-manage scripts. Changing one part can break another, and debugging becomes slow and frustrating.
Veil’s modular design solves this problem: each module is **self-contained**, with its own functions and rules. This makes your shell **predictable, transparent, and fully under your control**.
Modules and themes are organized in simple folders for clarity:
```
~/.veil/components/modules
├── completion.module.zsh
├── history.module.zsh
└── ...
~/.veil/components/themes
├── ultima.zsh-theme
└── ...
```
If you prefer plugins that just work without showing how they work, Veil may not be the right fit — it’s meant for users who value **visibility and control** over magic.
---
## Performance
Performance was measured with **all 9 modules + Ultima theme**, including **`zsh-users/zsh-autosuggestions`** and **`zsh-users/zsh-syntax-highlighting`**, using [**zimfw/zsh-framework-benchmark**](https://github.com/zimfw/zsh-framework-benchmark) as the test tool.
| Framework / Config | Real | User | Sys | Max |
| ------------------------------ | ----- | ----- | ----- | -------- |
| ZimFW (all included) | 0.075 | 0.003 | 0.071 | 0.107 |
| **Veil (9 modules + Ultima)** | 0.083 | 0.003 | 0.079 | 0.107 |
| zplug | 0.230 | 0.008 | 0.218 | 0.274 |
| Oh My Zsh | 0.351 | 0.005 | 0.344 | 0.378 |
Veil remains efficient and responsive, even with multiple modules loaded, and adding more modules may slow it down slightly — but performance stays within reasonable bounds.
---
## Documentation Tiers
Veil documentation follows **progressive disclosure**.
- **Tier 1 (You are here)** — Quick start, core concepts, essentials.
- [**Tier 2** — Advanced configuration and integration.](./components/README.md)
- [**Tier 3** — Core modules and system internals.](./components/modules/README.md)
Start here to learn the basics of Veil. Understand core concepts and essential workflows. Move to Tier 2 only when you are ready to configure and personalize your setup.
---
## Philosophy
### Script as Application
Veil treats each configuration module as a **small standalone program**, solving the issues that come with large, tangled `.zshrc` files. Each module handles one part of your shell clearly and predictably, with a **single responsibility**, a **clear entry point**, and its **own functions and internal rules**.
This design allows every module to be **read, reasoned about, and maintained in isolation**, and explains why **all of Veil, including its theme,** is structured like **self-contained programs** instead of typical shell scripts.
---
## License
**Do What The F*ck You Want To Public License, Version 2**
See [LICENSE](https://github.com/egorlem/veil.zsh/blob/main/LICENSE) for details.
Maintained by [Egor Lem](https://egorlem.com/)