A breathing layer for AI-powered terminals. Turns every wait into a calm ritual — across tools, across platforms, automatically.

Table of Contents

• 🚀 Get Started
• 🧘 Why HushFlow?
• ✨ Features
• 🖥️ Supported Terminals
• 🎵 Immersive Audio
• 📊 Usage Statistics
• 📺 UI Modes
• ⌨️ Common Commands
• 🧠 How It Works
• 🔒 Transparency & Trust
• 📚 Advanced Docs
• 🤝 Contributing & Support

🚀 Get Started in < 60 Seconds

[!IMPORTANT] Prerequisites: bash (4.0+), git, and jq are required. Optional: tmux (for tmux pane/popup mode), audio player (ffplay, mpv, afplay, or paplay) for immersive sound.

Method 1: Homebrew (macOS / Linux)

brew install cry8a8y/hushflow/hushflow
hushflow install

Method 2: Unix / macOS (curl)

curl -fsSL https://raw.githubusercontent.com/cry8a8y/HushFlow/main/install-remote.sh | bash

Method 3: Windows (PowerShell)

git clone https://github.com/cry8a8y/HushFlow.git; cd HushFlow; .\install.ps1

Method 4: npm / npx

npx hushflow install

✅ Verify Installation in 5 Seconds

1. Run hushflow doctor to verify your setup.
2. Restart your AI tool (e.g., Claude Code).
3. Send any Prompt.
4. First time? A guided setup wizard walks you through choosing your exercise and theme.
5. After setup — The breathing window appears automatically when the AI thinks.

🧘 Why HushFlow?

Typical developers face dozens of "dead moments" every day waiting for AI models to plan, edit, or test. Most fill these gaps with micro-distractions (scrolling, checking Slack) that break the flow state.

HushFlow turns them into recovery. Leveraging evidence-based breathing techniques, it naturally lowers heart rate and maintains your focus, all without leaving your terminal.

| Feature | HushFlow | Mindful-Claude | | :--- | :--- | :--- | | Integration | Native (Claude/Gemini/Codex) | Wrapper-only | | Experience | Separate Window / Tmux Pane | Main terminal only | | Performance | Shell Native (~3MB RAM) | Node.js Heavy | | Customization | 8+ Themes / Immersive Sound | Basic |

✨ Features

• 🧘 Auto-Mindfulness — Appears after a delay, disappears when AI finishes. Zero-click calm.
• 🎯 Focus-First — Runs in a separate window or tmux pane. Your terminal stays focused.
• 🛠️ Universal Integration — Native for Claude Code, Gemini CLI, and Codex CLI.
• 📊 Mindful Stats — Track your breathing sessions and keep your daily streak alive with hushflow stats.
• 🔔 Session Notifications — macOS notification after each session with exercise name, cycles completed, and duration.
• ⏸️ Permission-Aware — Automatically pauses when your AI asks for approval, resumes when you respond.
• 💻 Cross-Platform — macOS, Linux, and Windows. Optimized for Ghostty 1.3.1, iTerm2, Windows Terminal.
• 🫁 Breath Work — 4 built-in patterns: Coherent, Sigh, Box, and 4-7-8.
• 🎨 Custom Themes — 8+ themes (3 built-in + 5 community like Catppuccin, Dracula).
• 🎵 Immersive Audio — Zen-crafted soundscape with phase-specific breath cues.
• ⚡ Engineered for Speed — Pure Bash logic. Render path has zero external dependencies.

🖥️ Supported Terminals

| Platform | Terminals | Notes | |----------|-----------|-------| | macOS | Ghostty (optimized), iTerm2, Terminal.app | TrueColor recommended | | Linux | gnome-terminal, Konsole, xfce4-terminal, xterm, Ghostty | xdotool for window positioning | | Windows | Windows Terminal, PowerShell | Via Git Bash | | Fallback | Any terminal | Inline mode (no separate window) |

🎵 Immersive Audio

HushFlow features an optional built-in soundscape designed for deep immersion and functional guidance. Enable it with hushflow sound on.

Supported players: ffplay (FFmpeg), mpv, afplay (macOS built-in), paplay (PulseAudio/PipeWire).

• Inhale: Harmonic Bloom — A deep 60Hz swell with warming fireplace crackles.
• Hold: Tri-Harmonic Stillness — Interweaving resonances that eliminate flat tones.
• Exhale: Parabolic Recede — Silky 65Hz airflow that settles naturally like a tide.
• Complete: The Master Bell — A heavy 82Hz bronze bell struck by a mellow mallet.

Let the hum of a Tibetan bell dissolve your coding anxiety as the AI finishes its task.

📊 Usage Statistics

Track your progress and build a habit. Use hushflow stats to view your daily cycles, total mindful hours, and current streak.

📺 UI Modes

• 🪟 Window (Default) — Opens a companion terminal window.
• 📑 tmux pane — Splits a pane inside your current session.
• 🫧 tmux popup — Floating overlay (requires tmux 3.2+).
• ⌨️ Inline — Minimalistic rendering in your current terminal.

⌨️ Common Commands

hushflow config hrv    # Set Coherent Breathing
hushflow theme nord    # Apply Nord theme
hushflow animation orbit  # Set animation style
hushflow sound on      # Enable breath audio
hushflow wrap -- cmd   # Run breathing while a command executes
hushflow stats         # View session statistics
hushflow onboarding    # Re-run the first-time setup wizard
hushflow doctor        # Run health check
hushflow --version     # Show version

🧠 How It Works

HushFlow monitors your AI terminal hooks in the background:

1. 🔌 Hook Trigger: AI tool signals the start of agentic work.
2. ⏳ Smart Delay: Waits 5s to ensure you're actually waiting, not reading.
3. 🧘 Ritual: Opens a window/pane with smooth Bash animations.
4. 🔴 Cleanup: Automatically closes when the AI tool finishes.

[!TIP] View the Full Architecture & Flowchart for more technical details.

🔒 Transparency & Trust

HushFlow is designed to be completely non-intrusive:

• Hook Settings: Appends execution triggers to ~/.claude/settings.json, ~/.gemini/settings.json, and ~/.codex/hooks.json.
• Config Path: Per-tool preferences in ~/.<tool>/hushflow/config; custom themes, sounds, and stats in ~/.hushflow/.
• Session State: Uses a temporary .session file for state sync (auto-cleaned).
• Uninstall: Run hushflow uninstall to clean up all the above immediately.
• Privacy: Zero telemetry. 100% local execution.

📚 Advanced Docs

• Community Themes (Catppuccin, Dracula, Nord, Solarized, Gruvbox)
• Plugin API — Create custom animations
• Environment Variables — Advanced configuration
• Troubleshooting — Common issues & fixes

🤝 Contributing & Support

HushFlow is derived from Mindful-Claude. Contributions are welcome! Whether it's a new theme, plugin, or fix — check out CONTRIBUTING.md.

If HushFlow helps you stay calm, please give it a ⭐ — it helps others find the project.

MIT. See LICENSE for details.