@hotshot/server

Standalone HTTP + WebSocket server for AI-powered component editing with Hotshot.

This package provides a framework-agnostic server that works with plain HTML, Rails, Vue, Svelte, and any other web framework—no Vite required.

Installation

# Global installation
npm install -g @hotshot/server

# Or use directly with npx
npx @hotshot/server

Quick Start

1. Start the server in your project directory:

cd /path/to/your/project
npx @hotshot/server

2. Install the Hotshot Chrome extension (if you haven't already)

3. Open your app in Chrome and start editing components!

Usage

Basic Usage

# Start with default settings (port 3737)
hotshot-server

# Custom port
hotshot-server --port 8080

# With config file
hotshot-server --config hotshot.json

Configuration File

Create .hotshotrc.json in your project root:

{
  "port": 3737,
  "cwd": "/path/to/project",
  "model": "claude-sonnet-4-5",
  "permissionMode": "acceptEdits",
  "systemPromptAdditions": "Additional instructions for Claude..."
}

CLI Options

Options:
  -p, --port <port>      Server port (default: 3737)
  -c, --config <path>    Path to config file (default: .hotshotrc.json)
  -h, --help             Show help message

Supported Frameworks

✅ React (with Fiber)

• Automatic component detection
• File path extraction from React internals
• Full props and context support

✅ Rails

• View path detection from HTML comments
• Supports ERB templates and partials
• Line number extraction

✅ Plain HTML

• Direct element selection
• Manual file path configuration
• Works with any static site generator

🚧 Vue, Svelte (Coming Soon)

• Framework detection implemented
• Full support in development

How It Works

1. Server runs independently from your app's dev server
2. Extension connects via WebSocket (ws://localhost:3737/hotshot-ws)
3. Claude CLI integration handles AI-powered edits
4. Health check endpoint at http://localhost:3737/health

Differences from Vite Plugin

| Feature | Vite Plugin | Standalone Server | |---------|-------------|-------------------| | Framework Support | React only | React, Rails, HTML, etc. | | Installation | Part of Vite config | Separate process | | Port | Same as Vite | Independent (3737) | | HMR Integration | Automatic | Uses your dev server's HMR | | Best For | React + Vite projects | Everything else |

Programmatic Usage

You can also use the server programmatically in Node.js:

import { HotshotServer } from '@hotshot/server';

const server = new HotshotServer({
  port: 3737,
  cwd: process.cwd(),
  model: 'claude-sonnet-4-5',
  permissionMode: 'acceptEdits',
});

await server.start();

Requirements

• Node.js 20.19+ or 22.12+
• Claude CLI installed and configured
• Chrome browser with Hotshot extension

Troubleshooting

Extension won't connect

1. Make sure the server is running: hotshot-server
2. Check server output for errors
3. Verify port 3737 is not blocked by firewall
4. Check health endpoint: curl http://localhost:3737/health

Claude CLI errors

Make sure Claude CLI is installed and authenticated:

# Install Claude CLI
npm install -g @anthropic-ai/claude-cli

# Authenticate
claude auth

License

Apache-2.0