@hotshot-it/vite-plugin

Vite plugin that enables visual React component editing powered by Claude Agent SDK.

Installation

pnpm add -D @hotshot-it/vite-plugin

Setup

1. Get an API Key

Get your Claude API key from console.anthropic.com

Create a .env file in your project root:

ANTHROPIC_API_KEY=sk-ant-your-api-key-here

IMPORTANT: The API key must be valid and have access to the Claude models. Test your key:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

If you see an "Invalid API key" error, your key is expired or incorrect.

2. Configure Vite

In your vite.config.ts:

import { defineConfig } from 'vite';
import hotshot from '@hotshot-it/vite-plugin';

export default defineConfig({
  plugins: [
    hotshot({
      port: 3737, // Optional: WebSocket port (default: 3737)
      model: 'claude-sonnet-4-5', // Optional: Claude model (default: claude-sonnet-4-5)
    }),
  ],
});

3. Install Browser Extension

Build and load the Chrome extension from packages/extension/dist.

Testing

Integration Test

Run the integration test to verify your setup:

cd packages/vite-plugin
pnpm test:integration

This will:

• ✓ Load API key from examples/hotshot/.env
• ✓ Validate API key format
• ✓ Create a test workspace
• ✓ Test Agent SDK connectivity
• ✓ Execute a sample query

Expected Output

=== Hotshot Integration Test ===

1. Loading API key from examples/hotshot/.env...
   ✓ API key loaded: sk-ant-oat01-dNeZGWs...KgAA

2. Validating API key format...
   ✓ API key format is valid

3. Setting up test environment...
   ✓ Test workspace created
   ✓ Test component created: TestComponent.tsx

4. Testing Agent SDK connectivity...
   ✓ AgentHandler initialized

5. Testing Agent SDK query...
   ✓ Agent query completed successfully
   ✓ Received 15 messages from agent
   ✓ Received 12 streaming chunks
   ✓ Stream completed with session ID: abc123

=== Test Summary ===
✓ All tests passed! The integration is working correctly.

Troubleshooting

Error: "Invalid API key"

Cause: The API key in .env is invalid, expired, or lacks permissions.

Solution:

1. Get a new API key from https://console.anthropic.com/
2. Update examples/hotshot/.env with the new key
3. Verify the key works with the curl command above

Error: "Claude Code process exited with code 1"

Cause: The Agent SDK CLI failed to start, usually due to:

• Invalid API key
• Network connectivity issues
• Missing Node.js dependencies

Solution:

1. Verify your API key is valid
2. Check network connectivity to api.anthropic.com
3. Run pnpm install to reinstall dependencies

Error: "ANTHROPIC_API_KEY is required"

Cause: No API key found in environment or plugin config.

Solution:

1. Create .env file with ANTHROPIC_API_KEY=your-key
2. Or pass apiKey directly to the plugin config

Architecture

Browser Extension → WebSocket → Vite Plugin → Agent SDK → Claude

1. User clicks a component in the browser
2. Extension sends component info via WebSocket
3. Plugin constructs prompt with file context
4. Agent SDK spawns Claude Code CLI
5. Claude reads/edits files via Agent tools
6. Changes stream back via WebSocket
7. Vite HMR updates the component

API

hotshot(config?: HotshotConfig)

Vite plugin factory function.

Config Options:

• apiKey?: string - Anthropic API key (defaults to process.env.ANTHROPIC_API_KEY)
• port?: number - WebSocket port (default: 3737)
• model?: string - Claude model to use (default: 'claude-sonnet-4-5')
• systemPromptAdditions?: string - Additional system prompt instructions

Development

# Build plugin
pnpm build

# Watch mode
pnpm dev

# Run integration test
pnpm test:integration

# Clean build output
pnpm clean

License

MIT