sprite-galaxy

README

✦ Sprite Galaxy

A whimsical, visually impressive TUI for visualizing and managing your Sprite network.

✦ SPRITE GALAXY ✦                                        [?] help  [q] quit
        .          ·                    ✧           .                ·
                        ╭──────────────────────╮
   ·          .    · · ·│● api-server        ◇│· · ·          ✧
                        ╰──────────────────────╯
             ·              · · · · · ·                   .
    ╔══════════════════════╗      ·       ╭──────────────────────╮
    ║● dev-database      ◆║· · · · · · · ·│○ staging-env       ◆│     ·
    ╚══════════════════════╝              ╰──────────────────────╯
  .                 ·           ✦                    ·          .
                                      ·                   ·
⠋ 3 sprites | 2 running | 1 public | 1 connection
[j/k] select  [HJKL] move node  [n] new connection  [enter] details  [?] help

Legend: ● running ○ stopped ◇ public ◆ private ═ selected

Features

• Galaxy View: See all your sprites as animated nodes floating in space
• Real-time Status: Running, cold, or paused - know at a glance
• Network Config: Toggle public/private access with a keypress
• Interactive Layout: Drag nodes with your mouse or move them with keyboard (HJKL)
• Visual Connections: Create custom connections between sprites for visualization
• Network Policy Editor: View and edit sprite network policies inline
• Port Detection: Automatically detects listening ports on running sprites
• Physics Animations: Sprites float and glow using Harmonica spring physics
• Connection Particles: Visualize network activity between connected sprites
• Health Dashboard: Real-time CPU, memory, disk, network, and process monitoring per sprite
• Sparkline Graphs: Rolling history of resource usage with delta indicators
• Health Indicators: At-a-glance status dots on galaxy nodes (green/yellow/red)
• Maximum Chaos Mode: Easter eggs, dancing sprites, and absurdist humor

Installation

Prerequisites

• Go 1.21 or later
• Sprite CLI installed and authenticated

From Source

# Clone the repository
git clone https://github.com/aezell/sprite-galaxy.git
cd sprite-galaxy

# Build
go build -o sprite-galaxy .

# Run
./sprite-galaxy

Using Go Install

go install github.com/aezell/sprite-galaxy@latest

Quick Start

1. Make sure you have the Sprite CLI installed and logged in:

   curl -fsSL https://sprites.dev/install.sh | bash
   sprite login
   

2. Create a sprite if you don't have one:

   sprite create my-sprite
   

3. Launch Sprite Galaxy:

   sprite-galaxy
   

4. Navigate with j/k, press Enter to view details, p to toggle public/private.

Keyboard Shortcuts

Galaxy View

Key	Action
j / ↓	Select next sprite
k / ↑	Select previous sprite
H / J / K / L	Move selected node (left/down/up/right)
Enter	View sprite details
n	Create new connection from selected sprite
x / d	Delete all connections from selected sprite
p	Toggle public/private
r	Refresh data
?	Show help
q	Quit

Detail View

Key	Action
e	Edit network policy JSON
h	Open health dashboard
n	Create new connection from this sprite
p	Toggle public/private
Ctrl+s	Save edited policy (when editing)
Esc	Back to galaxy / Cancel edit

Health Dashboard

Key	Action
Tab / 1-4	Switch section (processes/disk/network/logs)
j / k	Scroll within section
r	Manual refresh
p	Pause/resume auto-refresh
f	Cycle log filter (all/error/warn/info)
Esc	Back to detail view

Mouse Controls

Action	Effect
Click + Drag	Move sprite nodes around the canvas

Secret

Key	Action
↑↑↓↓←→←→BA	🎉 Party mode!

Data Storage

Sprite Galaxy stores user-defined connections locally:

~/.sprite-galaxy/
└── connections.json    # Your visual connections between sprites

These connections are purely visual and don't modify the actual sprites - they're just for your own organization and visualization purposes.

Documentation

• User Guide - Detailed usage instructions
• Sprites Documentation - Official Sprites docs

Built With

• Bubble Tea - TUI framework
• Lip Gloss - Styling
• Bubbles - UI components
• Harmonica - Physics-based animations

Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/sprite-galaxy.git
cd sprite-galaxy

# Install dependencies
go mod download

# Run in development
go run .

Project Structure

sprite-galaxy/
├── main.go                 # Entry point
├── model.go                # Bubble Tea model + state management
├── view.go                 # View rendering
├── sprites/
│   ├── types.go            # Data types, personalities, messages
│   └── client.go           # Sprite CLI wrapper (includes port detection)
├── health/
│   ├── types.go            # Health data structures and status types
│   ├── collector.go        # Health data collection (single + batched)
│   ├── parser.go           # Command output parsers
│   └── history.go          # Metric history ring buffer for sparklines
├── connections/
│   └── connections.go      # User-defined connection persistence
├── graph/
│   ├── layout.go           # Force-directed graph layout with physics
│   └── connections.go      # Connection line rendering
├── styles/
│   └── styles.go           # Lip Gloss styles and colors
├── effects/
│   └── background.go       # Space background, star field, pulses
├── animation/
│   ├── springs.go          # Harmonica spring animations
│   └── particles.go        # Particle system for effects
├── art/
│   └── pixel.go            # Pixel art definitions
├── components/
│   └── effects.go          # Visual effects (glitch, rainbow, etc.)
└── docs/
    └── USER_GUIDE.md       # User documentation

Making Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly: go build && ./sprite-galaxy
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Contribution Ideas

• Add health dashboard with real-time monitoring
• Add sprite creation modal
• Implement sprite deletion with confirmation
• Add more particle effects
• Create new sprite personalities
• Add more easter eggs
• Auto-detect connections from network traffic
• Port forwarding visualization
• Theme customization
• Connection labels/annotations
• Export/import connection layouts

Code Style

• Follow standard Go formatting (go fmt)
• Keep functions focused and well-named
• Add comments for complex logic
• Maintain the whimsical spirit!

Easter Eggs

There are several hidden features in Sprite Galaxy. Here's a hint:

• The Konami code does something special...
• Leave the app idle for a while...
• Make all your sprites public...

License

MIT License - see LICENSE for details.

Acknowledgments

• Charm for the amazing TUI libraries
• Sprites for the cloud sandbox platform
• The terminal art community for inspiration

---

Made with 💚 and maximum chaos

"contemplating the void since 2026"