Puckadots Terminal
Universal dotfiles framework, Starship prompt architecture, and sub-second fleet orchestration engineered for seamless synergy between human operators and autonomous AI agents.
In modern homelab and hybrid-cloud infrastructure, shell friction is a compounding tax. Traditional multi-machine management suffers from fragmented packages, incompatible .bashrc snippets, missing PATHs during non-interactive SSH sessions, and inconsistent command aliases that break automation scripts.
Puckadots v6.1 establishes an immutable baseline across every device in the clusterโfrom flagship multi-GPU desktop workstations and high-core Proxmox hypervisors down to edge IoT sensors and storage appliances. Every terminal session offers identical keybindings, instantaneous fuzzy history search, and standardized telemetry.
All public dotfiles, Zsh plugins, shell scripts, and fleet orchestration logic live in a unified repository with sub-second parallel deployment.
Headless AI subagent invocations (ssh host cmd) automatically load user binaries, PATHs, and guarded tool helpers without interactive TTY dependencies.
Password authentication is disabled network-wide. Hosts authenticate strictly via Ed25519/RSA public keys with Vaultwarden encrypted sync.
Deep fzf, ripgrep, and zoxide integrations allow sub-second jump-to-line editing and millisecond history recall.
Experience the live Puckadots terminal environment below. Powered by Zsh, Starship, and FiraCode Nerd Font Mono, this interactive emulator demonstrates our unified shell architecture: the Starship powerline prompt, the complete dothelp command index, parallel multi-host fleet telemetry via puckafleet, and agent safety tooling.
fleet status, fleet maintain, and fleet dotpull execute concurrently across our distributed nodes using pooled worker threads over zero-password Tailscale SSH. Both human administrators and autonomous AI agents invoke the exact same tooling with identical PATHs, sub-second latency, and zero configuration drift.
The prompt is the engineer's primary feedback loop. Puckadots standardizes on the cross-shell Starship prompt engine, configured with custom powerline color tokens directly harmonized with our web design system.
Tokenized Color Anatomy
Powerline segments seamlessly transition from deep forest obsidian through dark spruce and eucalyptus jade:
Anchors the left rounded powerline cap, host identity, and OS distribution glyphs (Debian, Arch, Ubuntu, Alpine).
Houses the intelligent directory breadcrumb, applying surgical Nerd Font icons to standard development and dotfile paths.
Real-time Git tracking with branch name, ahead/behind counters (โก1 / โฃ2), and staging status indicators.
Language runtimes (Python, Rust, Node, Go) and automatic execution duration benchmarking for commands taking longer than 2s.
Intelligent Directory Substitutions
Rather than wasting prompt width with repetitive paths, Starship automatically condenses frequent homelab paths into single Nerd Font glyphs:
[directory.substitutions]
"~/dotfiles" = "๎ " # nf-custom-folder
"~/Notes" = "๓ฐ ฎ " # nf-md-notebook
"~/Projects" = "๓ฐฒ " # nf-md-tools
"/opt/stacks" = "๏ " # nf-md-layers
"~" = "๏ญ " # nf-oct-home
Manual directory crawling and typing full paths are anti-patterns. Puckadots wires fzf, ripgrep, bat, and zoxide into an integrated fuzzy navigation matrix.
Ctrl+R (History) • Alt+C (Directory) • Ctrl+T (Files)bat code syntax coloring • eza --tree directory structure previewmicro • cd to folder • Paste token at cursor
Live searches text inside files with syntax preview. Selecting a result opens micro jumped directly to that exact line number.
Powered by Zoxide. Type j dots or j notes to warp directly to frequently accessed project folders without typing full paths.
Full-screen fuzzy history recall across up to 1,000,000 commands with timestamps. Arrow keys filter past commands instantly.
Blazing fast terminal file manager with image previews. Quitting Yazi (y) automatically cds your shell to the highlighted folder.
Managing 12 individual nodes via manual, sequential SSH loops is slow and prone to errors. Puckadots introduces the fleet (or puckafleet) CLI, executing high-concurrency operations across defined infrastructure tiers over Tailscale SSH.
# Instant parallel cluster telemetry across target tier
fleet status [all|core|pve|stacks|workstations|edge]
# Concurrent package upgrades & dotfiles reload
fleet maintain all
# Sub-second parallel dotfiles git pull across all nodes
fleet dotpull all
# Audit and verify Antigravity CLI version parity on agent nodes
fleet ag-sync [--upgrade]
# Run arbitrary bash command concurrently across cluster tier
fleet exec core -- "uptime && uname -r"Modern homelabs are co-piloted by autonomous AI agents (such as Google Antigravity and Tess). While agents excel at rapid execution, standard Linux shells present distinct failure modes: unbounded file scans saturate context windows, live SQLite queries cause write-lock deadlocks, and headless SSH sessions fail to load binary paths.
Puckadots explicitly bridges this gap with dedicated Agent Safety Guards baked into the shell:
Executes queries with PRAGMA query_only = ON;. Guarantees zero write-lock hangs or database corruption on live production databases (Home Assistant, Jellyfin).
Pipes configurations directly through atomic temporary file swaps, eliminating syntax truncation, quote escaping bugs, and shell variable expansion errors.
Safety wrappers around rg and fd that automatically exclude heavy caches (node_modules, .venv, .cache) and enforce max-depth limits to prevent memory exhaustion.
Configured via zshenv.conf so headless subagents (ssh host <cmd>) immediately inherit ~/.local/bin, ~/.cargo/bin, and core environment variables.
Every single Puckanet node is automatically provisioned and maintained with this verified tooling matrix via sync.sh:
| Tool Name | Binary / Alias | Architecture Purpose | Operational Advantage |
|---|---|---|---|
| Zsh + Zinit | zsh |
Interactive shell & plugin loader | Asynchronous plugin loading with zero startup latency |
| Starship | starship |
Cross-shell contextual prompt engine | Puckanet forest theme with Nerd Font powerline glyphs |
| Ripgrep | rg, rgf |
High-speed code & content search | Guarded wrappers auto-exclude heavy venvs & node_modules |
| fd-find | fd, fdf |
High-speed directory & file search | Replaces slow recursive find; auto-symlinked on Debian |
| FZF | fzf, fzf-tab |
Command-line fuzzy finding | Intercepts tab completion for pop-up process & branch menus |
| Bat | bat |
Syntax-highlighted file viewing | Git modification markers & automatic terminal paging |
| Eza | ll, la, lt |
Modern ls replacement |
Color-coded file types, permissions, icons, and tree views |
| Zoxide | z, j, cd |
Smart frecency directory navigation | Jump to deepest nested project paths with single keyword |
| Tmux | tmux |
Persistent terminal multiplexer | Session persistence across intermittent mobile connections |
| Micro | micro |
Intuitive CLI text editor | Full mouse support, standard Ctrl+C/V/S keybindings |
| SQLite3 & sq | sq |
Read-only database telemetry | Guaranteed query_only=ON preventing database lockouts |
| jq | jq |
Command-line JSON processor | Zero-dependency JSON slicing for CLI APIs and metrics |
Convenience without security is technical debt. Puckadots strictly enforces an uncompromising cryptographic defense-in-depth posture:
sshd_config) enforce PasswordAuthentication no and KbdInteractiveAuthentication no. Attempting a password login results in instant connection termination.
Host and user authentication relies purely on modern 256-bit elliptic curve Ed25519 public keys distributed via automated dotfiles synchronization.
Sensitive environment variables (.env) and deployment credentials are encrypted and synchronized via self-hosted Vaultwarden with audit logging.
Private node variables (such as GPU device mappings or token exports) reside in ~/.zshrc.local, which is sourced last and strictly ignored by git.