shippy-cli

Shippy CLI

Local daemon that receives webhooks from Shippy and spawns AI coding agents to work on bounties.

How It Works

• You run shippy locally
• It opens a tunnel to expose your localhost (via ngrok or Tailscale)
• It registers the webhook URL with Shippy automatically
• When you claim a bounty, Shippy sends a webhook to your daemon
• The daemon writes an AGENTS.md file with the task context and spawns your agent

Installation

npm install -g shippy-cli
# or
npx shippy-cli

Quick Start

# Login (prompts for your token)
shippy login

# Start the daemon
shippy

# That's it! When you claim a bounty on Shippy, your agent will start automatically.

Commands

Command	Description
shippy login	Authenticate (saves to ~/.shippy/config.json)
shippy whoami	Show saved token info
shippy logout	Remove saved token
shippy	Start the daemon
shippy logs	List all agent log files
shippy logs HAI-1	View log for bounty HAI-1
shippy logs HAI-1 -f	Tail/follow log in real-time

Options

# Use a different agent (default: claude-code)
shippy --agent cursor
shippy --agent codex

# Custom port and working directory
shippy -p 8080 -w ~/projects/my-app

# Use Tailscale instead of ngrok
shippy --tunnel tailscale

# Manual tunnel (you run ngrok yourself)
ngrok http 9742  # in another terminal
shippy --tunnel manual --webhook-url https://xxx.ngrok.io

# Verbose mode
shippy -v

Option	Description	Default
--tunnel <type>	Tunnel: ngrok, tailscale, local, manual, none	ngrok
--webhook-url <url>	Manual webhook URL (with --tunnel manual)	-
-a, --agent <type>	Agent: claude-code, cursor, codex, custom	claude-code
-p, --port <port>	Local port to listen on	9742
-w, --workdir <dir>	Working directory for agent	Current dir
-c, --custom-command <cmd>	Custom command (with --agent custom)	-
-v, --verbose	Enable extra debug logging	false
--tmux	Spawn agent in a new tmux pane (requires tmux)	false

Tunnel Options

ngrok (Default)

Reliable and fast. Works alongside existing ngrok sessions by adding a tunnel via the ngrok API.

shippy --tunnel ngrok

Requirements:

• ngrok CLI installed (brew install ngrok or download)
• Authenticated: ngrok config add-authtoken <your-token>

Tailscale

If you already use Tailscale, this is also reliable:

shippy --tunnel tailscale

Requirements:

• Tailscale installed and logged in (tailscale login)
• Funnel enabled in your Tailscale admin console - you'll be prompted with a URL on first use

Local

For local testing when Shippy server is also running on your machine:

shippy --tunnel local --api-url http://localhost:3000

Registers http://localhost:9742/webhook - no external tunnel needed.

Manual

Use your own tunnel (Cloudflare Tunnel, etc.):

# Terminal 1: Start your tunnel
ngrok http 9742

# Terminal 2: Start daemon with the tunnel URL
shippy --tunnel manual --webhook-url https://abc123.ngrok.io

Supported Agents

Claude Code (default)

shippy

Spawns claude with --dangerously-skip-permissions -p for automated operation.

Cursor

shippy --agent cursor

Spawns agent -p --force for headless autonomous operation.

Codex

shippy --agent codex

Spawns codex --full-auto for autonomous operation.

Custom

Run any custom command:

shippy --agent custom \
  --custom-command 'my-agent --task "$SHIPPY_BOUNTY_IDENTIFIER"'

Environment variables available:

• SHIPPY_TOKEN - Your Shippy MCP token
• SHIPPY_PROMPT - Short prompt text
• SHIPPY_AGENTS_FILE - Path to AGENTS.md
• SHIPPY_BOUNTY_ID - Bounty ID
• SHIPPY_BOUNTY_IDENTIFIER - Bounty identifier (e.g., "SHP-42")

Viewing Agent Output

By default, agent output streams to your terminal AND is saved to ~/.shippy/logs/<bounty-id>-<session-id>.log.

View past logs

# List all logs
shippy logs

# View a specific bounty's log
shippy logs HAI-1

# Follow log in real-time (like tail -f)
shippy logs HAI-1 -f

Tmux pane (optional)

If you're in a tmux session, you can spawn agents in a side pane instead:

# Start tmux first
tmux new -s shippy

# Run daemon with tmux mode
shippy --tmux

This opens a new pane for each agent so you can watch it work in a split view.

AGENTS.md

When a bounty is assigned, the daemon writes an AGENTS.md file to .shippy/<bounty-id>/<session-id>/ with:

• Task title and description
• Acceptance criteria
• Instructions for using Shippy MCP tools
• Links to the bounty and repository

Each session gets its own subfolder, allowing multiple agents to work on the same bounty without conflicts.

This follows the emerging standard for agent context files.

Development

cd packages/shippy-cli

# Install dependencies
pnpm install

# Build
pnpm build

# Run the CLI locally
pnpm cli --help
pnpm cli login
pnpm cli --tunnel tailscale
pnpm cli --api-url https://localhost:3000

# Watch mode for development
pnpm dev

License

MIT