The Aporia Philosophy

Aporia isn't just a prompt — it's a context-aware environment. It adapts to your project, your privileges, and your operating system, staying out of the way when you're busy and surfacing detail the moment you need it. Every segment that touches the network or the filesystem runs asynchronously, so the prompt never blocks on a slow git status or a cold cloud CLI.

Core Features

• Asynchronous Prompt Engine: Git status, language versions, and plugin segments all resolve in background workers (zle -F) — the prompt renders instantly and fills in as data arrives.
• Theme Presets: Switch between deep_blue, light, amber, crimson_void, and forest_matrix with aporia theme <name>.
• Adaptive Icons: Four icon tiers — Nerd Font, Font Awesome, standard Unicode, and plain ASCII — so the prompt still looks intentional even without a patched font.
• Adaptive Branding: Distro-aware OS icons for macOS, Debian, Ubuntu, Arch, Fedora, and 40+ others.
• Polyglot Awareness: Real-time project detection for Go, Rust, Python, Node, Ruby, PHP, Java, and C++, shown only when you're actually inside a matching project.
• Context Intelligence: Dedicated segments for Docker, Kubernetes, AWS/GCP/Azure identity, VPN state, and operational target tracking.
• Aporia Essentials: Built-in support for ghost-text autosuggestions and live syntax highlighting out of the box.

Compatibility

Aporia targets native performance on any Unix-like system:

• macOS: Native support via Homebrew or the standard installer.
• Linux: Debian, Ubuntu, Arch, Fedora, Alpine, and most other distributions.
• Windows: Supported via WSL2 (install the Nerd Font on the Windows host, not just inside WSL).
• Bash users: The installer adds a lightweight bash → zsh bridge to both ~/.bashrc and ~/.profile, so a bash login shell hands off to your themed zsh automatically — no manual chsh required (though chsh -s $(which zsh) is still offered).

Requirements:

• Zsh: version 5.3 or newer (5.8+ recommended for higher-precision command timing).
• Font: A Nerd Font (e.g. JetBrainsMono, Hack) for full-fidelity icons. Not strictly required — see Troubleshooting for fallback modes.

Installation

1-Click Install (Universal)

The fastest way to get started on any system. The installer handles dependencies, configures your shell, offers to install a Nerd Font, and reloads your terminal automatically:

curl -fsSL https://raw.githubusercontent.com/fr3on/aporia/main/install.sh | zsh

Homebrew (macOS)

brew tap fr3on/aporia https://github.com/fr3on/aporia
brew install aporia
aporia-setup

aporia-setup adds the source line to your .zshrc for you — safe to re-run, it skips itself if already configured.

Plugin Managers

Manager	Configuration
Oh My Zsh	git clone https://github.com/fr3on/aporia $ZSH_CUSTOM/themes/aporia Set ZSH_THEME="aporia/aporia" in .zshrc
Zinit	zinit ice pick"aporia.zsh-theme"; zinit light fr3on/aporia
Antigen	antigen theme fr3on/aporia
Zplug	zplug "fr3on/aporia", as:theme

The Aporia CLI

Aporia ships a built-in management command, aporia, for everything below. Run aporia help any time for the full list.

Command	Description
aporia info	Show the status dashboard: OS, icon tier, active theme, segment toggles, plugin count. Default when run with no arguments.
aporia theme <name>	Switch color preset (deep_blue, light, amber, crimson_void, forest_matrix).
aporia icons <set>	Switch icon tier (nerd, font_awesome, unicode, ascii) and persist it to .zshrc. Offers to install a Nerd Font if none is detected.
aporia fonts install	Download and install JetBrainsMono Nerd Font directly (no need to re-run the full installer).
aporia doctor	Run health checks: Zsh version, locale, git availability, icon mode.
aporia benchmark	Profile the git segment, language segment, and render pass — useful when the prompt feels slow.
aporia inspect	Dump raw segment data for debugging.
aporia list	Show every registered plugin and its status (active / installed / not installed).
aporia upgrade	Update Aporia in place (detects Homebrew, git checkout, or manual install) and reports the version change.

Plugin System

Aporia ships 23 plugins, all opt-in via the AP_PLUGINS array so a fresh install stays minimal. Two — zsh-autosuggestions and zsh-syntax-highlighting — are treated as essentials and installed automatically.

Highlights

Plugin	Description	Category
docker-ctx	Docker context in the prompt, read from config — no subprocess	Context
kube-ctx	kubectl context:namespace, parsed from kubeconfig directly	Context
aws-profile	Active AWS profile and region, colored red for prod-like profiles	Context
gh-context	GitHub CLI identity, cached per session	Context
vpn-status	Detects Tailscale, Mullvad, or a generic tun/wg tunnel	Context
telemetry	CPU/RAM load, shown only above a configurable threshold	Context
target	Pins an operational IP/host in the prompt to prevent command leakage	Context
sudo	Warns when a shell has elevated privileges	Productivity
fzf-tab	Replaces the tab-completion menu with fzf	Utility
fast-syntax-highlighting	Drop-in FSH replacement, faster and themeable	Essential

See PLUGINS.md for the remaining cloud (azure-ctx, gcp-ctx), environment (autoswitch-venv, nix-shell), search (history-substring-search, fzf-history), and interaction (forgit, autopair, you-should-use) plugins.

Management Commands

• aporia install <p>: Downloads a third-party plugin.
• aporia activate <p>: Enables a plugin and saves it to ~/.zshrc.
• aporia deactivate <p>: Disables a plugin and removes it from ~/.zshrc.
• aporia activate-all: Activates every installed-but-inactive plugin at once.
• aporia update: Pulls the latest changes for all installed plugins.

Configuration

Set these in your ~/.zshrc before the line that sources the theme:

Variable	Default	Description
AP_THEME	deep_blue	Color preset: deep_blue, light, amber, crimson_void, forest_matrix
AP_ICON_STYLE	nerd	Icon tier: nerd, font_awesome
AP_USE_NERD_FONT	1	Set to 0 to use the standard Unicode tier instead of Nerd Font glyphs
AP_ASCII_FALLBACK	0	Set to 1 to force plain ASCII (no special font or Unicode needed)
AP_SHOW_SSH	1	Show SSH context (user@host) when connected remotely
AP_SHOW_GIT	1	Show git branch, dirty state, and ahead/behind counts
AP_SHOW_LANGS	1	Show language versions, only inside matching projects
AP_SHOW_EXEC_TIME	0	Show the last command's execution time
AP_EXEC_TIME_THRESHOLD	0	Minimum duration (seconds) before execution time is shown; 0 shows it for every command
AP_SHOW_EXIT_CODE	1	Show non-zero exit codes
AP_SHOW_TIME	1	Show the right-side clock
AP_DIR_DEPTH	3	Number of path segments to show in the directory indicator

Prefer aporia theme <name> and aporia icons <set> over hand-editing AP_THEME/AP_ICON_STYLE directly — the CLI commands persist the change to .zshrc for you and validate the input.

Troubleshooting

License

MIT © Ahmed Mardi (fr3on)