+--------------------------------------------------------------------------------------------------+
|                              *  ~  *  FORGUM JUNGLE ENGINE  *  ~  *                              |
+==================================================================================================+
|        / \  //\                                                                                  |
| |\___/|/  \//  \\   ███████╗ ██████╗ ██████╗  ██████╗ ██╗   ██╗███╗   ███╗  \   ^__^             |
| /O   O \_ / // | \  ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██║   ██║████╗ ████║   \  (oo)\_______     |
| \@_^_@'/ \/_// |  \ █████╗  ██║   ██║██████╔╝██║  ███╗██║   ██║██╔████╔██║      (__)\       )\/\ |
|  //_^_/  \///  |  ) ██╔══╝  ██║   ██║██╔══██╗██║   ██║██║   ██║██║╚██╔╝██║          ||----w |    |
|( //) |    //   | /  ██║     ╚██████╔╝██║  ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║          ||     ||    |
|                     ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝                       |
|                * * *  K I N E M A T I C   J U N G L E   M E N A G E R I E  * * *                 |
|                          ___                                     .___.                           |
|                          {~o.o~} ( ( (   A N I M A T E D   ) ) ) {o,o}                           |
|                         ( Y )  ) ) )      P A S T U R E     ( ( ( /)__)                          |
|                          ()~*~() ( ( (      M O T I O N      ) ) )  ""                           |
+==================================================================================================+
|       [Dragon: Ember]          [Koala: Zen]          [Toucan: Sky]         [Cow: Pasture]        |
+--------------------------------------------------------------------------------------------------+

Forgum is a high-performance Rust terminal animation engine that renders living ANSI creatures in your terminal — featuring physical 2D kinematics (stride-coupled ground traversal, flight swoops, Lissajous drift), 15 preloaded themes, zero-alloc dirty-damage rasterization, fail-safe signal/input handling, shell hooks, daemons, and capability probes. Cross-platform on Windows, macOS, and Linux.

Repo: HKDevLoops/Forgum · Version: 0.0.3 beta · License: MIT

---

✨ The Modern cowsay Alternative for Your Terminal

Keywords: cowsay alternative · terminal animation · shell animations · ASCII art mascots · lolcat replacement · ponysay alternative · terminal eye candy · ascii animation · fortune quotes · rust cli · ricing · dotfiles · shell prompt · tui · terminal customization

Forgum is the modern, Rust-powered successor to classic terminal toys like cowsay, ponysay, lolcat, fortune, figlet, nyancat, asciiquarium, and cmatrix. Instead of static ASCII cows or rainbow pipes, Forgum renders physically animated mascots — creatures that genuinely walk, fly, drift, and rest across procedural terminal landscapes, with real kinematics, 24-bit TrueColor color gradients, and particle effects.

Whether you're looking for a cowsay alternative, a lolcat replacement, a shell animation tool to beautify your terminal startup, or just want some terminal eye candy and ricing flair, Forgum delivers it all in a single, zero-dependency binary.

🆚 Forgum vs. Classic Terminal Tools

Feature	Forgum 🦁	cowsay 🐮	ponysay 🐴	lolcat 🌈	fortune 🔮	figlet/toilet 🔤	cmatrix 🟩	asciiquarium 🐠
Language	Rust	Perl	Python	Ruby/C	C	C	C	Perl
True physical animation	✅ Walk, fly, float	❌ Static	❌ Static	❌ N/A	❌ N/A	❌ Static	⚠️ Loop only	⚠️ Loop only
Procedural scenery	✅ Mountains, roads, sky	❌	❌	❌	❌	❌	❌	❌
24-bit TrueColor	✅ HSV manifold	❌	❌	✅	❌	⚠️ Basic	⚠️ Basic	❌
Particle effects (fire, bubbles, stars)	✅	❌	❌	❌	❌	❌	❌	⚠️ Fish only
Fortune quotes built-in	✅	❌	❌	❌	✅	❌	❌	❌
Shell hook (startup animation)	✅ 15 shells	❌	❌	❌	❌	❌	❌	❌
Interactive TUI config	✅	❌	❌	❌	❌	❌	❌	❌
Cross-platform (Win/Mac/Linux)	✅	❌ Win only fork	❌	⚠️	✅	⚠️	❌	❌
Memory footprint	< 10 MB	< 1 MB	< 50 MB	< 5 MB	< 1 MB	< 1 MB	< 5 MB	< 5 MB
Single binary install	✅	❌ Needs Perl	❌ Needs Python	❌	❌	❌	❌ Needs ncurses	❌ Needs Perl
Stride-velocity coupling	✅ Physics math	❌	❌	❌	❌	❌	❌	❌
mascot count	130+ animals	~50 cows	~400 ponies	—	—	—	—	~10 aquatic
pkg managers	scoop/winget/choco/brew/yay/apt/dnf/zypper/nix/cargo	apt/brew	apt/brew	apt/brew	apt/brew	apt/brew	apt	cpan

Also compared with: sl (steam locomotive), toilet, xcowsay, dinosay, charasay, pokemonsay, ferris-says, nyancat, pipes.sh, cbonsai

---

📑 Table of Contents

• 🚀 Installation & Quickstart
  • 📦 1-Command Quick Install
  • 🌐 Multi-Channel Package Managers
  • 🩺 Maintenance & Doctor
  • 🌌 Clean Uninstallation (Soft vs. Purge)
• 📖 The Story Behind Forgum: From Static Mascots to Kinetic Art
  • 🌿 Modernizing Terminal Mascots with Thoughtful Engineering
• 🚀 Quickstart (3 commands)
• 🎪 The Forgum Farm — A Tour in Animal Voices
• 📊 Complete CLI Command & Argument Reference
  • 1. Subcommands Reference Table
  • 2. Primary Render & Simulation Flags
  • 3. Procedural Mountain Styles
  • 4. Procedural Road Styles
  • 5. Mascot Kinematic Taxonomy
  • 6. Expressions & Mood Modifiers
  • 7. Color Modes & Palette Engine
  • 8. Configuration Schema Reference
  • 9. Multi-Platform & Hardware Compatibility
• 🧮 Under The Hood: Kinematics & Nature Mathematics
• 🐚 Shell Integration & Ecosystem
  • ⚡ One-Command Automatic Setup
  • 📋 Universal 15-Shell Reference Table
  • 🌟 Awesome-Shell & Multiplexer Matrix
• 🖥️ Terminal Compatibility
• 🩺 Check Your Pasture's Health (checkhealth)
• ⚙️ Config File Location & Multi-Format Support
• 🪵 Structured Logs & Diagnostics
• ✨ Forgum Configurator (Interactive TUI)
• 🎨 Preloaded Themes & Kinematic Motion
• 🍀 Fortune
• 📚 Further Reading
• 📜 License

---

🚀 Installation & Quickstart

Forgum features a celestial, Omarchy and Celestial Shell-inspired Terminal UI Wizard with rich TrueColor ASCII art, automatic shell detection, and transparent privacy permission controls.

  ✦ CELESTIAL INSTALLER ✦   [1] Welcome  ── [2] Privacy  ── [3] Shells  ── [4] Install  ── [5] Blastoff
  ╭───────────────────────────────╮
  │    ✦  F O R G U M   O S  ✦    │   Detects: PowerShell 7, Pwsh, Bash, Zsh, Fish, Nushell
  ╰───────────────────────────────╯   Zero Surveillance · Transparent Consent · 100% Offline

📦 1-Command Quick Install

Windows (PowerShell 5.1 / PowerShell 7+):

# Interactive Celestial TUI Wizard:
irm https://raw.githubusercontent.com/HKDevLoops/Forgum/dev/install.ps1 | iex

# Or run locally from clone:
./install.ps1

macOS & Linux (Bash / Zsh / Fish):

# Interactive Celestial TUI Wizard:
curl -4 -fsSL --connect-timeout 5 https://raw.githubusercontent.com/HKDevLoops/Forgum/dev/install.sh | bash

# Or run locally from clone:
./install.sh

🛡 Headless & Offline Install:

Prefer zero interactive UI and zero telemetry? Install headlessly with telemetry declined:

./install.ps1 -Headless -Telemetry decline

./install.sh --headless --telemetry decline

Note

Motivation & Curiosity Telemetry Notice: Forgum collects ONLY three aggregate community counters (users_tried, users_installed, active_users) purely for developer motivation. Zero surveillance, zero IP logging, zero personal data. Read our full commitment in docs/TELEMETRY.md.

🌐 Multi-Channel Package Managers

Forgum is packaged and distributed across every major operating system, architecture, and package manager:

OS	Package Manager	Installation Command	Update Command
Windows	Scoop	scoop bucket add hkdevloops https://github.com/HKDevLoops/scoop-bucket; scoop install forgum	scoop update forgum
Windows	WinGet	winget install HKDevLoops.Forgum	winget upgrade HKDevLoops.Forgum
Windows	Chocolatey	choco install forgum -y	choco upgrade forgum -y
macOS & Linux	Homebrew	brew install hkdevloops/tap/forgum	brew upgrade forgum
Arch Linux	AUR (yay / paru)	yay -S forgum or paru -S forgum	yay -Syu
Debian / Ubuntu	APT / dpkg	sudo dpkg -i forgum-*.deb	sudo apt install --only-upgrade forgum
Fedora / RHEL	DNF / RPM	sudo rpm -ivh forgum-*.rpm	sudo dnf upgrade forgum
openSUSE	Zypper	sudo zypper install forgum-*.rpm	sudo zypper update forgum
Nix / NixOS	Nix Profile	nix profile install github:HKDevLoops/Forgum	nix profile upgrade forgum
Alpine Linux	APK	apk add forgum	apk upgrade forgum
Void Linux	XBPS	xbps-install -S forgum	xbps-install -Su forgum
FreeBSD	pkg	pkg install forgum	pkg upgrade forgum
macOS	MacPorts	sudo port install forgum	sudo port upgrade forgum
Universal	Cargo (Rust)	cargo install --path crates/engine --bin forgum	cargo install --force --path crates/engine --bin forgum

Tip

Universal Shell Integration & Completions: For automated prompt hooks, tab completion scripts, and multiplexer setup across all 15 supported shells, see 🐚 Shell Integration & Ecosystem.

---

🩺 Maintenance & Doctor

Keep Forgum healthy, updated, and diagnosed with built-in commands:

# Check for updates across your detected package manager:
forgum update --check

# Upgrade Forgum using your native package manager:
forgum update

# Run comprehensive system, shell, and package manager diagnostic health check:
forgum checkhealth

# View, query, and diagnose structured engine logs:
forgum logs --diagnose

---

🌌 Clean Uninstallation (Soft vs. Purge)

Forgum guarantees total respect for your system with two distinct, user-directed uninstallation methods:

                          ┌───────────────────────────┐
                          │   forgum uninstall / TUI  │
                          └─────────────┬─────────────┘
                                        │
                    ┌───────────────────┴───────────────────┐
                    ▼                                       ▼
        ┌───────────────────────┐               ┌───────────────────────┐
        │ [1] Soft Uninstall    │               │ [2] Purge Uninstall   │
        │  (Keep Configuration) │               │   (Clean Slate)       │
        └───────────┬───────────┘               └───────────┬───────────┘
                    │                                       │
        • Remove binary from PATH               • Remove binary from PATH
        • Strip shell prompt hooks              • Strip shell prompt hooks
        • Strip shell completions               • Strip shell completions
        • Delete completions folder             • Delete completions folder
        • PRESERVE ~/.config/forgum/            • DELETE ~/.config/forgum/
        • PRESERVE custom .cow files            • DELETE all logs & cache
        • PRESERVE user preferences             • DELETE state & daemon sockets

Method 1: Soft Uninstall (Keep Configuration)

Removes the binary from disk and User PATH, strips prompt hooks and completions from all shell profiles, but PRESERVES ~/.config/forgum/ (configuration, custom mascots, themes) so your customizations remain intact if you reinstall later:

forgum uninstall --method soft
# or using standalone script:
./uninstall.sh --method soft

./uninstall.ps1 -Method Soft

Method 2: Purge Uninstall (Clean Slate)

Completely wipes everything. Leaves zero traces on your system:

forgum uninstall --method purge --yes
# or using standalone script:
./uninstall.sh --method purge --yes

./uninstall.ps1 -Method Purge -Yes

💫 Interactive Celestial De-Orbit Wizard:

Launch the interactive terminal UI with supernova ASCII art to review removals before executing:

forgum uninstall --tui

./uninstall.ps1 -Tui

---

📖 The Story Behind Forgum: From Static Mascots to Kinetic Art

In 1999, the terminal world welcomed cowsay. It was simple, charming, and brought warmth and humor to text consoles. For more than two decades, it served as a beloved staple in dotfiles, motd banners, and terminal scripts across Unix and Linux systems.

As modern terminal emulators evolved to support 24-bit TrueColor, Unicode, and rapid VT rendering, an intriguing engineering question presented itself: What if our terminal mascots could gently inhabit the terminal, moving across procedural landscapes while remaining lightweight and respectful of system resources?

Forgum was developed to explore that vision. 🌿

Rather than printing static text directly into the shell scrollback buffer, Forgum introduces a modular, lock-free, 3-threaded engine (SIM, RENDER, CONTROL). Mascots move according to classical kinematics and 2D orbital trajectories, allowing them to walk, glide, and rest across mathematically generated natural scenery. Through differential dirty-cell damage tracking, frame rasterization updates only the exact character cells that change, avoiding full-screen refreshes.

Forgum runs unobtrusively above your active shell prompt. Whether a dragon glides across the horizon, a koala rests with rhythmic chest oscillation, or a cow walks across an undulating trail, Forgum delivers consistent 60 FPS presentation while maintaining a lean memory and CPU footprint.

---

🌿 Modernizing Terminal Mascots with Thoughtful Engineering

Classic Terminal Mascots (1999)	Modern Architecture in Forgum (2026)	Practical Benefits
📜 Static Scrollback Output: Mascots print once and remain in scrollback.	🏃 2D Continuous Kinematics: Mascots navigate terminal margins and procedural horizons in real-time.	Living, animated canvas without cluttering shell history.
🔄 In-Place Leg Cycling: Leg characters cycle regardless of movement.	📐 Stride-Velocity Coupling: Leg cadence is mathematically synchronized to ground velocity ($\omega = v/\lambda$).	Natural gait locomotion: if the mascot halts, hoof animation pauses.
🖥️ Full-Screen Clears: Clears entire screen (\x1b[2J]), risking flicker.	⚡ Dirty-Cell Damage Tracking: Diff-compares buffers, emitting minimal ANSI coordinate jumps (\x1b[y;xH) only where changed.	Fluid 60 FPS animation with sub-1% CPU consumption.
🔒 Global File Locks: Risk of contention across multiple shell instances.	🪟 Pane-Level Session Isolation: Independent session routing across tmux, zellij, wezterm, kitty, and Windows Terminal.	Concurrent execution across terminal panes without contention.
🛑 Raw Mode Signal Delays: Signal propagation can lag in raw terminal mode.	⏱️ Sub-Millisecond Signal Handling: Non-blocking event loops poll and respond to Ctrl+C, 'q', and Esc within milliseconds.	Clean, prompt terminal restoration upon exit or interruption.
⚙️ Manual Configuration Files: Requires manual editing of syntax dotfiles.	🎨 Interactive TUI & 15 Curated Themes: Built-in settings explorer with presets (matrix, cyberpunk, forest, zen, etc.).	Zero-configuration by default, with complete interactive control.

---

🚀 Quickstart (3 commands)

# 1. Run Forgum
forgum

# 2. Ponder a thought with procedural mountain scenery and kinetic effects:
forgum think "The terminal is my canvas." --mountain alpine --road trail --effect walk

# 3. Discover all available options and mascots directly in your terminal:
forgum list
# Or inspect options for any specific argument on the fly:
forgum --animal list
forgum --effect list
forgum --mountain list

That's it. You do not need to edit any config file. Run forgum and follow the critter. By default, random thoughts are enabled—the engine automatically loads a random fortune and wraps it in a thought bubble ( ... ) with o connector circles. On PowerShell, forgum is also available as a wrapper via Forgum.psm1.

---

🎪 The Forgum Farm — A Tour in Animal Voices

Every Forgum scene is described by a SceneConfig. Think of the config as a little farm, and each option as one of the animals that lives there. Here is who you'll meet:

🐮 The Cow says:

"Moo. I am the star of the show — the ANSI cow (or whatever critter) that gets rendered. Set cow to pick your beast, and I'll moo it across the terminal. Set cow to "random" and I'll pick a different cow from data/Cows/ each time."

💭 The Thought says:

"By default, random thoughts are enabled! Whenever you run forgum without explicit speech text, I tap into the pasture fortune cookies and wrap a fresh random fortune inside a ( ... ) thought bubble with o connector circles. You can also prompt me directly with forgum think <words> or --think."

💬 The Text says:

"I'm the words in the speech bubble. When you pass explicit text with render --text, I carry your speech inside classical | ... | borders with \ stems."

✨ The Effect says:

"Watch me sparkle! effect chooses how I animate — rainbows, fades, and more. I'm the reason people stare at their terminal instead of working."

🎨 The Background says:

"I'm the canvas behind everything. background tints the world so the cow pops. Subtle is classy; loud is fun. Your call."

⏱️ The Duration says:

"Tick. Tock. duration is how long I let the scene play before it bows out. Set me to 0 and I'll linger until you say stop."

🎞️ The FPS says:

"I'm the heartbeat of the animation. fps tells me how many frames per second to push. Too high and you'll exhaust the terminal; too low and I limp."

👀 The Eyes say:

"Look at me. eyes sets the cow's gaze — the classic oo, the deadpan ??, or something silly. I give every cow its attitude."

👅 The Tongue says:

"Blep. tongue is the little flick of personality at the bottom of the muzzle. Pair me with the right eyes and the cow gets a whole mood."

🦉 The Owl says:

"Who delivers the cow to your prompt? I decide. default_shell is the shell the engine assumes when it sets up hooks — I watch from the branch and whisper the right command."

🦫 The Beaver says:

"I build dams, and I also build habits. auto_render_on_prompt is my switch — when on, I trigger a render every time your prompt appears. Busy terminal? Flip me off."

🦎 The Chameleon says:

"I become whatever the room needs. color_mode controls how color is handled — full, reduced, or off — so the farm looks right on every terminal, bright or dim."

---

📊 Complete CLI Command & Argument Reference (Structured Tables)

Forgum provides universal, interactive option discovery across every argument and subcommand. Whenever you are curious about what parameters are available, you can inspect them directly from your terminal using:

# Global interactive options table:
forgum list [category]
# Or pass 'list' to any CLI argument:
forgum --animal list
forgum --effect list
forgum --mountain list
forgum --road list
forgum --env list
forgum --color-mode list
forgum --palette list
forgum --eyes list
forgum --tongue list
forgum completions list
forgum config list

---

1. Subcommands Reference Table

Subcommand	Aliases	Parameters / Syntax	Description	Discovery / List Flag
render	(default)	[OPTIONS] [TEXT]...	Renders an animated or static scene with procedural scenery, particles, and speech/thought bubbles above the prompt.	forgum render --help
think	ponder	[OPTIONS] [TEXT]...	Generates a classic thought bubble ( ... ) connected with circular o thought glyphs. Random fortune if text omitted.	forgum think --help
say	speak	[OPTIONS] [TEXT]...	Classic cowsay speech bubble | ... | with diagonal \ pointer stems and full kinetic animation effects.	forgum say --help
fortune	quote	(none)	Fetches and prints a random philosophical, witty, or humorous fortune quote from the pasture catalog.	forgum fortune --help
tui	menu, ui, studio	[TAB]	Fullscreen interactive terminal studio and dashboard for live mascot auditioning, scenery selection, theme tuning, package management, and system configuration.	forgum tui
install	setup, wizard, installer	[--headless] [--telemetry <CONSENT>]	Interactive celestial setup wizard and shell installer with host diagnostics and transparent consent controls.	forgum install
uninstall	remove, deorbit, uninstaller	[-m soft&#124;purge] [-y] [--tui]	Cleanly uninstalls Forgum with user-directed choice (Soft keeps config, Purge wipes completely, or interactive TUI).	forgum uninstall --help
update	upgrade	[--check]	Checks for updates or upgrades Forgum using the detected package manager.	forgum update --check
list	options, ls, show	[CATEGORY]	Displays a responsive, word-wrapped Unicode table of available options (animals, effects, mountains, roads, environments, colors, shells, config, muxes, eyes, tongue, all).	forgum list all
completions	complete	[SHELL]	Emits or auto-installs syntax autocompletion scripts for bash, zsh, fish, pwsh, cmd, carapace, nu, elvish. Defaults to listing shells if omitted.	forgum completions list
init	hook	[SHELL] [--install] [--append]	Generates or auto-injects shell prompt integration hooks so Forgum animates seamlessly on prompt display. Defaults to listing shells if omitted.	forgum init list
config	cfg	[KEY] [VALUE] [--tui] [--list] [--migrate <FMT>]	Reads, writes, migrates (JSON/YAML/TOML), lists all keys in a table, or opens the interactive TUI configuration editor.	forgum config list
theme	themes	[list &#124; apply <NAME> &#124; save <NAME>]	Manages pasture themes. Lists 15 built-in themes with preview vibes or applies a theme to your active configuration.	forgum theme list
checkhealth	doctor	[--json]	Runs 12 comprehensive diagnostic probes across System, Terminal, TrueColor, DNA profiles, Shell hooks, and Loggers.	forgum checkhealth
logs	log, view-logs, show-logs	[-f] [-n <COUNT>] [-l <LEVEL>] [-s <GREP>]	Displays recent structured engine events in a clean tabular view, filters by severity (trace, debug, info, warn, error), or follows in real time.	forgum logs -l warn
diagnose	triage, bugradar	[-n <LINES>] [--json]	Automated diagnostic triage engine analyzing logs and environment to detect issues, root causes, and developer hints.	forgum diagnose
demo	(none)	[--duration <SECS>]	Cinematic showcase iterating through the animal mascots, procedural terrains, and visual animation modes.	forgum demo
showcase	(none)	[--animal <NAME>]	Interactive preview of any critter mascot with animated expression cycling and color palettes.	forgum showcase
tmux	mux	[install &#124; remove &#124; status &#124; list]	Configures tmux, zellij, or wezterm status lines with responsive cow telemetry and mini-status animations.	forgum tmux list
herd	cluster	[list &#124; spawn &#124; kill]	Coordinates multiple concurrent animals grazing across split panes and multi-window terminal layouts.	forgum herd list
remote	peers	[list &#124; who &#124; ping]	Discovers active Forgum pasture peers over local network / SSH clusters and synchronizes session state.	forgum remote list
battle	arena	[FIGHTER1] [FIGHTER2]	Turn-based ASCII battle simulation between two mascots with health bars, randomized travel distance kinematics, and combat log.	forgum battle "Alice" "Bob"
rps-battle	rps	[--player <NAME>] [--cpu <NAME>] [-c <WEAPON>]	Interactive Rock-Paper-Scissors mascot battle (User vs Computer) featuring cryptographic zero-bias PRNG, full-color ASCII hand showdown, and physical jousting clash!	forgum rps-battle
image	(none)	<PATH> [-w <WIDTH>] [--save-cow]	Converts any image (PNG, JPEG, GIF, WebP) to high-fidelity ASCII art with edge detection and color quantization, or converts into custom .cow mascot files.	forgum image logo.png
timer	stopwatch	<DURATION> [COMMAND]...	Animated countdown timer and command execution benchmark with elapsed microsecond progress box.	forgum timer 10s cargo build
status-line	(none)	[--max-len <LEN>]	Single-line compact ANSI status reporter engineered specifically for shell prompt $RPROMPT and tmux status bars.	forgum status-line --max-len 80
control	ctl	<status &#124; stop &#124; pause &#124; resume>	Sends IPC commands to a running background pasture daemon via local domain socket or Windows named pipe.	forgum control status
daemon	(none)	<start &#124; stop &#124; status>	Manages the background engine daemon that continuously feeds frames to prompt overlays without blocking shells.	forgum daemon status
sweep	clean	(none)	Emergency recovery command to restore terminal cursor, disable raw mode, clear temporary pipes, and exit cleanly.	forgum sweep

---

2. Global Arguments & Scene Configuration Table

Flag	Short	Value Type	Default	Description	Universal Discovery
--animal, --cow	-c	String	"default"	Mascot character template from the 106 built-in animal catalog. Set to "random" for a new mascot on every run.	--animal list
--effect, --animation	-E, -a	String	"walk"	Kinematic animation mode driving motion, strides, and particles (walk, fly, float, breathe, ember, aurora, glitch, matrix, portal, rain).	--effect list
--mountain	(none)	String	"smooth"	Procedural mountain backdrop algorithm (smooth, jagged, peaks, alpine, dunes, plateau, mesa, volcanic, rolling, sierra, ridge, flat, none).	--mountain list
--road	(none)	String	"highway"	Ground terrain and road surface rendering style (highway, trail, cobblestone, neon, dirt, gravel, railway, stream, path, cyber, grid, sand, grass, void, none).	--road list
--env, --environment	(none)	String	"pasture"	Full environmental biome preset coordinating sky gradient, ground tint, lighting, and ambient particle emitters (pasture, sunset, cyberpunk, matrix, vaporwave, midnight, autumn, desert, neon, arctic, deepsea, volcano, cosmic, retro, mono).	--env list
--color-mode	-C	String	"truecolor"	Color depth mode (truecolor for 24-bit direct RGB, 256 for xterm-256 color palette, 16 for ANSI 4-bit, mono for zero-escape ASCII).	--color-mode list
--palette	-p	String	"rainbow"	Procedural lolcat color gradient palette (rainbow, aurora, cyberpunk, matrix, sunset, inferno, pastel, grayscale, neon, fire, ice, forest, synthwave, dracula).	--palette list
--eyes	-e	String	"oo"	Facial expression eyes override (oo, $$, @@, xx, ==, ^^, **, .., 00, ??).	--eyes list
--tongue	-T	String	" "	Facial expression tongue override (U , V , J , w , m , " ").	--tongue list
--season	(none)	String	"spring"	Seasonal particle emitter and foliage modifier (spring cherry blossoms, summer bright rays, autumn falling leaves, winter snow flurries).	--season list
--weather	(none)	String	"clear"	Dynamic weather overlay (clear, rain, snow, storm, windy, fog).	--weather list
--duration	-d	u64	0 (or 3 fg)	Playback duration in seconds. 0 runs continuously until q, Esc, or Ctrl+C. Background daemon defaults to 0.	--duration 5
--fps	-f	u32	60	Animation refresh rate (1 to 120 FPS). Engine dynamically throttles to avoid CPU starvation.	--fps 30
--text	(none)	String	Random Fortune	Explicit text to display inside the speech or thought bubble.	--text "Hello World"
--think	(none)	bool	true (if empty)	Enforces thought bubble ( ... ) formatting with circular o connection rings.	--think
--background	-b	bool	false	Renders above prompt as a non-blocking overlay. Cleans up automatically without corrupting command input.	--background
--banner	(none)	bool	false	Prepends an ASCII Forgum header banner to the output frame.	--banner
--split-scroll	(none)	bool	false	Restricts terminal scroll margins via DECSTBM to prevent prompt lines from shifting.	--split-scroll
--thought-interval	(none)	u64	60	Rotation period in seconds for picking and rendering a new random fortune when running in daemon or continuous mode.	--thought-interval 30
--reduce-motion	(none)	bool	false	Accessibility flag: freezes translation coordinates while preserving color cycles and text displays.	--reduce-motion
--text-only	(none)	bool	false	Strips all ANSI color escapes and control characters, outputting pure raw ASCII. Ideal for piping to files or lpr.	--text-only
--file	(none)	Path	None	Loads a custom scene file (.json, .yaml, .toml) to override pasture parameters.	--file scene.yaml
--config	(none)	Path	Default path	Path to configuration file. Defaults to ~/.config/forgum/config.json.	--config /path/to/cfg
--list	-l	String	"all"	Displays formatted discovery table for any requested parameter category (all, animals, effects, mountains, roads, environments, colors, shells, config, muxes, eyes, tongue, scenery).	--list effects

---

3. Procedural Scenery & Mathematical Generation Table

Scenery Component	Style / Option	Generator Formula / Algorithm	Visual Characteristics	Responsive Flexbox Adaptation
Mountains	smooth	$h(x) = A_1 \sin(\frac{2\pi x}{\lambda_1}) + A_2 \cos(\frac{2\pi x}{\lambda_2})$	Soft rolling mountain hills with gentle continuous curvature.	Auto-scales amplitude $\propto \sqrt{W_{\text{term}}}$.
Mountains	jagged	$h(x) = \sum_{k=1}^3 \frac{1}{k} \Vert \text{sawtooth}(k x) \Vert$	Sharp angular ridges with craggy peaks and steep slope gradients.	Octaves recomputed on terminal resize.
Mountains	peaks	$h(x) = A \cdot \max(0, \cos(\omega x))^3$	Tall isolated alpine summits piercing the upper cloud layer.	Clamped to upper 40% of terminal height.
Mountains	alpine	$h(x) = \text{PerlinOctaves}(x, 4) \times \text{SnowCap}(y)$	Snow-dusted high-altitude peaks with variable tree lines.	Dynamically redistributes snow line with seasons.
Mountains	dunes	$h(x) = A \cdot \sin(\omega x) \cdot \Vert \cos(\frac{\omega x}{2}) \Vert$	Sweeping desert sand waves with windward and leeward shadow slopes.	Animates subtle sand drift when --wind > 0.
Mountains	volcanic	$h(x) = \text{Caldera}(x) + \text{EmberParticleEmitters}$	Massive stratovolcano cone with active smoke plume summit.	Emits rising ember ASCII particles (*, ^, .).
Mountains	sierra	$h(x) = \sum_{i=1}^5 A_i \sin(\omega_i x + \phi_i)$	Multi-layered rugged mountain chain spanning the entire backdrop.	Layered parallax scrolling at $0.2\times$ cow speed.
Roads	highway	$\text{Surface} = \text{DoubleSolidWhite} + \text{DashedYellow}$	Modern asphalt roadway with lane markers and road shoulder borders.	Aligned precisely with animal bounding box hooves.
Roads	cobblestone	$\text{Glyphs} = [, \text{"(O)(o)"}, \text{"(o)(O)"} ,]$	Old European rustic paved stone street with alternating stone seams.	Stride-coupled texture offset $\Delta x = \lfloor P_x \rfloor$.
Roads	neon	$\text{Shader} = \text{HSL}(\text{Hue}(t), 1.0, 0.5) \otimes \text{"═══"}$	Cyberpunk glowing light rail pulsing with chromatic energy.	Synchronized with --palette cycle speed.
Roads	dirt	$\text{Noise} = \text{Hash1D}(x) \pmod 3 \to [, \text{". ."}, \text{".. ."}, \text{" . ."} ,]$	Country trail with scattered pebbles and procedural ruts.	Dust particles emit behind running/walking hooves.
Roads	railway	$\text{Track} = \text{"[===|===|===]"}$ with gauge spacing	Industrial train tracks with wooden ties and steel rails.	Rhythmic click-clack motion timing indicator.
Roads	stream	$y_{\text{water}}(x, t) = \sin(\omega x - v t) \to [, \text{"~"}, \text{"≈"}, \text{"∼"} ,]$	Babbling brook / flowing river water surface with ripple reflections.	Flow direction vectors coupled with scenery wind.
Environments	pasture	Daytime blue sky, green grass baseline, procedural daisies.	Serene open countryside; the quintessential home of the cow.	Default balanced contrast biome for all terminals.
Environments	sunset	$C_{\text{sky}}(y) = \text{Lerp}(\text{Purple}, \text{Orange}, \frac{y}{H})$	Dusk twilight with warm ambient glow and lengthening shadows.	Rich 24-bit truecolor vertical gradient transitions.
Environments	cyberpunk	Dark violet sky, magenta horizon, cyan wireframe grid terrain.	High-tech dystopian skyline with scanline glitch flares.	Accents metallic and mechanical mascots.
Environments	matrix	Monochromatic phosphor green font fall on pitch-black background.	Digital rain streams cascading down terminal columns.	ASCII character cycling with variable fall velocity.
Environments	arctic	Glacial cyan-white sky, permafrost ground, falling ice crystals.	Frigid polar expanse with atmospheric refraction shimmer.	Pairs with penguins (tux), seals, and polar bears.
Environments	volcano	Ash-choked obsidian sky, molten magma road, glowing rock fissures.	Cataclysmic underworld with rising soot and lava splatter.	Maximum visual intensity mode for dragons and demons.

---

4. Visual Effects & Motion Kinematics Table

Effect Name	CLI Argument	Kinematic Category	Physics Formulation	Recommended Mascots	Visual Behavior
walk	-E walk	Ground Traversal	Stride Coupling: $\omega = \frac{v}{\lambda_{\text{step}}}$	default, cow, sheep, elephant, moose	The mascot walks smoothly across the pasture with hooves strictly synchronized to velocity.
fly	-E fly	Ballistic Aerial	Dual Harmonic: $Y(t) = Y_0 + A\sin(\omega t) + B\cos(2\omega t)$	dragon, golden-eagle, bat, pterodactyl	Swoops gracefully across the upper terminal canvas with dynamic wing flapping.
float	-E float	2D Orbital Drift	Lissajous Curve: $X(t) \perp Y(t)$ orthogonal drift	dolphin, happy-whale, nyan, ghost	Buoyant zero-gravity floating with smooth turning and depth oscillation.
breathe	-E breathe	Harmonic Respiration	Chest Expansion: $\Delta W(t) = \lfloor A \sin(2\pi f t) \rceil$	koala, tux, cat2, bear, buddha	Meditative stationary breathing cycle with organic subtle torso contraction.
ember	-E ember	Particle Emitter	Newtonian Ballistics: $\vec{P}(t) = \vec{P}_0 + \vec{V}t + \frac{1}{2}\vec{g}t^2$	dragon, daemon, hellokitty, vampire	Blazing fire particles and drifting smoke rising from nostrils and maw.
aurora	-E aurora	Wave Interference	Traveling Sine: $I(x, t) = \sin(k x - \omega t)$	all, fox, wolf, owl, stegosaurus	Luminous Northern Lights chromatic waves shifting across critter contours.
glitch	-E glitch	Scanline Distortion	Tearing: $\Delta x = \text{sgn}(\sin(\text{seed})) \cdot \lfloor 3 I^3 \rfloor$	mech-and-cow, telebears, cyborg, robot	CRT cybernetic scanline jitter, chromatic aberration, and coordinate tearing.
matrix	-E matrix	Rain Stream	Pseudo-random column shift & glyph cycling	default, gnu, tux, daemon	Cascading matrix code glyphs cascading through and around the speech bubble.
portal	-E portal	Radial Warp	Vortex Distortion: $r' = r \cdot (1 - e^{-\alpha t})$	ghost, tardis, nyan, cowsay	Swirling dimensional wormhole materialization and dematerialization.
rain	-E rain	Atmospheric Particle	Slanted precipitation vectors $\vec{V} = (v_{\text{wind}}, v_{\text{fall}})$	duck, frog, snail, turtle	Raindrops splashing on the ground with puddle ripples and droplet ricochets.

---

5. Animal Mascots Catalog Table (106 Built-in Mascots)

Category	Mascot Names	Character Width Range	Bubble Placement	Special Traits & DNA Features
Classic Bovines	default, cow, cowsay, small, eyes, bud-frogs, three-eyes, flaming-cow	14 – 22 cols	Top-Left / Above	Stride-coupled four-legged gait, tail wagging, ear twitches, chew animation.
Mythical & Fantasy	dragon, dragon-and-cow, daemon, ghost, skeleton, vampire, cthulhu, unicorn	24 – 38 cols	Top-Right / Dynamic	Dual-layer wings, ember particle emission, ethereal spectral transparency.
Wild Mammals	elephant, moose, koala, bear, fox, wolf, lion, tiger, kangaroo, hippo	18 – 32 cols	Above / Left	Custom trunk kinematics, antler span wrapping, meditative harmonic chest breathing.
Aquatic & Marine	dolphin, happy-whale, shark, octopus, squid, duck, frog, seahorse, penguin	16 – 30 cols	Floating Center	Lissajous orbital swimming, bubble particle streams, flipper motion.
Birds & Insects	golden-eagle, owl, toucan, turkey, rooster, bee, butterfly, spider	12 – 26 cols	High Altitude	Rapid wing flap cycles, perch animations, sinusoidal swooping.
Cybernetic & Pop	mech-and-cow, telebears, nyan, tardis, bender, homer, vader, mario, sonic	20 – 34 cols	Dynamic	Scanline glitch tearing, rainbow trail emitters, cybernetic visor blinking.
OS & Tech Mascots	tux (Linux), gnu (GNU), bsd-daemon (FreeBSD), rust-ferris (Rust), gopher (Go), python	16 – 28 cols	Above Prompt	Official ecosystem silhouettes, terminal prompt companion sizing.

---

6. Expressions & Mood Modifiers Table

Facial Feature	CLI Flag	Value	Expression Mood	Visual Rendering	Compatible Mascots
Eyes	-e oo	oo	Normal / Attentive	Standard rounded open bovine eyes (oo)	All mascots
Eyes	-e $$	$$	Greedy / Commercial	Dollar sign cash eyes ($$)	All mascots
Eyes	-e @@	@@	Stoned / Hypnotized	Spiral hypnotic concentric eyes (@@)	All mascots
Eyes	-e xx	xx	Dead / Knocked Out	Criss-cross knocked-out X eyes (xx)	All mascots
Eyes	-e ==	==	Zen / Meditative	Closed peaceful horizontal slit eyes (==)	All mascots
Eyes	-e ^^	^^	Happy / Joyful	Cheerful anime upturned squinting eyes (^^)	All mascots
Eyes	-e **	**	Dazed / Starstruck	Sparkling asterisk star eyes (**)	All mascots
Eyes	-e ..	..	Sleepy / Subtle	Tiny minimalist dot eyes (..)	All mascots
Eyes	-e 00	00	Cyber / Robotic	High-intensity glowing LED oculars (00)	Mech, Cyber, Tech
Eyes	-e ??	??	Perplexed / Curious	Question mark confused gaze (??)	All mascots
Tongue	-T "U "	U	Blep / Playful	Classic pink bovine tongue protruding ( U )	Bovines, Dogs, Cats
Tongue	-T "V "	V	Forked / Reptilian	Forked snake or dragon tongue ( V )	Dragons, Reptiles
Tongue	-T "J "	J	Lick / Savoring	Side curl licking lip tongue ( J )	All mascots
Tongue	-T "w "	w	Cute / Anime	W-shaped feline muzzle curl ( w )	Cats, Koalas, Nyan
Tongue	-T "m "	m	Chewing / Cud	Active cud-chewing jaw motion ( m )	Cows, Sheep, Moose
Tongue	-T " "	" "	Retracted / None	Clean closed muzzle without tongue	All mascots

---

7. Color Modes & Palette Engine Table

Color Mode	Flag Syntax	Bit Depth	Escape Sequences Emitted	Fallback Handling	Accessibility / Target Terminals
TrueColor	-C truecolor	24-bit direct	\x1b[38;2;R;G;Bm	Probed via COLORTERM=truecolor	Windows Terminal, Ghostty, WezTerm, Alacritty, Kitty, Foot.
256-Color	-C 256	8-bit indexed	\x1b[38;5;Nm	Nearest Euclidean RGB quantization	xterm-256color, tmux internal windows, macOS Terminal.app.
16-Color	-C 16	4-bit standard	\x1b[30m – \x1b[37m, \x1b[90m – \x1b[97m	Brightness threshold clamping	Linux VT consoles (/dev/tty1), legacy SSH terminals.
Monochrome	-C mono	1-bit	None (pure ASCII text)	Strips all styling and escapes	Braille readers, screen readers, pipeline logging, thermal printers.

---

8. Unified Configuration Schema (17 Keys) Table

Config Key	Data Type	Default Value	Valid Range / Options	CLI Mapping	Description
cow	String	"default"	132 mascots or "random"	--animal, -c	Selected mascot character template.
effect	String	"walk"	10 animation modes	--effect, -E	Primary animation effect algorithm.
mountain	String	"smooth"	12 mountain styles	--mountain	Procedural mountain backdrop style.
road	String	"highway"	14 road surfaces	--road	Ground terrain and road rendering surface.
environment	String	"pasture"	15 biome presets	--env, --environment	Environmental palette, sky gradient, and atmospheric particle theme.
color_mode	String	"truecolor"	truecolor, 256, 16, mono	--color-mode, -C	Color depth rendering mode.
palette	String	"rainbow"	14 palette presets	--palette, -p	Color gradient palette for lolcat cycling.
eyes	String	"oo"	10 eye expressions	--eyes, -e	Facial expression eye characters.
tongue	String	" "	6 tongue expressions	--tongue, -T	Facial expression tongue characters.
fps	u32	60	1 to 120	--fps, -f	Target frames per second for rendering loop.
duration	u64	0 (or 3 fg)	0 to 86400	--duration, -d	Playback duration in seconds (0 = infinite).
thought_interval	u64	60	1 to 3600	--thought-interval	Rotation interval in seconds for random fortune updates.
split_scroll	bool	false	true, false	--split-scroll	Restrict scrolling region to protect prompt.
background	bool	false	true, false	--background, -b	Render in non-blocking background overlay mode.
auto_render_on_prompt	bool	true	true, false	init hook setting	Triggers automatic cow render on new shell prompt.
default_shell	String	Auto-detected	All 15 shells	init <SHELL>	Default shell assumed for hook generation.
shell_attach_mode	String	"overlay"	"overlay", "banner", "inline"	--banner	How the pasture renders relative to the shell prompt.

---

9. Multi-Platform, Hardware Architecture & Zero-Ghosting Matrix Table

Platform / OS	CPU Architecture	Tested Terminals	Ghosting Prevention Mechanism	Terminal Resize Resilience
Linux (Ubuntu, Fedora, Arch, Debian, Alpine, Gentoo, NixOS)	x86_64, aarch64, armv7, riscv64gc	Ghostty, Alacritty, WezTerm, Kitty, Foot, Konsole, GNOME Terminal, Xterm	Lock-free diff-damage cell buffer (\x1b[y;xH minimal jumps)	Instant reflow via SIGWINCH signal; dynamic flexbox wrapping down to $10\times 10$ px.
macOS (Sonoma, Sequoia, Ventura)	Apple Silicon (aarch64), Intel (x86_64)	Ghostty, iTerm2, WezTerm, Alacritty, Terminal.app	Double-buffering with synchronized DEC 2026 update fencing	Debounced resize event loop guarantees clean bounds recalculation.
Windows (11, 10, Server 2022)	x64 (AMD64), ARM64, x86 (i686 best-effort)	Windows Terminal, WezTerm, ConEmu, Alacritty, ConHost	Windows Console API / VT100 dual-layer driver with atomic buffer flush	Full ConPTY viewport query with automatic cursor clamping and zero trail ghosting.
BSD (FreeBSD 14+, OpenBSD)	x86_64, aarch64	Xterm, Alacritty, Tmux	Zero platform-specific #[cfg] in engine; pure portable POSIX layer	Strict POSIX signal handler intercepts interrupts and restores terminal state.
ChromeOS / Android (Termux, Crostini)	aarch64, x86_64	Termux Terminal, ChromeOS Terminal (hterm)	Conservative fallback ANSI escape sequencing	High-density font scaling and touch-friendly terminal reflow.

---

🧮 Under The Hood: Kinematics & Nature Mathematics

Most terminal tools just print static text. Forgum treats your terminal emulator as a high-frequency discrete physics simulation canvas.

Behind every swaying tail, glowing dragon breath, and walking creature lies an industrial-grade mathematical engine implemented in pure, safe Rust. Forgum pushes tens of thousands of colored terminal cells at a locked 60 FPS without touching a GPU shader pipeline:

  ┌───────────────────────────────────────────────────────────────────────────────────┐
  │                            CONTINUOUS PHASE MANIFOLD                              │
  │                                                                                   │
  │   t (Sub-ms Instant) ──►  Newtonian Calculus  ──►  Lissajous Dynamic Coupling     │
  │                                    │                              │               │
  │                                    ▼                              ▼               │
  │   Fourier Horizon Synthesis ──► Bounding-Hull ──► 24-bit HSV Chromatic Dispersion │
  │   (Multi-Harmonic Terrain)    Occlusion Buffer    (Continuous lolcat Wave)        │
  │                                    │                              │               │
  │                                    └──────────────┬───────────────┘               │
  │                                                   ▼                               │
  │                                      Lock-Free Double FrameBuffer                 │
  │                                     (Diff-Damage Optimized Flushes)               │
  └───────────────────────────────────────────────────────────────────────────────────┘

1. Newtonian Kinematics & Sub-Millisecond Delta-Time Pacing

Forgum integrates continuous physical time deltas evaluated via platform-native monotonic timers (std::time::Instant with sub-microsecond resolution on Windows QPC and Linux CLOCK_MONOTONIC): $$\Delta t = t_n - t_{n-1}, \quad \vec{P}(t + \Delta t) = \vec{P}(t) + \vec{V}(t)\Delta t + \frac{1}{2}\vec{A}(t)\Delta t^2$$ Sub-character coordinates are projected onto discrete monospace grid cell quanta via midpoint quantization ($x_{\text{col}} = \lfloor P_x \rceil, y_{\text{row}} = \lfloor P_y \rceil$).

2. Stride-Velocity Coupling & Anti-Moonwalk Phase Invariant

In naive ASCII animation, a walking creature's feet slide unnaturally across the road (the "moonwalk bug"). Forgum mathematically couples leg stride cadence to ground velocity and stride wavelength: $$\omega_{\text{stride}} = \frac{v_{\text{walk}}}{\lambda_{\text{step}}}, \quad \phi_{\text{stride}}(t) = \left( \frac{|P_x(t)|}{\lambda_{\text{step}}} \right) \pmod{1.0}$$ During stance phase, relative contact velocity satisfies $\vec{v}{\text{contact}} = \vec{v}{\text{body}} - \omega \times \vec{r}_{\text{leg}} = 0$. When the creature halts, leg oscillation ceases instantly.

3. Harmonic Lissajous Orbitals & Sinusoidal Flight Trajectories

• Orbital Drift (float): Aquatic and celestial mascots follow orthogonal dual-frequency phase-shifted harmonic oscillations ($X(t) = X_0 + A_x \sin(\omega_x t + \delta_x), Y(t) = Y_0 + A_y \cos(\omega_y t + \delta_y)$), modeling organic buoyancy without sharp directional jerks.
• Flight Trajectories (fly): Airborne creatures follow continuous flight paths modulated by dual-harmonic altitude swoops with wing flap cadence dynamically scaling with vertical climb gradient $|\frac{dY}{dt}|$.

4. Nature Mathematics: Mountain Elevation & Golden Ratio Peak Count

Procedural alpine peaks, mesas, and volcanic calderas are generated deterministically per column $x$ using multi-harmonic sinusoidal superposition: $$H(x) = H_{\text{base}} \cdot \left[ 1 + \sum_{k=1}^{K} A_k \cdot \left| \sin\left( \frac{2\pi k}{\lambda} x_{\text{world}} + \phi_k \right) \right|^\gamma \right]$$ The peak count $N_{\text{peaks}}$ scales mathematically with viewport width $W$ and the Golden Ratio ($\Phi \approx 1.6180339887$): $$N_{\text{peaks}} = \mathrm{clamp}\left(\left\lfloor \frac{W}{\lambda \cdot (\Phi / 2)} \right\rceil, 1, 12\right)$$

• Alpine Peaks: Power-pinched exponent $\gamma = 1.85$ sculpts sharp glacial horn peaks separated by broad cirque valleys.
• Plateaus & Mesas: Hyperbolic tangent saturation $H(x) \propto \tanh(3 \sin(\omega x))$ produces flat-topped mesas with sheer vertical escarpments.
• Volcanic Cones: Lorentzian distribution $\frac{A}{1 + (x/\sigma)^2}$ with a central inverted caldera basin models volcanic topography.

5. Fibonacci Biological Flora Spacing & Stature-Scaled Canopy

Procedural trees and midground vegetation mimic natural botanical stands using Fibonacci / Golden Ratio phyllotaxis spacing ($\Phi^{-1} \approx 0.61803398875$): $$d(k) = \max\left(0.7 \cdot d_{\min}, ; d_{\min} + {k \cdot \Phi^{-1}} \cdot d_{\text{var}} + \frac{d_{\text{var}}}{4} \cos\left(2\pi {k \cdot \Phi^{-2}}\right)\right)$$ Tree height $H_{\text{tree}}$ is proportioned relative to the mascot's physical height $H_{\text{animal}}$ ($H_{\text{tree}} = H_{\text{animal}} \cdot M_{\text{anim}} \cdot (1 + 0.22 \sin(2.4k) + 0.12 \cos(1.6k))$). Walking creatures are framed naturally within glades ($M=1.25$), while airborne creatures glide gracefully above foliage ($M=0.80$).

6. Bounding-Hull Silhouette Occlusion Masking (Zero Scenery Bleed-Through)

To prevent background mountains, stars, and trees from bleeding through the interior body of ASCII mascots, the compositor evaluates scanline bounding hulls: $$\Omega_{\text{hull}}(y) = \left[ \min {x \mid \text{Glyph}(x, y) \neq \text{' '}}, ; \max {x \mid \text{Glyph}(x, y) \neq \text{' '}} \right]$$ Cells within the hull silhouette that lack mascot artwork are committed to the depth buffer as opaque masking cells, preserving the animal's solid visual form over scrolling backgrounds.

7. Continuous 24-Bit HSV Chromatic Manifolds

Forgum replaces discrete 8-color jumping with a continuous lolcat chromatic dispersion wave computed directly in normalized cylindrical HSV space: $$\text{Hue}(x, y, t) = \left( \frac{x \cdot \Delta x_{\text{freq}} + y \cdot \Delta y_{\text{freq}}}{\lambda} + \frac{t}{T_{\text{period}}} \right) \bmod 1.0$$ $$\begin{pmatrix} R \ G \ B \end{pmatrix} = \text{HSV}\to\text{RGB}\left(\text{Hue}(x, y, t), ; S=0.92, ; V=0.98\right)$$ Emitted as direct 24-bit TrueColor ANSI escape codes (\x1b[38;2;R;G;Bm).

8. Strict Lightweight Memory Architecture (< 100MB RAM Mandate)

Forgum enforces a strict memory ceiling across all execution modes:

• The entire render pipeline operates under 100MB of resident RAM.
• In multi-threaded benchmarking (8 concurrent simulation and rendering threads generating 200 frames each), resident set size measures ~13MB RAM.
• All mathematical evaluations operate exclusively on zero-allocation stack primitives and pre-allocated double buffers, avoiding runtime heap allocation during active rendering.

9. Terminal Viewport Reservation & DECSTBM Split-Scroll Multitasking

Forgum supports dynamic screen partitioning using standard DEC Set Top and Bottom Margins (DECSTBM):

• Reserved Animation Header: Fixes the top $K$ rows for physical creature kinematics and procedural nature horizons updating at 30/60 FPS.
• Simultaneous Shell Workspace: Sets scrolling margins to lines $(K+1) \dots N$, allowing the user to simultaneously execute commands, view build outputs, and type at the prompt without visual interference or cursor flicker.

📖 Deep Dive: For formal mathematical derivations, benchmark scripts, and architecture schematics, see ADVANCED.md.

---

🐚 Shell Integration & Ecosystem

Forgum hooks into your terminal shell so your living mascot and procedural pasture render seamlessly and unobtrusively above your prompt.

⚡ One-Command Automatic Setup

To automatically detect your active shell and inject the isolated, non-destructive prompt hook:

forgum init --install
# Or specify your shell explicitly:
forgum init <shell> --install

All injected shell hooks strictly maintain standard marker isolation (# >>> forgum >>> ... # <<< forgum <<<), never pollute shell startup latency, and can be cleanly uninstalled at any time.

📋 Universal 15-Shell Reference Table

Shell	Automated Hook Injection	Tab Completion Setup	Target Profile Path
PowerShell 7+ (pwsh)	forgum init pwsh --install	forgum completions pwsh | Out-File $PROFILE	$PROFILE
Windows PowerShell 5.1	forgum init powershell --install	forgum completions powershell | Out-File $PROFILE	$PROFILE
Bash	forgum init bash --install	forgum completions bash > ~/.bash_completion	~/.bashrc
Zsh	forgum init zsh --install	forgum completions zsh > ~/.zsh/completions/_forgum	~/.zshrc
Fish	forgum init fish --install	forgum completions fish > ~/.config/fish/completions/forgum.fish	~/.config/fish/config.fish
Nushell	forgum init nushell --install	forgum completions nu > ~/.config/nushell/completions/forgum.nu	~/.config/nushell/config.nu
Elvish	forgum init elvish --install	forgum completions elvish > ~/.config/elvish/lib/forgum.elv	~/.config/elvish/rc.elv
Cmd (cmd.exe)	forgum init cmd --install	(not applicable / doskey alias)	Registry AutoRun / AutoRun.cmd
Carapace	forgum init carapace --install	forgum completions carapace	~/.config/carapace/specs/forgum.yaml
Xonsh	forgum init xonsh --install	forgum completions xonsh > ~/.xonshrc	~/.xonshrc
Tcsh (csh)	forgum init tcsh --install	forgum completions tcsh > ~/.cshrc	~/.cshrc
Ksh (ksh93/mksh)	forgum init ksh --install	forgum completions ksh > ~/.kshrc	~/.kshrc
Ion	forgum init ion --install	forgum completions ion > ~/.config/ion/initrc	~/.config/ion/initrc
Oil (osh/ysh)	forgum init oil --install	forgum completions oil > ~/.config/oil/yshrc	~/.config/oil/yshrc
Yash	forgum init yash --install	forgum completions yash > ~/.yashrc	~/.yashrc

🌟 Awesome-Shell & Multiplexer Matrix

Forgum provides native interoperability with terminal multiplexers and utilities from alebcay/awesome-shell:

Tool / CLI	Category	Integration Command / Hook	Forgum Capability
tmux	Terminal Multiplexer	forgum tmux install >> ~/.tmux.conf	Zero-flicker DCS pass-through (\x1bPtmux;\x1b...), real-time status-right daemon updates.
zellij	Modern Multiplexer	forgum tmux zellij	Native plugin pane rendering, floating terminal mascot keeping tabs on workspace status.
wezterm	GPU Terminal	forgum tmux wezterm	Lua status line generator and GPU shader synchronization.
starship	Cross-Shell Prompt	forgum init starship	Custom starship prompt module emitting ANSI mascots and fortune cookies above prompt.
fzf	Fuzzy Finder	forgum list animals | fzf --preview 'forgum -c {} --text "Preview"'	Interactive instant mascot selection with high-speed ANSI previewing.
bat	Syntax Highlighter	forgum --text-only | bat	Color-aware pager formatting with automated background ANSI strip detection.
thefuck	Command Corrector	Custom rule forgum-rules.py	Automatically repairs mistyped mascots or unknown CLI flags to the closest match.
navi	Interactive Cheatsheet	forgum init navi	Pre-built cheatsheets for every CLI command, effect, and environment combination.
byobu	Multiplexer Wrapper	forgum init byobu	Background status monitor notifying when long-running compiler tasks complete.

---

🖥️ Terminal Compatibility

Terminal	Sync (DEC 2026)	Graphics	Notes
Windows Terminal	✓ (when supported)	✗	sync gated by capability probe
Ghostty	✓	✓ (Sixel)	full modern support
kitty	✓	✓ (Kitty graphics)	native graphics protocol
iTerm2	✓	via imgcat (out of scope)	sync supported
Alacritty	✓	✗	sync only
Konsole	✓	✓ (Sixel)	sync + sixel
gnome-terminal / xterm	varies	Sixel via xterm sometimes	conservative
Terminal.app (macOS)	✗	✗	ANSI only

All advanced features are capability-probed and OFF by default; Forgum emits conservative ANSI so it never breaks on an unknown terminal.

---

🩺 Check Your Pasture's Health (checkhealth)

Got weird rendering? Colors looking like a melted popsicle? Shell hooks misbehaving? Channel your inner Neovim user and run:

forgum checkhealth

The health inspector will run 12 diagnostic probes across 7 core systems (System, Configuration, Terminal & TrueColor, Pasture Assets & DNA profiles, Shell hooks, Daemons, and Structured Logs) and give you actionable remediation suggestions.

For CI/CD and scripts, get machine-readable JSON:

forgum checkhealth --json

---

⚙️ Config File Location & Multi-Format Support

Forgum has one unified configuration home across all operating systems:

Platform	Path
Windows	~/.config/forgum/config.json (or .yaml / .toml)
macOS	~/.config/forgum/config.json (or .yaml / .toml)
Linux	~/.config/forgum/config.json (or .yaml / .toml)

Single-Format Exclusivity: Forgum supports JSON, YAML, and TOML, but forbids multiple format files in the same directory. Want to switch? Run forgum config --migrate toml (or json/yaml) and let the engine convert it safely!

Override at runtime with the FORGUM_CONFIG environment variable.

---

🪵 Structured Logs & Diagnostics

Forgum logs all events with microsecond precision to both human-readable text and structured JSONL logs:

# View recent logs in a formatted table
forgum logs

# Filter by severity
forgum logs --level warn

# Live follow logs
forgum logs -f

---

✨ Forgum Configurator (Interactive TUI & Full Scripting Parity)

Forgum features a rich, responsive terminal configuration studio with Tailwind CSS-inspired design tokens (Slate-800 dark pill badges, vibrant Indigo/Violet/Emerald/Sky/Amber accents, rounded borders, and dynamic text wrapping):

# Launch the interactive Forgum Configurator:
forgum config --tui
# Or shortcut:
forgum tui

 ✨ FORGUM CONFIGURATOR   [CONFIG]  1 Mascots  2 Scenery  3 Effects  4 Installer  5 [Config]        0.0.3 beta
┌───────────────────────────── Forgum Engine Settings ───────────────────────────────┬───────────────────────────────┐
│ > 01. cow                   [ moojira                      ]                       │ Parameter Details             │
│   02. text                  [                              ]                       │ Parameter: split_mode         │
│   03. effect                [ animal_natural               ]                       │ Value:     [seamless]         │
│   04. split_mode            [ seamless                     ]                       │ Mode:      Single-pane        │
│   05. editor                [ nvim                         ]                       │                               │
│   06. fps                   [ 60                           ]                       │ Shortcuts:                    │
│   07. duration              [ 0                            ]                       │ [e/Enter] Edit  [+/-] Step    │
│   08. background            [ ON                           ]                       │ [o] Editor      [s] Save      │
└────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────┘
 <Tab> Tabs   <j/k> Select   <e/Enter> Edit   <+/-> Step   <o> Open Editor   <s> Save   <q> Quit  │ Forgum Configurator Ready

🌟 Key Studio Capabilities:

• 100% Config & Scripting Parity: Every single setting that can be defined in a configuration file or passed via CLI flags (all 26 parameters: cow, text, effect, background, duration, fps, eyes, tongue, default_shell, auto_render_on_prompt, think, color_mode, shell_attach_mode, environment, road, mountain, palette, thought_interval, split_scroll, reserve_rows, reserve_cols, split_ratio, animation, animation_type, image, split_mode, editor) can be inspected, toggled, stepped, or modified in the Configurator.
• Seamless Split Mode: Set split_mode to seamless (via forgum config set split_mode seamless or --split-mode seamless) to run inline above your active prompt without terminal margin flickering or pane boundary disruption.
• External Text Editor Keybinding (o / Ctrl+O / Ctrl+E): Press o, Ctrl+O, or Ctrl+E in the TUI to open the active configuration file in your system's detected or chosen editor (nvim, vim, emacs, nano, code, or notepad). Forgum cleanly suspends the terminal raw mode, spawns your editor, and reactively reloads the updated configuration when you exit.
• Live Preview Canvas & HUD Timeline: Preview animal motion, speech/thought bubbles, eye blinks, and procedural terrain changes in real-time at your configured target FPS.

📜 Headless CLI Scripting:

Need to script or query configuration values in CI/CD or shell scripts? All 26 keys support fast headless querying and updating:

# Query any setting:
forgum config get cow
forgum config split_mode
forgum config editor

# Set any setting (both 'config set' and 'config <key> <val>' supported):
forgum config set cow tux
forgum config split_mode seamless
forgum config editor nvim
forgum config set fps 60
forgum config set color_mode natural

# List all 26 parameters, data types, and accepted options:
forgum list config
# or:
forgum config --list

---

🎨 Preloaded Themes & Kinematic Motion

Forgum includes 15 built-in preloaded themes ready out-of-the-box:

# List all built-in and user themes
forgum theme list

# Apply a preloaded theme immediately
forgum theme apply matrix
forgum theme apply cyberpunk
forgum theme apply inferno

Theme	Effect	Mascot	Eyes	Vibe
arcade	walk	default	oo	Classic 8-bit pasture walk
aurora	aurora	default	oo	Northern lights color shifting
cyberpunk	glitch	mech-and-cow	$$	Neo-Tokyo neon scanline distortion
forest	breathe	koala	..	Calm bamboo canopy breathing
ghost	portal	ghost	xx	Ethereal spectral phasing
inferno	ember	dragon	@@	Blazing fire particles & smoke
matrix	glitch	telebears	00	Falling terminal green glyphs
nyan	float	nyan	^^	2D cosmic rainbow orbital drift
ocean	float	dolphin	oo	Deep ocean buoyancy float
zen	breathe	tux	==	Meditative Linux penguin respiration

🏃 2D Kinematics Engine

Entities in Forgum are driven by continuous 2D kinematics:

• True Traversal (walk): The creature physically moves across the terminal pasture with leg strides coupled to ground velocity ($\omega = v / \lambda$).
• Flight Trajectory (fly): Soars across the sky on a sinusoidal flight path with synchronized wing flapping.
• Orbital Drift (float): Smooth 2D Lissajous floating drift across the viewport.
• Interactive Fail-Safe Exit: Press Ctrl+C, q, or Esc anytime in foreground mode for clean, immediate terminal restoration.

---

🎨 Sample Configs

Want a head start? Browse the ready-made scenes in docs/samples/:

Config	Description
config.rainbow.json	Full-color, effect-heavy joy
config.minimal.json	Just the cow, nothing else
config.solid.json	Solid background, calm and clean

See docs/samples/README.md for the full tour of each sample.

---

🏗️ Build from Source

cargo build --workspace
cargo test --workspace

Bubble Format

The speech bubble is rendered with a consistent width guarantee: all rows (top, content, and bottom) have identical visible width. This ensures the bubble looks correct regardless of text length or line count.

Platform Notes

• i686 (32-bit Windows): Build-only lane — the binary builds but is not tested or packaged for release. Use at your own risk.

---

🍀 Fortune

Need a little wisdom from the farm?

forgum fortune

---

📚 Further Reading

Document	What it covers
CONTRIBUTING.md	How to contribute, and the current status of each package-manager lane
ADVANCED.md	Deep dives into the engine, daemon, and capability probe
docs/TALES.md	Longer stories from the Forgum menagerie
docs/samples/README.md	The sample config catalog

---

📜 License

MIT. See LICENSE.

---

    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
            ||----w |
            ||     ||

Made with ❤️ and Rust by harish2222 (HKDevLoops) · For the terminal cow in all of us