🛰️ Space Station

Atomic Mission Control for Parallel Operations.

Space Station is a high-performance terminal orchestrator designed to manage multiple parallel development environments ("Planets") within a single repository. By leveraging Git Worktrees and a high-fidelity TUI, it eliminates context-switching overhead and enables seamless multi-tasking.

🚀 Quick Start

Space Station is built with Bun and requires the GitHub CLI and Tmux.

1. Install

bun add -g space-station

Also supports installation via npm, pnpm, or yarn.

2. Initialize

Run the init command inside any Git repository to transform it into a Space Station.

space-station init

3. Launch

Open the Command Center to start orchestrating.

space-station console

✨ Key Features

🪐 Planet Architecture (Git Worktrees)

Stop stashing and switching branches. Space Station maintains multiple parallel clones ("Planets") of your repository. Work on a feature in mercury, review a PR in venus, and run tests in earth—all simultaneously.

⚡ Smart Port Isolation

Each Planet is assigned a dedicated port range (e.g., 8000, 9000, 10000). This allows you to run multiple versions of your stack in parallel without port collisions.

🛠️ Interactive Command Center

A powerful Tmux-based dashboard that puts your PRs, Issues, and Planet status in a single unified view. Choose from multiple layouts: 2x2, 3x3, Sidebar, or 2x1.

🤖 Agent Ready

Designed for the age of AI agents. Use space-station land <planet> to instantly prepare an environment and hand it off to an agent for task execution.

🧩 Extensible

Built to be extended. Add new agents, custom dashboard hooks, or planet templates. See EXTENDING.md for the guide and LLM instructions.

🔄 Auto-Update & Management

The CLI automatically detects your installation method and prompts you to upgrade whenever a new version is released. Keep your mission control up to date with zero effort.

⌨️ Command Reference

| Command | Alias | Description | | :--- | :--- | :--- | | space-station dash | d | Live dashboard of PRs, Issues, and GitHub Actions. | | space-station console | c | Launch the Tmux Command Center grid. | | space-station land <planet> | l | Reset a planet to main and launch an agent. | | space-station status | s | Overview of all active Planets and their branches. | | space-station prs | p | Interactive PR browser and instant checkout. | | space-station agent <planet>| a | Resume or start an agent session on a planet. | | space-station reset <planet>| r | Hard sync a planet with origin/main. | | space-station update | | Manually check for and install updates. |

🔧 Advanced Workflow patterns

Planet Initialization Hooks

Automate environment setup by adding a space-station-init.sh script to your repo. Space Station runs this during planet creation or reset.

#!/usr/bin/env bash
source ".env.planet" # Injected by Space Station

# Update your local env with the planet's isolated port
sed -i "s/^PORT=.*/PORT=${SS_PLANET_BASE_PORT}/" .env.local

# Clean install and migrate
bun install && bun x prisma migrate dev

System Event Hooks

Trigger local automation on GitHub events by adding scripts to the ./hooks directory:

• pr_review_requested.sh
• pr_merged.sh
• action_failed.sh

🏗️ Internal Structure

Space Station organizes your workspace using a bare repository and multiple worktrees:

/your-project/
├── .hub/           # The bare repository (Shared history)
├── mercury/        # Planet 1 (Worktree)
├── venus/          # Planet 2 (Worktree)
├── earth/          # Planet 3 (Worktree)
└── package.json    # Shared configuration

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to get started.

📄 License

This project is licensed under the MIT License.