{"id":51143775,"url":"https://github.com/kestalkayden/terminal-flow","last_synced_at":"2026-06-26T01:02:25.739Z","repository":{"id":366202021,"uuid":"1061502810","full_name":"kestalkayden/terminal-flow","owner":"kestalkayden","description":"a TUI designed for hyprland that lets you colorize ascii art with cool effects right in your terminal!","archived":false,"fork":false,"pushed_at":"2026-06-20T17:42:06.000Z","size":2806,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T19:13:24.785Z","etag":null,"topics":["animation","ascii-art","cli","colorizer","curses","hyprland","python","ricing","terminal","terminal-art","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kestalkayden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T02:21:05.000Z","updated_at":"2026-06-20T17:42:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kestalkayden/terminal-flow","commit_stats":null,"previous_names":["kestalkayden/terminal-flow"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kestalkayden/terminal-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestalkayden%2Fterminal-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestalkayden%2Fterminal-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestalkayden%2Fterminal-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestalkayden%2Fterminal-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kestalkayden","download_url":"https://codeload.github.com/kestalkayden/terminal-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestalkayden%2Fterminal-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34798183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","ascii-art","cli","colorizer","curses","hyprland","python","ricing","terminal","terminal-art","tui"],"created_at":"2026-06-26T01:02:21.883Z","updated_at":"2026-06-26T01:02:25.623Z","avatar_url":"https://github.com/kestalkayden.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# terminal-flow\n\n![Demo](assets/terminal-flow-logo.gif)\n\n\u003e *I wanted something more customizable for hyprland, so I created this with love, dark magic, and way too much caffeine.* ☕✨\n\nA colorful Python terminal user interface (TUI) application that displays ASCII text files with dynamic rainbow animations and visual effects. Built with pure Python curses for zero external dependencies and optimal performance.\n\n## Features\n\n### Performance Optimized\n- **Zero External Dependencies** - Pure Python standard library implementation\n- **Curses-based** - Flicker-free animation using optimized screen updates\n- **Variable FPS** - Choose between 5, 10, 30, or 60 FPS for performance tuning\n- **Memory Efficient** - Minimal resource usage suitable for 24/7 operation\n\n### Animation Modes\n- **Wave** - Rainbow wave effect flowing horizontally across ASCII art\n- **Spin** - Colors rotate around the center point using polar coordinates\n- **Pulse** - Ripple effects pulsing outward from the center\n- **Flux** - Uniform color cycling across all characters simultaneously\n- **Morph** - 3D wave field animation with mathematical wave propagation\n\n### Color System\n- **Prism Colors** - Full rainbow spectrum with HSV color generation (default)\n- **Monochromatic Gradients** - 9 color schemes: red, blue, green, yellow, purple, cyan, gray, pink, orange\n- **256-Color Support** - Rich color depth with 8-color terminal fallback\n\n### File Management\n- **Smart File Selection** - Random selection by default, specific file targeting, or auto-cycling\n- **Text Directory Support** - Reads ASCII art from customizable text directory\n- **UTF-8/ASCII Support** - Automatic encoding detection with fallback handling\n\n## Installation\n\n### Prerequisites\n- Python 3.8 or higher\n- Terminal with curses and color support\n- TTY environment (not compatible with dumb terminals)\n\n### Install with pipx (Recommended)\n```bash\n# Install pipx if you don't have it\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n\n# Install terminal-flow\npipx install git+https://github.com/kestalkayden/terminal-flow.git\n```\n\n### Alternative Installation\n```bash\n# Clone and install locally\ngit clone https://github.com/kestalkayden/terminal-flow.git\ncd terminal-flow\npip install -e .\n```\n\n## Usage\n\n### Basic Usage\n```bash\n# Run with default settings (random file, wave mode, rainbow colors)\nterminal-flow\n\n# Display specific file with pulse animation and red gradient\nterminal-flow --file spin --mode pulse --color red\n\n# Auto-cycle through files with spin mode and blue colors\nterminal-flow --cycle 15 --mode spin --color blue --hd\n\n# Minimal CPU usage for 24/7 ambient display with flux mode\nterminal-flow --uld --cycle --mode flux --color orange\n```\n\n### Command Line Options\n```bash\nterminal-flow --help                    # Show help\nterminal-flow --mode wave               # Animation mode: wave, spin, pulse, flux, morph\nterminal-flow --color red               # Color scheme: red, blue, green, yellow, purple, cyan, gray, pink, orange\nterminal-flow --speed 1.5               # Animation speed multiplier\nterminal-flow --file spin             # Display specific file (spin.txt)\nterminal-flow --cycle 30                # Auto-cycle files every 30 seconds\nterminal-flow --ld                      # Low definition (10 FPS, default)\nterminal-flow --md                      # Medium definition (30 FPS)\nterminal-flow --hd                      # High definition (60 FPS)\nterminal-flow --uld                     # Ultra-low definition (5 FPS)\n```\n\n### Performance Options\n- `--uld` - Ultra-low definition: 5 FPS (minimal CPU usage)\n- `--ld` - Low definition: 10 FPS (default, efficient)\n- `--md` - Medium definition: 30 FPS (smooth animation)\n- `--hd` - High definition: 60 FPS (maximum smoothness)\n\n### File Selection\n- `--file \u003cname\u003e` - Display specific file (e.g., `--file spin` for spin.txt)\n- `--cycle [seconds]` - Auto-cycle through files (default: 30 seconds)\n- No options: Random file selection from text/ directory\n\n### Animation \u0026 Color Options\n- `--mode \u003cmode\u003e` - Animation mode: wave, spin, pulse, flux, morph (default: wave)\n- `--color \u003cscheme\u003e` - Color scheme: red, blue, green, yellow, purple, cyan, gray, pink, orange (default: rainbow)\n- `--speed \u003cmultiplier\u003e` - Animation speed (default: 1.0)\n\n### Runtime Controls (while application is running)\n- **Left Arrow** - Navigate to previous file\n- **Right Arrow** - Navigate to next file\n- **C/c** - Cycle through color schemes (rainbow → red → blue → green → yellow → purple → cyan → gray → pink → orange)\n- **M/m** - Switch animation modes (wave → spin → pulse → flux → morph)\n- **Q/ESC** - Quit application\n\n## Text Files\n\nThe application includes a built-in `text/` folder for your ASCII art files:\n```\ntext/\n├── spin.txt           # Project welcome message\n├── arch.txt           # Arch Linux logo\n├── nyan.txt           # Nyan cat animation\n├── spiral.txt         # Geometric spiral pattern\n├── heart.txt          # Unicode heart art\n├── galaxy.txt         # Cosmic galaxy art\n└── ... (11 files total)\n```\n\n**File Selection Modes:**\n- **Default**: Random file selection from available .txt files\n- **Specific**: Use `--file \u003cname\u003e` to target a specific file (e.g., `--file spin` for spin.txt)\n- **Cycling**: Use `--cycle [seconds]` to automatically rotate through all files\n\nSimply drop your `.txt` files into the `text/` directory and terminal-flow will handle the rest!\n\n## Examples\n\n### Animation Mode Combinations\n```bash\n# Wave mode with blue gradient - horizontal flowing effect\nterminal-flow --mode wave --color blue\n\n# Spin mode with orange gradient - spinning around center point\nterminal-flow --mode spin --color orange\n\n# Pulse mode with purple gradient - ripple effects from center\nterminal-flow --mode pulse --color purple\n\n# Flux mode with pink gradient - uniform color cycling\nterminal-flow --mode flux --color pink\n\n# Morph mode with green gradient - 3D wave field animation\nterminal-flow --mode morph --color green\n```\n\n### Performance \u0026 File Management\n```bash\n# High-performance cycling display for presentations\nterminal-flow --hd --cycle 10 --mode spin\n\n# Energy-efficient 24/7 display\nterminal-flow --uld --cycle 60 --mode flux --color cyan\n\n# Interactive file exploration (use arrow keys to navigate)\nterminal-flow --file spin --mode wave\n\n# Fast animation with specific color scheme\nterminal-flow --speed 2.0 --mode pulse --color red --md\n```\n\n### Creative Combinations\n```bash\n# Slow, meditative orange flux for background ambiance\nterminal-flow --speed 0.5 --mode flux --color orange --ld\n\n# Rapid rainbow spin for dynamic displays\nterminal-flow --speed 1.5 --mode spin --hd\n\n# Gentle blue pulse effect for focus sessions\nterminal-flow --mode pulse --color blue --speed 0.8\n\n# Cycling green wave for nature-themed displays\nterminal-flow --cycle 20 --mode wave --color green\n```\n\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by cmatrix, terminal-rain-lightning and other curses animation projects\n- ASCII art community for creative text designs\n- Python curses library documentation and examples","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestalkayden%2Fterminal-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkestalkayden%2Fterminal-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestalkayden%2Fterminal-flow/lists"}