# Starfleet Sessions

> Ship session and workspace management — spawning ships, session attach/stop, git worktrees, web console, deployment. Load when launching/administering ships or managing the fleet web console.

- Skill: `mpbt-hq/starfleet-sessions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mpbt-hq/starfleet-sessions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mpbt-hq/starfleet-sessions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mpbt-hq (https://skillmd.com/u/mpbt-hq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mpbt-hq/starfleet-sessions

---


# starfleet-sessions — ship sessions, worktrees, web console

Spawning and managing ships, isolated worktrees, and the fleet web console.
Comms/task core lives in the **`starfleet`** and **`starfleet-tasks`** skills.

## Ship sessions

| Subcommand | Purpose |
|---|---|
| `run [--flagship\|--name <id>] [--client claude\|opencode]` | Start an AI ship session |
| `session list` | List running detached sessions |
| `session attach <id>` | Attach terminal to a detached session |
| `session stop <id>` | Kill a detached session + release ship name |

Background ships never prompt on their console (see the starfleet-instructions working
practices) — hand them a task via the dashboard/comms, not as extra CLI args.

## Git worktrees

| Subcommand | Purpose |
|---|---|
| `worktree add <repo> [name]` | Create a per-task git worktree |
| `worktree list` | List worktrees |
| `worktree remove <path>` | Remove a worktree |
| `worktree prune` | Garbage-collect stale worktrees |

## Web console & setup

| Subcommand | Purpose |
|---|---|
| `web start/stop/restart/autostart` | Fleet web console (mobile-first) |
| `genesis-init [dir]` | Bootstrap a workspace from nothing |
| `self-install` | Clone/pull + build + symlink starfleetctl |
| `sop install-starfleet` | Install/update SOP fragments and skills |

## Deployment

```bash
# Phase A: genesis (from an existing binary)
starfleetctl genesis-init .

# Phase B: bootstrap (from the committed script)
./starfleet-bootstrap
```

Everything under `.starfleet-ai/` is gitignored. Re-run `./starfleet-bootstrap` anytime to update.