# ReviseMy

**Mark feedback for your agent.**

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=revisemy&config=eyJ1cmwiOiJodHRwczovL3JldmlzZW15LmNvbS9tY3AvcmV2aXNlbXkifQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_ReviseMy-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=revisemy&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Frevisemy.com%2Fmcp%2Frevisemy%22%7D)
[![License: O'Saasy](https://img.shields.io/badge/license-O'Saasy-ffc53d)](LICENSE)
[![Latest release](https://img.shields.io/github/v/release/heyderekj/revisemy?label=release)](https://revisemy.com/changelog)

**Hosted MCP server:** `https://revisemy.com/mcp/revisemy` — Claude and ChatGPT add it as a custom connector and click Connect; no account. Claude Code:

```bash
claude mcp add --transport http revisemy https://revisemy.com/mcp/revisemy
```

Or install the Claude Code plugin, which adds the server plus a `design-checkup` skill. In Claude Code:

```text
/plugin marketplace add heyderekj/revisemy
/plugin install revisemy@revisemy
```

ReviseMy is an open-source human-in-the-loop design review tool. Your agent captures **UI, websites, slides, or email** from screenshots, a URL, PDF, or HTML over [Laravel MCP](https://laravel.com/docs/mcp), you open a review link, **mark** what matters like a design critique, then approve or request changes. The agent reads structured work packets and keeps going.

Built with Laravel, Livewire, [Flux](https://fluxui.dev/), Sanctum, and Laravel MCP — ready for [Laravel Cloud](https://cloud.laravel.com).

## Features

- **Marks, not pins** — product UI speaks in marks (yellow rectangles + M1/M2 badges). Human marks are authoritative; API keys stay `pins` for compatibility.
- **Rectangle-first review** — drag to outline a region or click for a point note; zoom with +/− and pan with Space+drag (or middle mouse).
- **Second opinion (hints only)** — Free type-aware checklist in the sidebar on every screenshot; optional Claude/OpenAI vision when keyed draws dashed regions on the capture. Sky S-markers never override your marks — accept or dismiss them in the review UI.
- **Review types** — `ui`, `website`, `presentation` (Slide in the UI), or `email`: each gets its own checklist and vision lens (emails get CTA/dark-mode/client checks, slides get slide-density checks, sites get above-the-fold/responsive checks).
- **Four ways to ingest** — `images` (https URL, data URL, or base64), `capture_url` + `page_url` (desktop + mobile screenshots), `pdf` (one shot per page), or raw `html` (email at ~600px). URL capture also stores a DOM snapshot for grounding.
- **Before/after evidence** — agents attach an `after_image` when resolving a mark; the review page and board show a before/after crop next to the resolution note.
- **Mark lifecycle + board** — `/r/{token}/board` groups marks Open → In progress → Resolved → Verified. Agents call `resolve_marks` as they fix code; only the human verifies or reopens. When marks await verify, the review page surfaces an **Awaiting your verify** focus (with verify-all).
- **Thread comments** — reply on a mark without moving it on the canvas; recent comments land in `get_review` work packets for the agent.
- **Suggested copy + question answers** — optional exact-copy strings and answers on question marks ship in work packets so agents don’t invent wording.
- **Agent subagent path** — `add_findings` drops suggestion / a11y / polish notes into the same review before you look. Accept/dismiss (including batch and accept-as severity) promotes hints to marks with provenance (`guest` / `checklist` / `vision` / `agent`).
- **Work packets + `next_action`** — agents know whether to wait, apply marks, open the next pass, or stop.
- **Pass ledger** — multi-pass reviews show a revision ledger (decisions, mark counts, after evidence) in the UI and in `get_review`.
- **Multi-pass checkups** — `create_review` with `parent_id` for pass 2+ after you request changes (type and webhook inherit from the parent).
- **Decision webhooks** — optional `webhook_url` on `create_review`; ReviseMy POSTs a signed `review.decided` event when the human approves or requests changes, so CI/CD can gate without polling.
- **Guest share links** — `guest_share_url` lets stakeholders leave suggestions (not authoritative marks); the owner accepts or dismisses them.
- **Token-scoped recent reviews** — `/reviews` and enriched `list_reviews` show pass #, outstanding counts, and awaiting-verification without an account (same try token).
- **MCP Apps inline review** — in hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) (Claude web/desktop, Copilot, …), `create_review` / `get_review` render the review inline so humans can mark and decide without leaving chat. Cursor and Claude Code use the `review_url` link instead.
- **Connect, no account** — Claude and ChatGPT sign in with one click (OAuth); Cursor and VS Code install from a link; Grok, Muse, Codex and scripts use a free try token.
- **Secret review links** — humans open `/r/{token}` without signing up.
- **Live updates (optional)** — Laravel Reverb for realtime board/mark updates; without it the UI polls gracefully.

## Try it on any project (~2 minutes)

1. Open `/connect` on the hosted app and pick your assistant.
2. Claude and ChatGPT: add a custom connector with the address and click **Connect** (no account, no token). Cursor and VS Code: one click. Claude Code: one command. Grok, Muse and Codex: a free try token the page makes for you.
3. The page shows when your assistant makes its first call.
4. Ask your agent to capture the work (screenshot, URL, PDF slides, or email HTML) and call `create_review`.
5. Open the review link (or use inline MCP Apps if your host supports it), mark feedback, approve or request changes.
6. Ask the agent to call `get_review` and follow `next_action` — or listen on your `webhook_url` if you set one.

No account required for the human reviewer.

## MCP tools

| Tool | Purpose |
|------|---------|
| `create_review` | title + one source — `images`, `capture_url` (renders `page_url`), `pdf`, or `html` — (+ optional `type`, `page_url`, `parent_id`, `webhook_url`) → review URL; starts second opinion |
| `get_review` | work packets + `next_action` (`wait_for_human` / `apply_pins_then_next_pass` / `apply_decision_note` / `open_next_pass` / `done`), plus `work_packets.carried_over` for previous-pass marks the human reopened |
| `list_reviews` | recent reviews for this try token (summaries: status, pass, outstanding / awaiting-verification counts — call `get_review` for pins) |
| `add_screenshot` | append a shot to an open review |
| `add_findings` | agent subagent — push suggestion/a11y/polish into the review |
| `resolve_marks` | agent progress on human marks: `in_progress` → `resolved` (+ note, optional `after_image`); never `verified`. Check `skipped` in the response — marks listed there did **not** land |
| `request_second_opinion` | refresh checklist (+ vision if keyed) |
| `get_billing` | plan, credits remaining, burn table, and when credits refill |
| `add_mark` | **MCP Apps UI only** — human leaves a mark inline (agents must not call) |
| `decide_review` | **MCP Apps UI only** — human approves or requests changes |
| `verify_mark` | **MCP Apps UI only** — human verifies or reopens a resolved mark |

Three more tools — `create_checkout`, `create_portal`, and `cancel_subscription` — are registered **only when `REVISEMY_PRICING_ENABLED=true`** (billing runs through [Polar](https://polar.sh)). Paid pricing is off by default, so a default install advertises 11 tools, not 14. Keeping the dead ones off the list keeps them out of every agent's context.

Prompt: `design_checkup_loop` — full agent↔human checkup cycle.

Screenshots accept **https URLs**, **data URLs**, or **base64**. URLs are fetched server-side, so they must be public https on standard ports — loopback, private, and link-local addresses are rejected (including via redirect). For anything on localhost, pass a data URL instead.

## Credits

Every `create_review` costs credits, so this is the limit you'll hit first:

| Source | Cost |
|--------|------|
| `images` | 1 |
| `pdf` | 1 |
| `html` | 3 |
| `capture_url` | 5 |

**Try** (the default, no account) grants **20 credits per month**, rolling, with no rollover — about 20 screenshot reviews or 4 full website captures. **Plus** ($9/mo) grants **100 credits per billing month**. A **credit pack** ($5 one-time) adds **50 credits that never expire**, on either plan; pack credits are spent after the monthly grant. `get_billing` reports what's left and when it refills; a `create_review` that can't afford its source returns `[insufficient_credits]`. Self-hosting? Set `REVISEMY_FREE_CREDITS` and `REVISEMY_TRY_TOKEN_PER_DAY` to whatever you like.

**Terminology:** UI copy uses *marks*; JSON still uses `work_packets.pins`, `related_pin`, and `apply_pins_then_next_pass`. Second opinion is suggestions only — see [docs/SECOND-OPINION.md](docs/SECOND-OPINION.md). Webhooks and MCP Apps details — see [docs/CONNECTORS.md](docs/CONNECTORS.md).

### MCP config (Cursor example)

After you get a try token from the homepage:

```json
{
  "mcpServers": {
    "revisemy": {
      "url": "https://YOUR-APP.laravel.cloud/mcp/revisemy",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

The homepage also copies configs for Claude Desktop, Copilot, Claude Code, and ChatGPT/Grok hints. Same URL + Bearer header works for any MCP host — see [docs/CONNECTORS.md](docs/CONNECTORS.md).

### REST API (same auth)

The same reviews over plain HTTP, for scripts and CI: `POST /api/try-token`, then `/api/reviews` and its screenshots, findings, `marks/resolve` and `second-opinion` endpoints. Every endpoint with a curl example is in the [REST API docs](https://revisemy.com/docs/rest-api).

## Local development

```bash
composer setup          # install, .env, key, migrate, npm build
composer dev            # server + queue + logs + vite (all-in-one)
```

Or step by step:

```bash
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
php artisan storage:link
npm install && npm run build
php artisan serve
```

Run a queue worker (`php artisan queue:listen`) only if you are testing decision webhooks or other queued jobs locally. Vision second opinion does not need one.

Visit `http://127.0.0.1:8000`, get a try token, and create a review.

### Tests

```bash
composer test           # 122 tests
```

Key suites for contributors:

| File | What it covers |
|------|----------------|
| `tests/Feature/McpCreateReviewTest.php` | `create_review` / `get_review` over MCP for every input type |
| `tests/Feature/McpAppTest.php` | MCP Apps UI tools (`add_mark`, `decide_review`, `verify_mark`) |
| `tests/Feature/CaptureIngestionTest.php` | same ingestion paths via REST |
| `tests/Feature/ReviseMyFlowTest.php` | try token, guest share, findings, multi-pass loop |

MCP tests use `ReviseMyServer::actingAs($user)->tool(...)` — no Cursor config required.

## Deploy on Laravel Cloud

1. Push this repo to GitHub.
2. In [Laravel Cloud](https://cloud.laravel.com): **New application** → import the repo.
3. Attach **Postgres** and **object storage** (do not use SQLite on Cloud — it does not persist across deploys).
4. Set env:
   - `APP_NAME=ReviseMy`
   - `FILESYSTEM_DISK` / `REVISEMY_DISK` to the Cloud object storage disk
   - `APP_URL` to your `https://….laravel.cloud` URL
   - Queue worker optional (`QUEUE_CONNECTION`) — not required for vision second opinion
   - Optional `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`) for the vision second opinion — `REVISEMY_VISION_PROVIDER=auto` prefers Claude when both are set. Just the key; no worker needed.
   - Optional free local vision: run Ollama, set `REVISEMY_VISION_PROVIDER=openai`, `REVISEMY_OPENAI_BASE_URL=http://localhost:11434/v1`, and `REVISEMY_OPENAI_MODEL=llama3.2-vision` (blank key is fine). Local/OSS models give helpful hints, not Claude/GPT-4o quality.
   - Optional `REVISEMY_CAPTURE_DRIVER=hosted` + `REVISEMY_CAPTURE_ENDPOINT`/`REVISEMY_CAPTURE_KEY` (Browserless-compatible API) for server-side URL/email/PDF capture — Cloud containers have no Chrome, so use the hosted driver there
   - Optional `REVISEMY_CAPTURE_DPR=2` (default) — retina URL captures via Browserless `deviceScaleFactor`
   - Optional Reverb (`BROADCAST_CONNECTION=reverb` + `REVERB_*`/`VITE_REVERB_*`) for live updates — without it the UI polls
5. Deploy. Run migrations from Cloud commands: `php artisan migrate --force`

See [docs/DEPLOY.md](docs/DEPLOY.md) for Postgres pooler tips, Neon wake timeouts, and contest checklist.

## Self-host

Point MCP at your own origin. Use S3-compatible storage for screenshots in production. Rate limits and review expiry are built in — retention is per plan (`REVISEMY_FREE_RETENTION_DAYS`, 7 by default; 90 on Plus), and guest share links expire on their own 7-day clock.

For free pixel vision without a cloud API key, point `REVISEMY_OPENAI_BASE_URL` at Ollama (or another OpenAI-compatible `/v1` host) as in `.env.example`.

## Stack

- Laravel 13
- Livewire 4 + Flux UI
- Laravel MCP (HTTP at `/mcp/revisemy`)
- Laravel Sanctum try tokens
- SQLite (local) / Postgres (production) + object storage
- Laravel Reverb (optional realtime)

## Docs

- **[Developer docs](https://revisemy.com/docs)** — quickstart, authentication, the MCP tool reference, the review loop, REST API and webhooks. Source in [docs/developers](docs/developers); the tool reference is generated from the server.
- [CONNECTORS.md](docs/CONNECTORS.md) — ChatGPT / Claude / Cursor / Grok setup, MCP Apps inline review, decision webhooks
- [SECOND-OPINION.md](docs/SECOND-OPINION.md) — second opinion, agent subagent findings, work packets
- [DEPLOY.md](docs/DEPLOY.md) — Laravel Cloud deploy
- [DISCOVERY.md](docs/DISCOVERY.md) — registry listings, directories and search setup
- `/llms.txt` and `/llms-full.txt` — agent-oriented site index, and every page in one file (on your deployed origin)
- `/{page}.md` — any public page as markdown, e.g. `/board.md`
- `/.well-known/mcp/server-card.json` — endpoint, auth, tools and prompts as JSON
- `/sitemap.xml` — public pages for search engines
- `/changelog` — versioned release notes

### Version bumps

Product SemVer lives in `config/revisemy.php`. To cut a release: `php artisan revisemy:bump {major|minor|patch} [--title=…]` → fill highlights in `config/changelog.php` → commit (and tag if you want). The homepage badge, MCP app, `/changelog` and the server card read that version automatically; the command also updates `server.json` and the Claude plugin's `plugin.json`.

## License

[O'Saasy License](https://osaasy.dev/) — see [`LICENSE`](LICENSE). Use, fork, and contribute freely; hosted SaaS rights are reserved for the copyright holder.