/ Spikes

El bucle de retroalimentación para la construcción asistida por IA

La IA puede crear un prototipo en una hora. Convertir los comentarios en acción sigue siendo la parte lenta.

Inicio rápido · Referencia de la CLI · Documentación del widget · Panel alojado · Autoalojamiento

¿Qué es esto?

Spikes es una herramienta de feedback para el desarrollo asistido por IA. Permite a los revisores dejar comentarios específicos directamente en las páginas web — sin capturas de pantalla, sin «ese botón de allí», sin contexto perdido.

Haz clic en cualquier elemento. Valóralo. Comenta. Spikes captura el selector CSS exacto, el cuadro delimitador y el contexto de la página. Tu agente de IA recibe JSON estructurado sobre el que puede actuar de inmediato.

Sin necesidad de cuentas. Sin paso de compilación. Funciona en file://, localhost, en cualquier lugar.

Related MCP server: Aceto

Inicio rápido

1. Instalar la CLI

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

2. Inicializar tu proyecto

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

spikes init crea .spikes/config.toml con una sección [remote] que apunta a https://spikes.sh por defecto. Pasa --self-host (o responde s en el aviso) para omitir los valores predeterminados del servicio alojado.

3. Añadir el widget a tu HTML

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

4. Recopilar y usar el feedback

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

Comandos de la CLI

Todos los comandos admiten --json para scripting. Consulta la referencia completa de la CLI.

Ver spikes de un proyecto alojado:

El panel alojado en https://spikes.sh/dashboard muestra todos los proyectos que posees y te permite profundizar en spikes individuales (filtrar por página, valoración, resuelto, alternar resolved en línea). Inicia sesión directamente en tu navegador: haz clic en Iniciar sesión, abre la página de verificación y confirma mediante el enlace mágico enviado a tu correo electrónico — no se requiere CLI.

También puedes llamar a la API JSON directamente con tu token de portador ($SPIKES_TOKEN de 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

Todos los endpoints /me/* están limitados al usuario: solo ves proyectos y spikes propios. Las solicitudes entre inquilinos devuelven 404 PROJECT_NOT_FOUND (a prueba de enumeración).

Nota de seguridad: las claves de API (sk_spikes_*) y el SPIKES_TOKEN de administrador no se aceptan en los endpoints /me/* ni en POST /projects — esos requieren un token de portador de usuario de spikes login. El endpoint de recopilación POST /spikes aplica una lista de orígenes permitidos por proyecto y límites de velocidad por proyecto; las solicitudes rechazadas del widget se muestran como un pequeño indicador rojo #spikes-error-dot en el botón del widget (404 / 403 / 429).

Integración con agentes de IA

Spikes habla el idioma de los agentes de forma nativa. Tu asistente de codificación con IA puede leer, escribir y gestionar feedback sin salir nunca de su flujo de trabajo.

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

Servidor MCP — 9 herramientas

spikes mcp serve inicia un servidor Model Context Protocol que expone 9 herramientas:

Admite transportes stdio y HTTP, y modos de datos local y remoto:

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

Claves de API

Los agentes obtienen su propia identidad. Sin correo electrónico, sin enlace mágico, sin paso humano:

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

Las claves admiten ámbitos de lectura/escritura/completos y límites de presupuesto opcionales.

Facturación para agentes

Precios basados en el consumo para un uso a escala de agentes. Paga por spike, no por asiento:

spikes usage    # See current spend and limits

La aplicación del presupuesto devuelve 429 BUDGET_EXCEEDED cuando se alcanzan los límites: los agentes pueden comprobarlo antes de gastar.

Exportaciones de contexto

Exporta markdown estructurado optimizado para el consumo por parte de los agentes:

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

Descubrimiento

• llms.txt — Las 9 herramientas MCP, parámetros, inicio rápido para agentes

• agents.md — Página de destino legible por máquina para agentes

• Smithery — Incluido en el registro de servidores MCP

• spikes mcp install — Genera la configuración para Claude Desktop / Cursor

Detalles completos: llms.txt · agents.md

Acción de GitHub

Condiciona la CI a la calidad del feedback. spikes-action hace fallar las compilaciones cuando el feedback negativo sin resolver supera tu umbral.

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

Consulta action/README.md para la documentación completa.

Atributos del widget

Configuración sencilla — solo añade tu clave de proyecto y ya estás listo para recopilar feedback:

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

Cuando defines data-project, el feedback se sincroniza automáticamente con https://spikes.sh/spikes. No necesitas configurar un endpoint a menos que te autoalojes.

Configuración completa — todos los atributos disponibles:

<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>

Autoalojamiento — apunta a tu propio backend:

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

Consulta la Referencia de atributos del widget para la documentación completa.

Arquitectura

Spikes tiene tres componentes que funcionan juntos o de forma independiente:

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

CLI — binario de Rust para el desarrollo local, la gestión de spikes y el despliegue. Almacena los spikes en ~/.local/share/spikes/.

Widget — JS puro de 14KB comprimido con gzip. Captura selectores de elementos, cuadros delimitadores, valoraciones y comentarios. Funciona sin conexión mediante localStorage.

Worker — backend opcional de Cloudflare Worker + D1 para la sincronización entre múltiples revisores, el uso compartido y los despliegues alojados. Vive en spikes-hosted/.

Desarrollo

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

Pruebas de regresión del widget

Suite de CI que detecta la clase de errores de pérdida silenciosa de datos (p. ej., widget cargado en un origen no permitido que falla al sincronizar sin mostrar el error):

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

También está conectado al agent-ci local:

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

Worker

El backend del Worker vive en el repositorio privado spikes-hosted. Para probarlo:

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

Autoalojamiento

¿Quieres tu propio backend? Un solo comando:

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

Consulta la Guía de autoalojamiento para la configuración completa con la base de datos D1, autenticación e integración de facturación con Stripe.

¿Compartir o desplegar en Cloudflare? ¿Cuál elegir?

Usa spikes share cuando quieras compartir al instante sin ninguna configuración — los archivos se suben a spikes.sh y se sirven desde nuestra infraestructura. Ideal para revisiones rápidas, comentarios de clientes o para cuando no quieras gestionar un backend.

Usa spikes deploy cloudflare cuando necesites aislamiento de datos (el feedback permanece en tu cuenta de Cloudflare), un dominio personalizado o quieras control total sobre la infraestructura. El autoalojamiento requiere una cuenta de Cloudflare y una configuración de despliegue única.

Novedades (renovación reciente)

• Seguridad: hash de contraseñas con PBKDF2, correcciones de path traversal, protección XSS

• Autenticación: autenticación por enlace mágico (sin contraseñas que olvidar)

• Facturación: integración con Stripe y soporte del plan Pro

• Pruebas: suite de pruebas de la CLI (Rust) + suite de pruebas del Worker (en ../spikes-hosted/worker)

• Arquitectura: worker modular con una separación limpia de responsabilidades

• CI/CD: pipelines automatizados de pruebas y despliegue

Documentación detallada

• Referencia de CLI — Documentación completa de comandos

• Atributos del widget — Todas las opciones de configuración

• Guía de autoalojamiento — Despliega tu propio backend

• Referencia de API — Documentación de la API REST

• Guía de reversión — Procedimientos de emergencia

Por qué Spikes

Precios

Gratis para siempre. Pro si quieres más.

No se necesitan cuentas para empezar. Inicia sesión cuando necesites funciones Pro.

Con licencia MIT. El pago es agradecimiento, no acceso.

spikes upgrade cuando estés listo. Sin presión.

Sitio web · Documentación · GitHub · Incidencias

Licencia MIT · Diseñado para creadores que trabajan con IA.