climash 0.1.1

Ambient terminal weather effects – snow, rain, sun, and spring leaves

Climash 🌨

Ambient terminal weather effects – beautiful, non-intrusive animations that play in the background while you work.

---

What is Climash?

Climash renders subtle weather particle effects (snow ❄, rain 🌧, sunlight ☀, spring leaves 🍂) at the top of your terminal using ANSI escape sequences, while leaving your shell prompt and all command output completely intact.

❄   ❄     ❄  ❄      ❄   ❄   ❄   ❄
  ❄    ❄         ❄      ❄       ❄
❄        ❄    ❄     ❄      ❄      ❄
user@machine:~$ ping google.com
PING google.com (142.250.80.46) 56(84) bytes of data.
64 bytes from lga34s32-in-f14.1e100.net: icmp_seq=1 ttl=115 time=12.4 ms

The animation runs in a background thread at ~12 FPS. It never clears the full screen and never overwrites your output.

---

Installation

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
climash

If the climash launcher is not on your PATH yet, use:

python -m climash.main

If you cloned the repo into a folder with spaces in the path, quote it:

python -m pip install -e "D:\DUK Study\Projects-Personal\climash"

In PowerShell, do not use start by itself. That is PowerShell's built-in Start-Process alias. Always call the app as climash start.

If PowerShell still tries to treat start like a shell command, use the stop-parsing operator:

climash --% start

Linux / macOS shell

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
climash

If the launcher is not available, use:

python -m climash.main

Install from PyPI

pip install climash

Or install from source on either platform:

git clone https://github.com/Vimal-Mudalagi/climash.git
cd climash
pip install -e .

If you want to verify the install on a fresh system, run:

climash --help
climash themes
climash start

If the climash command is not available yet, use the module form:

python -m climash.main --help
python -m climash.main themes
python -m climash.main start

Requirements: Python 3.10+ — no mandatory third-party dependencies.

---

Quick Start

# Show banner and usage
climash

# Start with a random theme
climash start

# Start a specific theme
climash start snow
climash start rain
climash start sun
climash start spring

# Stop the animation (or just press Ctrl-C in the running terminal)
climash stop

# List all themes
climash themes

If the climash command is not available in your shell yet, run:

python -m climash.main

If you are in PowerShell and the launcher is missing, use:

python -m climash.main themes
python -m climash.main start

---

CLI Reference

climash

Display the welcome banner and usage instructions.

╔════════════════════════╗
║                        ║
║        CLIMASH         ║
║   terminal weather     ║
║        vibes           ║
║                        ║
╚════════════════════════╝

---

climash start [theme]

Start the animation. Optional theme argument overrides the configured default.

climash start          # uses configured default (or random)
climash start snow
climash start rain
climash start sun
climash start spring

On Windows PowerShell, use climash start rather than start.

If that still opens the PowerShell Start-Process prompt, run:

climash --% start

Press Ctrl-C to stop.

---

climash stop

Prints guidance on stopping the animation (Ctrl-C or kill <PID>).

---

climash themes

List all available themes:

Available themes:

  ❄  snow          Gently falling snowflakes
  🌧 rain          Fast falling rain drops
  ☀  sun           Warm sunlight glow particles
  🍂 spring        Drifting spring leaves

---

climash set <theme>

Persist a default theme to ~/.climash/config.json.

climash set snow
climash set rain
climash set sun
climash set spring
climash set random

---

climash random

Set the default theme to random (a different theme is chosen each session).

climash random

---

climash disable

Disable the automatic theme (sets default to "none").

climash disable

---

climash --help

Print full argparse help text.

---

Themes

Command	Particles	Movement	Colours
snow	❄ ✦ ·	Downward drift	White / light blue
rain	| .	Fast vertical drop	Blue
sun	☀ ✧ *	Gentle flicker / glow	Yellow / gold
spring	🍂 🍃 ✿ ❀	Diagonal drift	Orange / green

---

Configuration

Climash stores a small JSON config file at ~/.climash/config.json:

{
  "default": "snow"
}

Possible values for "default": "snow", "rain", "sun", "spring", "random", "none".

---

Auto-Start

To launch Climash automatically every time you open a terminal, add the following to your shell startup file.

Bash (~/.bashrc):

climash start &

Zsh (~/.zshrc):

climash start &

Fish (~/.config/fish/config.fish):

climash start &

PowerShell ($PROFILE):

climash start

On Windows, climash start runs in the foreground. If you want a detached session, launch it from a separate terminal window or use a background job.

Tip: climash set snow (or any theme) before adding to your rc file so the same theme starts each session.

---

How It Works

1. climash start launches an AnimationEngine in a daemon thread.
2. The engine detects the terminal width dynamically.
3. Each frame (~12 FPS):
   • Saves the current cursor position (ESC 7).
   • Moves to rows 1–3 (the reserved animation region).
   • Renders updated particle positions.
   • Restores the cursor (ESC 8).
4. When stopped, the reserved rows are cleared and the cursor is restored.

This means no full-screen clear, and your shell prompt stays exactly where it is.

---

Contributing

Contributions are welcome! See the project structure below and open a PR.

climash/
├── climash/
│   ├── __init__.py    – package version
│   ├── main.py        – CLI (argparse)
│   ├── engine.py      – background animation thread
│   ├── animations.py  – particle logic & rendering
│   ├── themes.py      – theme definitions
│   └── config.py      – ~/.climash/config.json management
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

---

License

MIT © Climash Contributors