Skip to content

alxmlv/yoloship

BranchesTags

Repository files navigation

YOLOShip

╭──────────────────────────────────────────────────────────╮
│  ██╗   ██╗ ██████╗ ██╗      ██████╗ ███████╗██╗  ██╗██╗██████╗  │
│  ╚██╗ ██╔╝██╔═══██╗██║     ██╔═══██╗██╔════╝██║  ██║██║██╔══██╗ │
│   ╚████╔╝ ██║   ██║██║     ██║   ██║███████╗███████║██║██████╔╝ │
│    ╚██╔╝  ██║   ██║██║     ██║   ██║╚════██║██╔══██║██║██╔═══╝  │
│     ██║   ╚██████╔╝███████╗╚██████╔╝███████║██║  ██║██║██║      │
│     ╚═╝    ╚═════╝ ╚══════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝╚═╝      │
│                                                                  │
│              Ship MVPs while you sleep                           │
╰──────────────────────────────────────────────────────────╯

Ship MVPs while you sleep. YOLOShip launches overnight AI coding missions — describe your idea, answer 3 quick questions, go to sleep, and wake up to a working prototype with a summary report.

What It Does

  1. You describe an idea: yoloship launch "Build a review request tool for local businesses"
  2. AI asks 3 refinement questions: Clarifies the use case, tech stack, and success criteria
  3. Generates an enriched prompt: Detailed implementation spec for the agent
  4. Launches Claude Code: In an isolated git worktree, with full autonomy
  5. Monitors progress: Every 90 minutes, checks status and sends notifications
  6. Morning report: 5-bullet summary of what got built, what's blocked, and what's next

Quick Start

# 1. Clone and install
cd yoloship
npm install

# 2. Run the setup wizard
npm run dev setup

# 3. Launch your first mission!
npm run dev launch "Build a CLI tool for managing bookmarks"

Installation

Prerequisites

  • Node.js 20+
  • Claude CLI installed (npm install -g @anthropic-ai/claude-code)
  • Git (for worktree support)
  • Docker (optional but recommended — enables isolated mission containers)

Setup

# Install dependencies
npm install

# Build
npm run build

# Run setup wizard
yoloship setup

The setup wizard will:

  1. Auto-detect the Claude CLI path
  2. Let you choose the default model (sonnet/opus/haiku)
  3. Configure max turns per mission (default: 50)
  4. Set the missions directory (default: ~/.yoloship/missions)
  5. Configure notifications (desktop/telegram/none)
  6. Configure auto PR creation (optional)
  7. Enable/disable Docker containerization (recommended if Docker is installed)

No API key needed! YOLOShip uses the Claude CLI directly, so it works with your Claude Max/Pro subscription.

Commands

yoloship setup

Interactive setup wizard to configure YOLOShip. Run this first!

yoloship setup

yoloship launch "idea"

Launch a new overnight mission. Starts an interactive Q&A flow:

yoloship launch "Build a CLI tool for managing bookmarks"

yoloship status

Live TUI dashboard showing all missions:

yoloship status

Also shows whether the background monitor daemon is running.

Keyboard shortcuts:

  • j/k - Navigate up/down
  • l - View logs
  • x - Kill mission
  • r - View report
  • q - Quit

yoloship list

Table view of all missions:

yoloship list

yoloship report <id>

5-bullet morning summary:

yoloship report yolo-abc123

yoloship continue <id> "instructions"

Resume a completed/failed mission with new instructions:

yoloship continue yolo-abc123 "Add tests and fix the login bug"

yoloship kill <id>

Stop a running mission:

yoloship kill yolo-abc123

yoloship watch [mission-id]

Live log streaming for active missions:

# Watch the most recently launched active mission
yoloship watch

# Watch a specific mission
yoloship watch yolo-abc123

Features:

  • Real-time log streaming (updates every 500ms)
  • Header with mission ID, task, and elapsed time
  • Status badge (RUNNING/COMPLETE/FAILED)
  • Last 30 log lines with auto-scroll
  • Keyboard shortcuts: q to quit, k to kill mission
  • Auto-exits 3 seconds after mission completes

yoloship clean [--all]

Remove old worktrees to reclaim disk space:

# Remove worktrees for missions completed/killed more than 7 days ago
yoloship clean

# Remove worktrees for ALL non-running missions
yoloship clean --all

yoloship docker [build|clean|status]

Manage the Docker image used for containerized missions:

# Build the mission container image (do this once after install)
yoloship docker build

# Show image size, running containers, Docker version
yoloship docker status

# Remove the image + any stopped yoloship-* containers
yoloship docker clean

yoloship preview [mission-id]

Generate a preview (screenshot, recording, or text snapshot) of what a mission built:

# Preview the most recently completed mission
yoloship preview

# Preview a specific mission
yoloship preview yolo-abc123

Preview must be enabled first via yoloship setup or config. See Preview Generation below for details.

Preview Generation

After a mission completes, see what was built by running yoloship preview.

How to Enable

  1. Run yoloship setup and select Yes at the "Preview Generation" step
  2. Or add to ~/.yoloship/config.json: 
    { "preview": { "enabled": true, "port": 4321 } }

What It Does

  1. Loads the mission and inspects the worktree to detect what was built
  2. Detects the current environment (macOS, Linux with display, or headless VPS)
  3. Runs the appropriate preview strategy:
App Type macOS / Linux+Display Headless (VPS)
Web app Start dev server, Playwright screenshot + 15s video Start dev server, curl HTTP snapshots
CLI/TUI asciinema terminal recording + text snapshot script text capture
Other Text output capture Text output capture
  1. Saves output to the mission's preview/ directory
  2. On macOS, auto-opens the screenshot

