Exeggutor — Terminal Multiplexer & Git Worktree Manager
Local-first, subscription-free workspace orchestration dashboard.

---

Features

Multi-Workspace Engine	Switch projects and automatically swap terminal grids, paths, and configurations.
Tabbed Terminal Grid	Spawn unlimited terminals, split horizontally/vertically, persist sessions across restarts.
Observer Sidebar	Real-time terminal state monitoring (Active, Waiting, Idle, Errored) with live text previews.
Git Worktree Isolation	Run terminals inside branch-isolated worktree folders — no checkout overhead, no conflicts.
Remote Access	Expose the dashboard over your Tailscale tailnet via --tailscale flag.
Persistent State	Workspaces, terminals, and layouts survive server restarts and package upgrades.

---

Screenshots

Workspace Management

Switch between registered workspaces, each with its own terminal grid, path mapping, and branch configuration.

Git Branch Selector

Create and switch branches per-terminal. New branches automatically spin up an isolated git worktree — zero context switching.

Zero-State Onboarding

A clean welcome screen guides you through registering your first workspace and getting started in seconds.

Mobile View

Responsive layout with a slide-out sidebar drawer and single-terminal tabbed view for on-the-go access.

---

Architecture

┌──────────────────────────────────────────────────────┐
│                   Exeggutor CLI                        │
│  (bin/exeggutor.js — server lifecycle, flags, tasks)  │
└──────────┬───────────────────────────────────────────┘
           │ starts / stops
┌──────────▼───────────────────────────────────────────┐
│                 Backend (Fastify)                      │
│  Node.js + Fastify + WebSocket + node-pty             │
│  ┌────────────┐ ┌──────────┐ ┌─────────────────┐     │
│  │  Workspace  │ │  PTY     │ │  Git Worktree   │     │
│  │  Manager    │ │  Manager  │ │  Manager        │     │
│  └────────────┘ └──────────┘ └─────────────────┘     │
│  ┌──────────────────────────────────────────────┐     │
│  │  Tailscale Detection (optional)               │     │
│  │  --tailscale flag → bind 0.0.0.0             │     │
│  │  /api/tailscale/status → frontend badge      │     │
│  └──────────────────────────────────────────────┘     │
└──────────┬───────────────────────────────────────────┘
           │ HTTP / WebSocket
           │  127.0.0.1:17492 (normal)
           │  <tailscale-ip>:17492 (remote)
┌──────────▼───────────────────────────────────────────┐
│               Frontend (Vite + React)                  │
│  xterm.js · react-mosaic-component · Tailwind CSS    │
│  Terminal Grid · Observer Sidebar · Branch UI        │
│  Tailscale IP badge (when --tailscale mode active)   │
└──────────────────────────────────────────────────────┘

Stack

Layer	Technology
Frontend	Vite · React · TypeScript · Tailwind CSS · xterm.js · react-mosaic-component
Backend	Node.js · Fastify · Fastify WebSocket · node-pty
State	Persistent JSON (~/.exeggutor-sessions.json)

---

Getting Started

# Install globally
npm install -g @ts47andres/exeggutor

# Start the dashboard
exeggutor

# Open in browser
exeggutor --open

# Stop the server
exeggutor --stop

# Check server status
exeggutor --status

Once the dashboard loads, register a project directory with a name and path, and you're ready to go.

---

Remote Access (Tailscale)

Exeggutor can be exposed securely over your Tailscale tailnet, allowing you to access the dashboard from any device on your tailnet via a browser.

# Start with Tailscale remote access enabled
exeggutor --tailscale

This binds the server to 0.0.0.0 and makes it reachable at http://<tailscale-ip>:17492 from any device on your tailnet. The frontend header shows a Tailscale IP badge (with copy-to-clipboard) when in this mode.

Authenticating from a Remote Browser

When accessing from a remote device (e.g., phone browser), you'll see an authentication page. To sign in:

# On the host machine, print the auth token
exeggutor --show-token

Copy the token and paste it into the input field on the authentication page, then click Submit. The token is stored in your browser's localStorage so you only need to do this once per browser.

Note: Tailscale must be installed and connected on the host machine. The badge only appears when --tailscale mode is active.

---

CLI Reference

Server Lifecycle

Command	Description
exeggutor or exeggutor --start	Start servers in background (normal mode, localhost only)
exeggutor --stop or exeggutor --kill	Stop all running servers
exeggutor --restart	Restart all servers
exeggutor --status or exeggutor -s	Show server status and workspace list
exeggutor --open	Open dashboard in default browser
exeggutor --log	Show recent server logs
exeggutor --version or exeggutor -v	Show version
exeggutor --help or exeggutor -h	Show help

Remote Access

Command	Description
exeggutor --tailscale	Start with Tailscale remote access enabled
exeggutor --show-token	Print the auth token for remote browser login

Workspace Management

Command	Description
exeggutor --workspaces or exeggutor -w	List all workspaces
exeggutor --create-workspace <name> <path>	Register a new workspace
exeggutor --delete-workspace <hash>	Delete a workspace and all its terminals

Terminal Management

Command	Description
exeggutor --terminals <hash>	List terminals in a workspace
exeggutor --add-terminal <hash> [name]	Add a new terminal to a workspace
exeggutor --rename <ws-hash> <term-hash> <new-name>	Rename a terminal
exeggutor --close <ws-hash> <term-name-or-hash>	Close a terminal

Service Management

Command	Description
exeggutor --install-service	Install auto-start on system boot
exeggutor --remove-service	Remove auto-start service

---

Data Persistence

File	Location	Purpose
~/.exeggutor.json	User home directory	Runtime configuration (port, auth token, backend PID)
~/.exeggutor-sessions.json	User home directory	Workspaces, terminals, and layout state
~/.exeggutor-logs/	User home directory	Server log files
~/.exeggutor-worktrees/	User home directory	Temporary git worktree directories

Data survives server restarts, package upgrades, and uninstall/reinstall cycles.

---

Development

See CONTRIBUTING.md for coding conventions, comment rules, and local-first principles.

# Build all packages
npm run build

# Start in development mode
npm run dev