/ Spikes

Die Feedback-Schleife für KI-gestütztes Bauen

KI kann in einer Stunde einen Prototyp bauen. Feedback in Aktionen umzusetzen ist immer noch der langsame Teil.

Schnellstart · CLI-Referenz · Widget-Dokumentation · Gehostetes Dashboard · Self-Hosting

Was ist das?

Spikes ist ein Feedback-Tool für die KI-gestützte Entwicklung. Es ermöglicht Reviewern, gezieltes Feedback direkt auf Webseiten zu hinterlassen – keine Screenshots, kein „der Button da drüben“, kein verlorener Kontext.

Klicke auf ein beliebiges Element. Bewerte es. Kommentiere. Spikes erfasst den exakten CSS-Selektor, die Bounding Box und den Seitenkontext. Dein KI-Agent erhält strukturiertes JSON, mit dem er sofort arbeiten kann.

Keine Konten erforderlich. Kein Build-Schritt. Funktioniert mit file://, localhost, überall.

Related MCP server: Aceto

Schnellstart

1. CLI installieren

curl -fsSL https://spikes.sh/install.sh | sh
# Or: cargo install spikes

2. Projekt initialisieren

spikes init                     # Defaults to hosted spikes.sh
# spikes init --self-host       # Opt out — scaffold a self-hosted config instead

spikes init erstellt .spikes/config.toml mit einem [remote]-Abschnitt, der standardmäßig auf https://spikes.sh zeigt. Übergib --self-host (oder antworte an der Eingabeaufforderung mit s), um die gehosteten Standardwerte zu überspringen.

3. Widget zu deinem HTML hinzufügen

spikes inject ./mockups/        # Injects widget script tag (uses configured endpoint)
spikes serve                    # http://localhost:3847

4. Feedback sammeln und nutzen

spikes list                     # See all feedback
spikes list --json              # Feed to your agent
spikes list --rating no         # Find problems
spikes hotspots                 # Elements with most feedback
spikes resolve <id>             # Mark items done

CLI-Befehle

Alle Befehle unterstützen --json für Skripte. Siehe vollständige CLI-Referenz.

Spikes für ein gehostetes Projekt anzeigen:

Das gehostete Dashboard unter https://spikes.sh/dashboard listet jedes Projekt, das dir gehört, und ermöglicht es dir, einzelne Spikes aufzurufen (nach Seite, Bewertung und Status filtern, resolved inline umschalten). Melde dich direkt im Browser an: Klicke auf Anmelden, öffne die Verifikationsseite und bestätige über den Zauberlink, der an deine E-Mail gesendet wird – keine CLI erforderlich.

Du kannst die JSON-API auch direkt mit deinem Bearer-Token aufrufen ($SPIKES_TOKEN von spikes login):

# GET /me/projects
# List all projects you own (with spike_count + last_activity)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  https://spikes.sh/me/projects

# GET /me/projects/:key/spikes
# List spikes for one of your projects (paginated, filterable: page, per_page,
# filter_page, filter_rating, filter_resolved)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  "https://spikes.sh/me/projects/my-project/spikes?page=1&per_page=50"

# PATCH /me/projects/:key/spikes/:id
# Toggle the `resolved` flag on one spike
curl -X PATCH -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}' \
  https://spikes.sh/me/projects/my-project/spikes/<spike_id>

# POST /projects
# Create a new project (user bearer only)
curl -X POST -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "my-project", "allowed_origins": ["https://example.com"]}' \
  https://spikes.sh/projects

# Single-line variant (copy-paste friendly)
curl -H "Authorization: Bearer $SPIKES_TOKEN" https://spikes.sh/me/projects

