Skip to content
BranchesTags

Repository files navigation

ReviseMy

Mark feedback for your agent.

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, 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, Sanctum, and Laravel MCP — ready for Laravel Cloud.

Features

  • Marks, not pins — product UI speaks in marks (rose 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 (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.
  • Try token, no account — one-click token on the homepage; paste MCP config for ChatGPT, Claude, Copilot, Cursor, or Grok.
  • 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 the hosted app (your *.laravel.cloud URL after deploy).
  2. Click Get a try token.
  3. Copy the MCP config for your client (ChatGPT, Claude, Copilot, Cursor, or Grok).
  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 / done)
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. Paid Plus is paused 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. 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. Webhooks and MCP Apps details — see docs/CONNECTORS.md.

MCP config (Cursor example)

After you get a try token from the homepage:

{
  "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.

REST API (same auth)

  • POST /api/try-token — create a try workspace + token
  • POST /api/reviews — { "title", "context?", "type?", "page_url?", "parent_id?", "webhook_url?", "images"|"capture_url"|"pdf"|"html" }
  • GET /api/reviews/{id}
  • GET /api/reviews
  • POST /api/reviews/{id}/screenshots — { "image" }
  • POST /api/reviews/{id}/findings — { "findings": [...] }
  • POST /api/reviews/{id}/marks/resolve — same payload as resolve_marks
  • POST /api/reviews/{id}/second-opinion — optional { "screenshot_index" }

Local development

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

Or step by step:

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

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

  • CONNECTORS.md — ChatGPT / Claude / Cursor / Grok setup, MCP Apps inline review, decision webhooks
  • SECOND-OPINION.md — second opinion, agent subagent findings, work packets
  • DEPLOY.md — Laravel Cloud deploy
  • /llms.txt — agent-oriented site index (on your deployed origin)
  • /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, and /changelog read that version automatically.

License

O'Saasy License — see LICENSE. Use, fork, and contribute freely; hosted SaaS rights are reserved for the copyright holder.

About

Mark feedback for your agent — human-in-the-loop design review over Laravel MCP

revisemy.com

Topics

design-toolsfeedback-looplaravellaravelcloudmcpmcpapps

Resources

Readme
License
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages