{
  "markdown": "<div align=\"center\">\n\n# <span>/</span> Spikes\n\n**The feedback loop for AI-assisted building**\n\n[![MIT License](https://img.shields.io/badge/license-MIT-e74c3c?style=flat-square)](LICENSE)\n[![Widget Size](https://img.shields.io/badge/widget-14KB_gzipped-22c55e?style=flat-square)](#)\n[![Free + Pro](https://img.shields.io/badge/free_+_pro-3b82f6?style=flat-square)](#pricing)\n\nAI can build a prototype in an hour.<br>\nTurning feedback into action is still the slow part.\n\n[Quick Start](#quick-start) · [CLI Reference](#cli-commands) · [Widget Docs](docs/widget-attributes.md) · [Hosted Dashboard](https://spikes.sh/dashboard) · [Self-Hosting](docs/self-hosting.md)\n\n</div>\n\n---\n\n## What Is This?\n\nSpikes is a feedback tool for AI-assisted development. It lets reviewers leave targeted feedback directly on web pages — no screenshots, no \"that button over there\", no lost context.\n\nClick any element. Rate it. Comment. Spikes captures the exact CSS selector, bounding box, and page context. Your AI agent gets structured JSON it can act on immediately.\n\n**No accounts required. No build step. Works on `file://`, localhost, anywhere.**\n\n---\n\n## Quick Start\n\n### 1. Install the CLI\n\n```bash\ncurl -fsSL https://spikes.sh/install.sh | sh\n# Or: cargo install spikes\n```\n\n### 2. Initialize your project\n\n```bash\nspikes init                     # Defaults to hosted spikes.sh\n# spikes init --self-host       # Opt out — scaffold a self-hosted config instead\n```\n\n`spikes init` creates `.spikes/config.toml` with a `[remote]` section pointing at `https://spikes.sh` by default. Pass `--self-host` (or answer `s` at the prompt) to skip the hosted defaults.\n\n### 3. Add the widget to your HTML\n\n```bash\nspikes inject ./mockups/        # Injects widget script tag (uses configured endpoint)\nspikes serve                    # http://localhost:3847\n```\n\n### 4. Collect and use feedback\n\n```bash\nspikes list                     # See all feedback\nspikes list --json              # Feed to your agent\nspikes list --rating no         # Find problems\nspikes hotspots                 # Elements with most feedback\nspikes resolve <id>             # Mark items done\n```\n\n---\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `spikes init` | Create `.spikes/` directory with config (hosted by default; `--self-host` to opt out) |\n| `spikes list` | List feedback (`--json`, `--page`, `--reviewer`, `--rating`, `--unresolved`) |\n| `spikes show <id>` | Show single spike details |\n| `spikes export` | Export to JSON/CSV/JSONL/Cursor/Claude context |\n| `spikes hotspots` | Elements with most feedback |\n| `spikes reviewers` | List all reviewers |\n| `spikes inject <dir>` | Add/remove widget from HTML files (`--endpoint <url>` overrides the configured endpoint) |\n| `spikes serve` | Local dev server (`--port`, `--marked`, `--cors-allow-origin`) |\n| `spikes mcp serve` | Start MCP server for AI agent integration |\n| `spikes pull/push/sync` | Sync with remote endpoint |\n| `spikes share <dir>` | Upload to spikes.sh for instant sharing |\n| `spikes login/logout/whoami` | Authentication management |\n| `spikes upgrade/billing` | Pro tier subscription via Stripe |\n| `spikes deploy cloudflare` | Scaffold self-hosted Worker + D1 |\n\nAll commands support `--json` for scripting. See [full CLI reference](docs/cli-reference.md).\n\n**Viewing spikes for a hosted project:**\n\nThe hosted dashboard at **<https://spikes.sh/dashboard>** lists every project you own and lets you drill into individual spikes (filter by page, rating, resolved, toggle `resolved` inline). Sign in directly in your browser: click **Sign in**, open the verification page, and confirm via the magic link sent to your email — no CLI required.\n\nYou can also hit the JSON API directly with your bearer token (`$SPIKES_TOKEN` from `spikes login`):\n\n```bash\n# GET /me/projects\n# List all projects you own (with spike_count + last_activity)\ncurl -H \"Authorization: Bearer $SPIKES_TOKEN\" \\\n  https://spikes.sh/me/projects\n\n# GET /me/projects/:key/spikes\n# List spikes for one of your projects (paginated, filterable: page, per_page,\n# filter_page, filter_rating, filter_resolved)\ncurl -H \"Authorization: Bearer $SPIKES_TOKEN\" \\\n  \"https://spikes.sh/me/projects/my-project/spikes?page=1&per_page=50\"\n\n# PATCH /me/projects/:key/spikes/:id\n# Toggle the `resolved` flag on one spike\ncurl -X PATCH -H \"Authorization: Bearer $SPIKES_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"resolved\": true}' \\\n  https://spikes.sh/me/projects/my-project/spikes/<spike_id>\n\n# POST /projects\n# Create a new project (user bearer only)\ncurl -X POST -H \"Authorization: Bearer $SPIKES_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"key\": \"my-project\", \"allowed_origins\": [\"https://example.com\"]}' \\\n  https://spikes.sh/projects\n\n# Single-line variant (copy-paste friendly)\ncurl -H \"Authorization: Bearer $SPIKES_TOKEN\" https://spikes.sh/me/projects\n```\n\nAll `/me/*` endpoints are user-scoped: you only ever see projects and spikes you own. Cross-tenant requests return `404 PROJECT_NOT_FOUND` (enumeration-proof).\n\n> **Security note:** API keys (`sk_spikes_*`) and the admin `SPIKES_TOKEN` are **not** accepted on `/me/*` endpoints or `POST /projects` — those require a user bearer token from `spikes login`. The `POST /spikes` collect endpoint enforces a per-project origin allowlist and per-project rate limits; rejected widget requests surface as a small red `#spikes-error-dot` indicator on the widget button (404 / 403 / 429).\n\n---\n\n## AI Agent Integration\n\nSpikes speaks agent natively. Your AI coding assistant can read, write, and manage feedback without ever leaving its workflow.\n\n```bash\nnpx spikes-mcp            # Zero-install MCP server — just works\n# or: spikes mcp serve    # If you have the CLI installed\n```\n\n### MCP Server — 9 Tools\n\n`spikes mcp serve` starts a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 9 tools:\n\n| Tool | Purpose |\n|------|---------|\n| `get_spikes` | List feedback with filters (page, rating, unresolved) |\n| `get_element_feedback` | Get feedback for a specific CSS selector |\n| `get_hotspots` | Find elements with the most feedback |\n| `submit_spike` | Create feedback programmatically |\n| `resolve_spike` | Mark feedback as addressed |\n| `delete_spike` | Remove a spike |\n| `create_share` | Upload files, get a shareable URL |\n| `list_shares` | See your active shares |\n| `get_usage` | Check usage stats, limits, and spend |\n\nSupports **stdio** and **HTTP** transports, **local** and **remote** data modes:\n\n```bash\nspikes mcp serve                              # stdio, local JSONL\nspikes mcp serve --remote                     # stdio, hosted API\nspikes mcp serve --transport http --port 3848 # HTTP for sandboxed agents\n```\n\n### API Keys\n\nAgents get their own identity. No email, no magic link, no human step:\n\n```bash\nspikes auth create-key --name \"my-agent\"   # → sk_spikes_...\nspikes auth list-keys                       # See all keys\nspikes auth revoke-key <key_id>            # Revoke\n```\n\nKeys support read/write/full scopes and optional budget caps.\n\n### Agent-Tier Billing\n\nConsumption-based pricing for agent-scale usage. Pay per spike, not per seat:\n\n```bash\nspikes usage    # See current spend and limits\n```\n\nBudget enforcement returns `429 BUDGET_EXCEEDED` when caps are hit — agents can check before they burn.\n\n### Context Exports\n\nExport structured markdown optimized for agent consumption:\n\n```bash\nspikes export --format cursor-context > cursor-feedback.md\nspikes export --format claude-context > claude-feedback.md\n```\n\n### Discovery\n\n- **[llms.txt](https://spikes.sh/llms.txt)** — All 9 MCP tools, parameters, agent quickstart\n- **[agents.md](https://spikes.sh/agents.md)** — Machine-readable landing page for agents\n- **[Smithery](https://smithery.ai)** — Listed in the MCP server registry\n- `spikes mcp install` — Generates config for Claude Desktop / Cursor\n\nFull details: [llms.txt](https://spikes.sh/llms.txt) · [agents.md](https://spikes.sh/agents.md)\n\n---\n\n## GitHub Action\n\nGate CI on feedback quality. The `spikes-action` fails builds when unresolved negative feedback exceeds your threshold.\n\n```yaml\nname: CI\non: [push, pull_request]\n\njobs:\n  feedback-gate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: bierlingm/spikes/action@v0.3.1\n        with:\n          threshold: 0           # Fail if any blocking spikes\n          ignore-paths: \"\"     # Optional: pages to ignore\n          require-resolution: false\n```\n\nSee [action/README.md](action/README.md) for full documentation.\n\n---\n\n## Widget Attributes\n\n**Simple setup** — just add your project key and you're ready to collect feedback:\n\n```html\n<script src=\"https://spikes.sh/spikes.js\" data-project=\"my-app\"></script>\n```\n\nWhen you set `data-project`, feedback syncs automatically to `https://spikes.sh/spikes`. No need to configure an endpoint unless you're self-hosting.\n\n**Full configuration** — all available attributes:\n\n```html\n<script src=\"https://spikes.sh/spikes.js\"\n  data-project=\"my-app\"\n  data-position=\"bottom-right\"\n  data-color=\"#e74c3c\"\n  data-theme=\"dark\"\n  data-reviewer=\"Pat\"\n  data-collect-email=\"true\"\n  data-admin=\"true\">\n</script>\n```\n\n**Self-hosting** — point to your own backend:\n\n```html\n<script src=\"/spikes.js\"\n  data-project=\"my-app\"\n  data-endpoint=\"https://my-worker.workers.dev/spikes\">\n</script>\n```\n\n| Attribute | Description | Default |\n|-----------|-------------|---------|\n| `data-project` | Group feedback by project key | `location.hostname` |\n| `data-position` | Button corner: `bottom-right`, `bottom-left`, `top-right`, `top-left` | `bottom-right` |\n| `data-color` | Accent color (any CSS color) | `#e74c3c` |\n| `data-theme` | Modal theme: `dark` or `light` | `dark` |\n| `data-reviewer` | Pre-set reviewer name | (prompts user) |\n| `data-endpoint` | Backend URL for multi-reviewer sync. Optional — defaults to `https://spikes.sh/spikes` when `data-project` is set. | `https://spikes.sh/spikes` (with `data-project`), `/spikes` (local dev) |\n| `data-collect-email` | Show email field in prompt | `false` |\n| `data-admin` | Enable review mode features | `false` |\n| `data-offset-x/y` | Button offset from edge | — |\n\nSee [Widget Attributes Reference](docs/widget-attributes.md) for complete documentation.\n\n---\n\n## Architecture\n\nSpikes has three components that work together or standalone:\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   CLI       │────▶│   Widget    │◄────│   Worker    │\n│  (Rust)     │     │  (Vanilla   │     │ (Cloudflare │\n│             │     │    JS)      │     │  + D1)      │\n└─────────────┘     └─────────────┘     └─────────────┘\n     │                                            │\n     │          spikes.sh (hosted)                │\n     └────────────────────────────────────────────┘\n```\n\n**CLI** — Rust binary for local development, spike management, and deployment. Stores spikes in `~/.local/share/spikes/`.\n\n**Widget** — 14KB gzipped vanilla JS. Captures element selectors, bounding boxes, ratings, and comments. Works offline via localStorage.\n\n**Worker** — Optional Cloudflare Worker + D1 backend for multi-reviewer sync, sharing, and hosted deployments. Lives in `spikes-hosted/`.\n\n---\n\n## Development\n\n### CLI\n\n```bash\ncd cli\ncargo build --release\ncargo test              # 160+ tests\ncargo run -- --help\n```\n\n### Widget\n\n```bash\ncd widget\n# Edit src/spikes.js\n# Test by running: spikes serve from the project root\n```\n\n### Widget Regression Tests\n\nCI suite that catches the silent-data-loss bug class (e.g., widget loaded on a non-allowed origin failing to sync without surfacing the error):\n\n```bash\ncd tests/widget\nnpm install\nnpx playwright install chromium    # one-time\nnpm test                           # 23 tests: marker checks + happy/reverse/boundary specs (<60s)\n```\n\nAlso wired into local agent-ci:\n\n```bash\nnpx agent-ci run --workflow workflows-local/widget.yml\n```\n\n### Worker\n\nThe Worker backend lives in the private `spikes-hosted` repo. To test it:\n\n```bash\ncd ../spikes-hosted/worker\nnpm test              # Worker test suite (vitest)\nnpx wrangler dev\n```\n\n---\n\n## Self-Hosting\n\nWant your own backend? One command:\n\n```bash\nspikes deploy cloudflare    # Creates spikes-worker/ directory\ncd spikes-worker && npx wrangler deploy\n```\n\nSee [Self-Hosting Guide](docs/self-hosting.md) for full setup with D1 database, authentication, and Stripe billing integration.\n\n### Share vs. Deploy Cloudflare: Which to Choose?\n\nUse **`spikes share`** when you want instant sharing without any setup — files are uploaded to spikes.sh and served from our infrastructure. Great for quick reviews, client feedback, or when you don't want to manage a backend.\n\nUse **`spikes deploy cloudflare`** when you need **data isolation** (feedback stays in your Cloudflare account), a **custom domain**, or want full control over the infrastructure. Self-hosting requires a Cloudflare account and a one-time deployment setup.\n\n---\n\n## What's Changed (Recent Overhaul)\n\n- **Security**: PBKDF2 password hashing, path traversal fixes, XSS protection\n- **Auth**: Magic link authentication (no passwords to forget)\n- **Billing**: Stripe integration with Pro tier support\n- **Testing**: CLI test suite (Rust) + Worker test suite (in ../spikes-hosted/worker)\n- **Architecture**: Modular worker with clean separation of concerns\n- **CI/CD**: Automated testing and deployment pipelines\n\n---\n\n## Detailed Documentation\n\n- [CLI Reference](docs/cli-reference.md) — Complete command documentation\n- [Widget Attributes](docs/widget-attributes.md) — All configuration options\n- [Self-Hosting Guide](docs/self-hosting.md) — Deploy your own backend\n- [API Reference](docs/API.md) — REST API documentation\n- [Rollback Guide](docs/rollback.md) — Emergency procedures\n\n---\n\n## Why Spikes\n\n| | |\n|---|---|\n| **Zero friction** | One script tag, no signup required, no build step |\n| **Works anywhere** | `file://`, `localhost`, any domain |\n| **Precise** | Element-level feedback with exact CSS selectors |\n| **Agent-native** | JSON everywhere, pipes, queryable CLI |\n| **Your infrastructure** | Self-host or use hosted — your choice |\n| **Tiny** | Widget is 14KB gzipped |\n| **Private** | No tracking, your data stays yours |\n\n---\n\n## Pricing\n\n<div align=\"center\">\n\n### Free forever. Pro if you want more.\n\nNo accounts required to start. Login when you need Pro features.\n\n</div>\n\n| | **Free** | **Pro** |\n|---|---|---|\n| **Price** | $0 forever | Pay what you can |\n| **Shares** | 5 | Unlimited |\n| **Spikes per share** | 1,000 | Unlimited |\n| **Widget + CLI** | Full | Full |\n| **Self-hosting** | Yes | Yes |\n| **Password protection** | — | Yes |\n| **Webhooks** | — | Yes |\n| **Badge removal** | — | Yes |\n\n<div align=\"center\">\n\nMIT licensed. Payment is appreciation, not access.\n\n`spikes upgrade` when you're ready. No pressure.\n\n</div>\n\n---\n\n<div align=\"center\">\n\n**[Website](https://spikes.sh)** · **[Docs](https://spikes.sh/docs.html)** · **[GitHub](https://github.com/bierlingm/spikes)** · **[Issues](https://github.com/bierlingm/spikes/issues)**\n\nMIT License · Built for builders who work with AI.\n\n</div>\n",
  "bytes": 15133,
  "sha": "b1435acfd02bbdee112c88a3576e489d5326274aeedeaab9cca876190e38e237",
  "repo_slug": "bierlingm/spikes",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bierlingm_spikes_9952a907/readme"
}