Shippy CLI

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

How It Works

1. You run shippy locally
2. It opens a tunnel to expose your localhost (via ngrok or Tailscale)
3. It registers the webhook URL with Shippy automatically
4. When you claim a bounty, Shippy sends a webhook to your daemon
5. 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