✦ starwar

Navigate your codebase as a 3D star map in the terminal.

Each file is a star. Brightness = how often it's edited. Heat color = how recently. Directories form spiral arms. Fly through your codebase like a spaceship.

Install

npm install -g starwar-cli

Usage

# In any git repo
starwar

# With a theme
starwar --theme nebula

# Point at a specific directory
starwar ~/projects/my-app --theme matrix

# Quick mode (skip git history, faster on huge repos)
starwar --quick

Controls

| Key | Action | |---|---| | arrows / hjkl | Rotate view | | w / s | Zoom in / out | | space | Pause / resume rotation | | / | Search for a file and warp to it | | tab | Cycle themes | | r | Reset view | | q / ctrl+c | Quit |

Themes

• Tron — cyan grid, hot orange stars (default)
• Matrix — green on black, hacker vibes
• Nebula — pink and purple, space feels
• Retro — monochrome terminal aesthetic
• Sunset — warm oranges and cool purples
• Midnight — soft blues, easy on the eyes

How It Works

1. Scans your git repo for all tracked files
2. Pulls commit history to calculate edit frequency and recency
3. Positions files in a 3D spiral galaxy (directories = arms, files = stars)
4. Projects the 3D galaxy onto your terminal in real time
5. You fly through it

Star brightness is driven by commit count. Star color is driven by how recently the file was touched (hot = recent, cold = old). File size determines star size.

Requirements

• Node.js >= 14
• A git repository
• A terminal with 256-color support (iTerm2, Windows Terminal, Kitty, Alacritty, etc.)

License

MIT