Prerequisites

Tool Purpose Install
Playwright Web app screenshots & video npx playwright install chromium
asciinema Terminal recordings for CLI/TUI apps brew install asciinema (macOS) or pip install asciinema

Both are optional. Without them, preview falls back to text-based snapshots.

Platform Support

Platform Screenshots Video Terminal Recording Text Snapshots
macOS Yes Yes Yes Yes
Linux + Display Yes Yes Yes Yes
VPS / Headless No No No Yes

Output Files

Preview files are saved to the mission's preview/ directory:

  • screenshot.png — Full-page screenshot (web apps, requires Playwright)
  • demo.webm — 15-second video recording (web apps, requires Playwright)
  • demo.cast — asciinema recording (CLI/TUI, requires asciinema)
  • output.txt — Text snapshot of CLI output
  • http-snapshot.txt — HTTP response snapshot (headless web apps)

How It Works

Git Worktrees

Each mission runs in an isolated git worktree, so you can have multiple missions running without conflicts. The agent commits its work as it goes.

Claude CLI Integration

YOLOShip spawns Claude Code via the CLI with --dangerously-skip-permissions and streams the JSONL output to track progress. Each mission gets up to 50 agent turns by default (configurable via yoloship setup).

Mission State Machine

Missions progress through states:

  • pending -> running -> complete
  • Or: running -> rate_limited -> running (auto-resume)
  • Or: running -> failed -> running (manual retry)
  • Or: running -> killed

Background Monitor Daemon

A background daemon monitors running missions every 90 minutes. It:

  • Checks if agent processes are still alive
  • Detects stuck missions (no commits for too long)
  • Sends notifications (desktop or Telegram) on completion/failure
  • Survives terminal close (runs as a detached process)

Docker Isolation

YOLOShip runs Claude Code with --dangerously-skip-permissions — which is exactly what it sounds like. Without isolation, the agent has full access to your host filesystem.

With Docker enabled (default when Docker is available), each mission runs in a fresh container:

docker run --rm \
  -v ~/.claude:/root/.claude:ro \   # auth tokens (read-only)
  -v <worktree>:/workspace \        # mission code (read-write)
  --cpus 2 --memory 4g \            # resource limits
  yoloship-mission \
  claude --dangerously-skip-permissions ...

The agent can only touch its own worktree — not your home directory, not the rest of the VPS. --dangerously-skip-permissions stays dangerous, just inside a box.

First-time setup:

# Build the mission image once
yoloship docker build

# Verify Docker is ready
yoloship docker status

Toggle off (if Docker isn't available):

// ~/.yoloship/config.json
{ "containerize": false }

Or re-run yoloship setup and choose No at the Docker step.

Auto PR Creation

When a mission completes successfully, YOLOShip can automatically create a GitHub PR:

  • Uses gh CLI if available and authenticated
  • Falls back to GitHub API with a personal access token
  • PR title is taken from the first line of SUMMARY.md (or the mission task)
  • PR body contains the full SUMMARY.md content
  • PR URL is included in completion notifications and reports

Configure during setup or add to config:

{
  "autoCreatePr": true,
  "githubToken": "ghp_..."  // Optional: only needed if gh CLI not available
}

Project Context Injection

Add a .yoloship.md file to your project root to provide context to the AI agent:

# My Project

## Tech Stack
- Node.js + TypeScript
- Express backend
- React frontend

## Coding Standards
- Use ESLint + Prettier
- Write tests for all new features
- Follow existing patterns

## Important Files
- src/app.ts - main entry point
- src/routes/ - API routes

When launching a mission from a directory with .yoloship.md, the content is automatically prepended to the prompt:

[Project Context from .yoloship.md]
<your context>
[End Project Context]

<enriched prompt>

This helps the agent understand your project's conventions and avoid common mistakes.

Configuration

Configuration is stored in ~/.yoloship/config.json:

{
  "claudePath": "/usr/local/bin/claude",
  "defaultModel": "sonnet",
  "maxTurns": 50,
  "missionsDir": "/home/user/.yoloship/missions",
  "containerize": true,
  "notifications": {
    "type": "desktop"
  },
  "preview": {
    "enabled": false,
    "port": 4321
  },
  "autoCreatePr": true,
  "githubToken": "ghp_..."
}

Set containerize: false to run Claude directly on the host (no Docker required).

For Telegram notifications:

{
  "notifications": {
    "type": "telegram",
    "telegram": {
      "botToken": "123456:ABC...",
      "chatId": "789..."
    }
  }
}

Data Storage

YOLOShip stores data in ~/.yoloship/:

  • config.json - Configuration file
  • yoloship.db - SQLite database with mission metadata
  • monitor.pid - PID file for the background monitor daemon
  • missions/<id>/ - Mission-specific data
    • worktree/ - Git worktree for the mission
    • agent.jsonl - Raw agent output stream

Development

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Run tests
npm test

# Type check
npm run lint

# Build for production
npm run build

Tech Stack

  • Node.js + TypeScript - Core runtime
  • Ink v5 - React for CLI (TUI components)
  • better-sqlite3 - Local SQLite database
  • Commander - CLI argument parsing
  • Claude CLI - For AI interactions (no SDK needed)
  • node-notifier - Desktop notifications
  • Docker - Mission container isolation (optional)

License

MIT

Built with AI assistance. Ship MVPs while you sleep.

About

YOLOship | Ship MVPs while you sleep. A YOLO coding experiment.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages