🛸 Space Station

Space Station is a high-performance development orchestrator designed to manage multiple parallel repository environments ("Planets") on a single machine. It is built for engineers and AI agents who need to context-switch between multiple PRs, issues, and experiments without the overhead of git checkout or "dirty" worktrees.

---

✨ Features

• Parallel Universes (Planets): Manage up to 8 independent worktrees of your repository, each with its own isolated environment and local database.
• Mission Dashboard: A real-time, interactive TUI for monitoring PR status, CI checks, GitHub issues, and local activity across all planets.
• AI Agent Native: Seamlessly launch AI agents (Claude Code, Gemini, Codex) in isolated environments with one command.
• Interactive Interactivity: Mouse-aware selection, trackpad scrolling, and instant "Jump to Planet" tmux pane focus.
• Automated Infrastructure: One-click setup for dependencies, worktrees, and isolated .env.local files.
• Natural Hooks: Automate repetitive tasks (like PR auto-approval) using simple shell scripts.

---

🚀 Quick Start

1. Prerequisites

• macOS or Linux
• Bun (Runtime)
• Homebrew (For dependency management)
• gh (GitHub CLI, authenticated)
• Tmux (For the Command Center)

2. Installation

Clone the repository and link the ss command:

git clone https://github.com/pullflow/space-station.git ~/space-station
cd ~/space-station
bun install
# Add to your ~/.zshrc or ~/.bashrc:
# export PATH="$HOME/space-station:$PATH"

3. Initialize Your Environment

Run the setup wizard in your project root:

ss init

This will create your ss.yaml and guide you through selecting the number of planets and configuring your preferred AI agents.

4. Orchestration

Launch your universe of planets:

ss setup

This will verify system dependencies, initialize the "Hub" (bare repo), create your planets, and run any local initialization hooks.

---

🎮 The Mission Dashboard

The interactive heart of Space Station. Use it to lead your mission from the bridge.

ss dash

Key	Action
Tab	Cycle focus between Planets, Issues, PRs, and Hooks
↑ / ↓	Navigate items in the focused container
Wheel	Scroll any container under the mouse cursor
Enter	Jump to Planet (tmux) or Open in Browser (GitHub)
Click	Instantly select an item or jump to a planet's pane
C	Launch the 4-pane Command Center (Tmux Grid)
?	Toggle the Help Overlay
Ctrl+C	Return to base

---

🛠️ Command Reference

Command	Alias	Description
ss setup		Full infrastructure initialization
ss dash		Launch the interactive mission dashboard
ss status	st	Overview of all planets and current branches
ss prs		Browse and checkout PRs to specific planets
ss agent	ag	Launch an AI agent on a planet
ss land	l	Reset a planet to main and launch an agent
ss reset		Force-reset a planet to main and re-run init hooks
ss doctor	dx	Verify your Space Station installation

---

🤖 Automation & Hooks

Space Station can automate your workflow using simple shell scripts. Drop executable files into the hooks/ directory, and they will fire automatically when the dashboard detects events.

Available Triggers

• pr_assigned.sh: Fired when a PR is assigned to you.
• pr_review_requested.sh: Fired when someone requests your review.
• pr_approved.sh: Fired when a PR is approved.
• pr_checks_passed.sh: Fired when all CI checks pass on a PR.

Example: Auto-Approve & Notify

Create hooks/pr_review_requested.sh:

#!/usr/bin/env bash
# Auto-approve any PR requested from me (if not a draft)
if [ "$SS_PR_DRAFT" != "true" ]; then
  ss prs approve "$SS_PR_NUMBER"
  say "PR $SS_PR_NUMBER auto-approved"
fi

Note: Hooks are local-only and gitignored by default.

---

🛸 The "Multi-Planet" Workflow

Why context-switch in one folder when you can have a whole solar system?

1. Dashboard View: Run ss dash to see your assigned issues and incoming PRs.
2. Land on Mars: Select a PR and checkout to mars.
3. Deploy Agent: Run ss agent mars to have an AI start working on that PR in isolation.
4. Stay Focused: While the agent works on mars, you can continue your own work on earth or review a teammate's PR on mercury.
5. Tmux Integration: Use ss console (or press C in the dashboard) to see 4 planets side-by-side in a single tmux window.

---

🤝 Contributing

We welcome contributions! Space Station is built with minimal dependencies and raw ANSI rendering for maximum performance. Check out the src/ directory to see how we manage the TUI logic without heavy frameworks.

Development

bun install
npm run test       # Run tactical test suite
npm run typecheck  # Verify type safety

---

📜 License

MIT © Zak Mandhro & Space Station Contributors.