Getting Started

Two ways to install — pick whichever fits your workflow.

MCP Server (Recommended)

Register Preamp as an MCP server in Claude Code, then launch a session to complete setup. This gives you natural language control directly in your coding session.

1. Add the MCP server

claude mcp add --transport http preamp https://api.preamp.ai/mcp

2. Start a Claude session

claude

3. Sign up

Say to Claude: "Sign me up for Preamp."

Claude will discover the Preamp tools, prompt you for your email and a device name, and walk through email verification. The signup flow installs your device token, schedules hourly backups, and registers the /preamp slash command for future sessions. No terminal commands — everything happens inside Claude.

CLI Installer

Works with any AI tool on macOS, Linux, and Windows. Single file, zero dependencies beyond Node.js.

# Download the CLI
curl -fsSL https://preamp.ai/preamp.cjs -o preamp.cjs

# Run setup
node preamp.cjs setup

The setup wizard prompts for your email, discovers AI tool directories, and configures automatic backups.

Using /preamp after setup

Once either install path completes, the /preamp slash command is available globally in any Claude Code session. Type /preamp to get your backup status, trigger a manual backup, sync your config from another machine, restore from a snapshot, and more. Natural language also works — say things like “what’s my backup status” or “back up now” and Claude will use the Preamp tools directly.

What the Installer Does

1. Email verification — Sends a 6-digit code to your email. Confirms your identity and creates your account.
2. Device registration — Generates a cryptographic device token and stores it in your OS credential store.
3. Auto-discovery — Scans for Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Amp, Aider, Continue, and GitHub Copilot.
4. Setup generation — Creates Preamp settings files with your discovered paths and backup preferences.
5. Cron setup — Adds an hourly cron job to run incremental backups automatically.
6. First backup — Runs an immediate backup of all discovered files.

Configuration Options

Backup frequency

Default is hourly. Adjust to any interval from 15 minutes to daily.

node preamp.cjs schedule 30min   # Every 30 minutes
node preamp.cjs schedule hourly  # Every hour
node preamp.cjs schedule daily   # Once per day

Custom directories

Add any additional paths to your backup. Useful for project-level agent files or custom tool settings.

# Via Claude Code
"Also back up ~/my-project/.claude"

# Or via MCP
claude mcp add preamp -- npx ... --include ~/my-project/.claude

Credential Storage

Your device token is stored securely using your OS credential manager.

CLI Reference

Webhooks

Subscribe to events and receive HTTP POST notifications at your endpoint. See the API reference for webhook CRUD endpoints.

Event Types

Payload Format

Every delivery is an HTTP POST with Content-Type: application/json.

{
  "event": "backup-complete",
  "timestamp": "2026-03-25T10:30:00.000Z",
  "userId": "usr_abc123",
  "data": {
    "action": "backup_complete",
    "deviceId": "dev_xyz789",
    "metadata": {
      "snapshotId": "snap_abc123",
      "fileCount": 42,
      "totalBytes": 1048576
    }
  }
}

Signature Verification

Always verify the X-Preamp-Signature header before processing a webhook.

Node.js

import crypto from 'node:crypto';

function verifyWebhook(secret, body, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

// In your HTTP handler:
app.post('/webhooks/preamp', (req, res) => {
  const signature = req.headers['x-preamp-signature'];
  const rawBody = req.body; // must be raw string

  if (!verifyWebhook(WEBHOOK_SECRET, rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(rawBody);
  console.log(`Received: ${payload.event}`);
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your Flask handler:
@app.route('/webhooks/preamp', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Preamp-Signature', '')
    raw_body = request.get_data()

    if not verify_webhook(WEBHOOK_SECRET, raw_body, signature):
        return 'Invalid signature', 401

    payload = request.get_json()
    print(f"Received: {payload['event']}")
    return 'OK', 200

Slack Integration

If your webhook URL points to hooks.slack.com, Preamp automatically formats the payload as a Slack message:

{
  "text": "[Preamp Backup] *backup-complete*: `backup_complete` (device: dev_xyz789)"
}

Limits & Behavior

Deliveries are dispatched asynchronously. Failed deliveries are not retried — use the test endpoint to verify connectivity before subscribing to production events.