Alle /me/*-Endpunkte sind nutzerbezogen: Du siehst immer nur Projekte und Spikes, die dir gehören. Mandantenübergreifende Anfragen geben 404 PROJECT_NOT_FOUND zurück (vor Enumeration geschützt).

Sicherheitshinweis: API-Schlüssel (sk_spikes_*) und der Admin-SPIKES_TOKEN werden an /me/*-Endpunkten oder bei POST /projects nicht akzeptiert – diese erfordern ein Nutzer-Bearer-Token von spikes login. Der Collect-Endpoint POST /spikes erzwingt eine projektbezogene Origin-Allowlist und projektbezogene Rate-Limits; abgelehnte Widget-Anfragen erscheinen als kleiner roter #spikes-error-dot-Indikator am Widget-Button (404 / 403 / 429).

KI-Agenten-Integration

Spikes spricht nativ die Sprache der Agenten. Dein KI-Coding-Assistent kann Feedback lesen, schreiben und verwalten, ohne jemals seinen Workflow zu verlassen.

npx spikes-mcp            # Zero-install MCP server — just works
# or: spikes mcp serve    # If you have the CLI installed

MCP-Server – 9 Tools

spikes mcp serve startet einen Model Context Protocol-Server, der 9 Tools bereitstellt:

Unterstützt stdio- und HTTP-Transports sowie lokale und remote Datenmodi:

spikes mcp serve                              # stdio, local JSONL
spikes mcp serve --remote                     # stdio, hosted API
spikes mcp serve --transport http --port 3848 # HTTP for sandboxed agents

API-Schlüssel

Agenten erhalten eine eigene Identität. Keine E-Mail, kein Zauberlink, kein menschlicher Schritt:

spikes auth create-key --name "my-agent"   # → sk_spikes_...
spikes auth list-keys                       # See all keys
spikes auth revoke-key <key_id>            # Revoke

Schlüssel unterstützen Lese-, Schreib- und Vollzugriff-Scopes sowie optionale Budget-Obergrenzen.

Abrechnung für Agenten-Tarife

Verbrauchsbasiertes Pricing für den Einsatz im Agenten-Maßstab. Zahle pro Spike, nicht pro Sitzplatz:

spikes usage    # See current spend and limits

Die Budget-Durchsetzung gibt 429 BUDGET_EXCEEDED zurück, wenn Obergrenzen erreicht sind – Agenten können vorher prüfen, bevor sie etwas verbrauchen.

Kontext-Exporte

Exportiere strukturiertes Markdown, optimiert für die Verarbeitung durch Agenten:

spikes export --format cursor-context > cursor-feedback.md
spikes export --format claude-context > claude-feedback.md

Entdeckung

• llms.txt — Alle 9 MCP-Tools, Parameter, Agenten-Schnellstart

• agents.md — Maschinenlesbare Landingpage für Agenten

• Smithery — Im MCP-Server-Registry gelistet

• spikes mcp install — Generiert Konfiguration für Claude Desktop / Cursor

Vollständige Details: llms.txt · agents.md

GitHub Action

Steuere CI anhand der Feedbackqualität. Die spikes-action lässt Builds fehlschlagen, wenn ungelöstes negatives Feedback deinen Schwellenwert überschreitet.

name: CI
on: [push, pull_request]

jobs:
  feedback-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bierlingm/spikes/action@v0.3.1
        with:
          threshold: 0           # Fail if any blocking spikes
          ignore-paths: ""     # Optional: pages to ignore
          require-resolution: false

Siehe action/README.md für die vollständige Dokumentation.

Widget-Attribute

Einfache Einrichtung – füge einfach deinen Projekt-Schlüssel hinzu und du kannst Feedback sammeln:

<script src="https://spikes.sh/spikes.js" data-project="my-app"></script>

Wenn du data-project setzt, wird Feedback automatisch mit https://spikes.sh/spikes synchronisiert. Du musst keinen Endpoint konfigurieren, außer du verwendest Self-Hosting.

Vollständige Konfiguration – alle verfügbaren Attribute:

<script src="https://spikes.sh/spikes.js"
  data-project="my-app"
  data-position="bottom-right"
  data-color="#e74c3c"
  data-theme="dark"
  data-reviewer="Pat"
  data-collect-email="true"
  data-admin="true">
</script>

Self-Hosting – auf dein eigenes Backend zeigen:

<script src="/spikes.js"
  data-project="my-app"
  data-endpoint="https://my-worker.workers.dev/spikes">
</script>

Siehe Referenz der Widget-Attribute für die vollständige Dokumentation.

Architektur

Spikes besteht aus drei Komponenten, die zusammen oder eigenständig funktionieren:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CLI       │────▶│   Widget    │◄────│   Worker    │
│  (Rust)     │     │  (Vanilla   │     │ (Cloudflare │
│             │     │    JS)      │     │  + D1)      │
└─────────────┘     └─────────────┘     └─────────────┘
     │                                            │
     │          spikes.sh (hosted)                │
     └────────────────────────────────────────────┘

CLI – Rust-Binary für lokale Entwicklung, Spike-Verwaltung und Bereitstellung. Speichert Spikes in ~/.local/share/spikes/.

Widget – 14KB gzipptes Vanilla-JS. Erfasst Element-Selektoren, Bounding-Boxes, Bewertungen und Kommentare. Funktioniert offline über localStorage.

Worker – Optionales Cloudflare-Worker-+‑D1-Backend für die Synchronisierung mehrerer Reviewer, zum Teilen und für gehostete Bereitstellungen. Liegt in spikes-hosted/.

Entwicklung

CLI

cd cli
cargo build --release
cargo test              # 160+ tests
cargo run -- --help

Widget

cd widget
# Edit src/spikes.js
# Test by running: spikes serve from the project root

Widget-Regressionstests

CI-Suite, die die Klasse der stillen Datenverlustfehler abfängt (z. B. wenn ein Widget auf einer nicht erlaubten Origin geladen wird, nicht synchronisiert und den Fehler nicht anzeigt):

cd tests/widget
npm install
npx playwright install chromium    # one-time
npm test                           # 23 tests: marker checks + happy/reverse/boundary specs (<60s)

Außerdem in das lokale agent-ci eingebunden:

npx agent-ci run --workflow workflows-local/widget.yml

Worker

Das Worker-Backend liegt im privaten Repository spikes-hosted. So testest du es:

cd ../spikes-hosted/worker
npm test              # Worker test suite (vitest)
npx wrangler dev

Self-Hosting

Du willst dein eigenes Backend? Ein Befehl:

spikes deploy cloudflare    # Creates spikes-worker/ directory
cd spikes-worker && npx wrangler deploy

Siehe Self-Hosting-Guide für die vollständige Einrichtung mit D1-Datenbank, Authentifizierung und Stripe-Abrechnungsintegration.

Share vs. Deploy Cloudflare: Was ist die richtige Wahl?

Nutze spikes share, wenn du ohne Einrichtung sofort teilen möchtest – Dateien werden zu spikes.sh hochgeladen und von unserer Infrastruktur ausgeliefert. Ideal für schnelle Reviews, Kundenfeedback oder wenn du kein Backend verwalten möchtest.

Nutze spikes deploy cloudflare, wenn du Datenisolierung benötigst (Feedback bleibt in deinem Cloudflare-Konto), eine eigene Domain haben möchtest oder die volle Kontrolle über die Infrastruktur willst. Self-Hosting erfordert ein Cloudflare-Konto und eine einmalige Einrichtung der Bereitstellung.

Änderungen (aktuelle Überarbeitung)

• Sicherheit: PBKDF2-Passwort-Hashing, Path-Traversal-Fixes, XSS-Schutz

• Auth: Zauberlink-Authentifizierung (keine Passwörter zum Vergessen)

• Abrechnung: Stripe-Integration mit Pro-Tier-Unterstützung

• Tests: CLI-Testsuite (Rust) + Worker-Testsuite (in ../spikes-hosted/worker)

• Architektur: Modularer Worker mit sauberer Trennung der Verantwortlichkeiten

• CI/CD: Automatisierte Test- und Bereitstellungs-Pipelines

Ausführliche Dokumentation

• CLI-Referenz — Vollständige Befehlsdokumentation

• Widget-Attribute — Alle Konfigurationsoptionen

• Self-Hosting-Leitfaden — Stell dein eigenes Backend bereit

• API-Referenz — REST-API-Dokumentation

• Rollback-Leitfaden — Notfallverfahren

Warum Spikes

Preise

Für immer kostenlos. Pro, wenn du mehr willst.

Keine Konten erforderlich, um zu starten. Melde dich an, wenn du Pro-Funktionen brauchst.

MIT-lizenziert. Bezahlen ist Wertschätzung, nicht Zugang.

spikes upgrade, wenn du bereit bist. Kein Druck.

Website · Docs · GitHub · Issues

MIT-Lizenz · Gebaut für Macher, die mit KI arbeiten.