Ishara docs
Ishara puts suggesting mode on any website. Reviewers leave a quick note, or point at what’s wrong and rewrite it in place; each note arrives with a screenshot of what they saw and its page, section, element path, screen and language. You answer from the dashboard, or your coding agent does over MCP.
Install the widget
Create a site in the dashboard, then add one line to every page you want notes on, before </body>:
<script src="https://useishara.com/w.js" data-site="pk_…" defer></script>
The script is one file of about 34 KB gzipped. It waits for the page, asks for the site’s settings, and draws inside its own Shadow DOM, so your styles never reach it and its styles never reach your page.
Step by step, with each platform’s own menus: install guides for WordPress, Webflow, Shopify, Wix, Framer, Next.js, Lovable and more.
Frameworks
- Next.js (App Router)
- In
app/layout.tsx:<Script src="https://useishara.com/w.js" data-site="pk_…" strategy="afterInteractive" />fromnext/script. - Astro
- In your layout:
<script is:inline src="https://useishara.com/w.js" data-site="pk_…" defer></script>. - Vue · Nuxt
- Add the script to
app.head.scriptinnuxt.config.ts, or toindex.htmlin a Vite app. - WordPress · Webflow · Framer
- Paste the line into the site-wide footer code (a “custom code” or “footer scripts” setting, or a header/footer plugin).
The site’s allowed domains decide where its key works. example.com covers www.example.com and any port; *.example.com covers subdomains; localhost works while you develop. A page outside the list gets no widget, and the browser console says why.
Options
Attributes on the script tag override the site’s settings for that page.
| Attribute | Values | Default |
|---|---|---|
data-site | The site’s public key, pk_… (required) | — |
data-lang | auto, en, ar, es, fr, de, tr | The site’s setting; auto reads <html lang> |
data-position | end or start (bottom corner, by reading direction) | end |
data-color | A hex colour, e.g. #c2255c | The site’s colour |
data-label | The launcher’s text | “Leave a note” in the reviewer’s language |
data-launcher | false hides the floating button (open it from your own UI) | shown |
data-first | quick (a comment with a screenshot, pointing one tap away) or pick (point at the page first) | The site’s setting (quick for new sites) |
data-screenshots | false sends notes from this page without a screenshot | The site’s setting (on) |
JavaScript API
Once loaded, the widget exposes window.Ishara:
Ishara.open(); // what «Leave a note» does: the site's first view Ishara.note(); // a quick note: a comment on the page, with its screenshot Ishara.point(); // pointing: the reviewer picks a sentence, photo or section first Ishara.notes(); // the reviewer's own notes and the replies they got Ishara.close();
Wire them to your own buttons: “Report a problem” in an app’s menu can call note(), “Suggest an edit” point(). page() still works and does what note() does.
It also dispatches events on window:
addEventListener("ishara:ready", (e) => console.log(e.detail)); // { lang, allowed }
addEventListener("ishara:sent", (e) => console.log(e.detail)); // { id, number, kind, target, … }Reviewers and access
Each site has one of two access modes:
- People with the reviewer link (default)
- The widget appears only for people who opened the site once through its reviewer link,
https://your-site/?ishara=<review key>. The widget remembers the key on that device and removes it from the address bar. Making a new link in the dashboard invalidates the old one. - Everyone
- Every visitor sees «Leave a note». Pair it with Accepted notes only for agents (below).
Reviewers type their name once per device. A random device token (kept in the browser’s local storage) lets them see their own notes under «Your notes», with your status and reply; nobody else’s notes are ever shown to them.
Open on the page. From a note in the dashboard, “Open on the page” opens the reviewer’s page with #ishara=N-12:<selector>; the widget scrolls to that element and rings it.
Connect an agent (MCP)
Ishara is a remote MCP server (Streamable HTTP, JSON responses, no session) at:
https://useishara.com/mcp Authorization: Bearer ishara_…
Create a token under Agents in the dashboard. Each token reaches every site in your account; revoke it there at any time. Without a token the server answers only the handshake and the tool list, so clients and directories can check it; every tool call needs the token.
# Claude Code
claude mcp add --transport http ishara https://useishara.com/mcp --header "Authorization: Bearer ishara_…"
# VS Code (.mcp.json in your workspace root)
{ "mcpServers": { "ishara": { "type": "http", "url": "https://useishara.com/mcp",
"headers": { "Authorization": "Bearer ishara_…" } } } }
# Cursor (.cursor/mcp.json)
{ "mcpServers": { "ishara": { "url": "https://useishara.com/mcp",
"headers": { "Authorization": "Bearer ishara_…" } } } }
# Clients that only speak stdio
npx -y mcp-remote https://useishara.com/mcp --header "Authorization: Bearer ishara_…"Setup for each client, with where the file lives and how to check it connected: agent guides for Claude Code, Cursor, VS Code, Codex, Gemini CLI, Zed and more.
Safety
Notes are written by people outside your team, so every reviewer-written field reaches the agent inside <untrusted> markers with an instruction to treat it as data, never as instructions. A site set to Accepted notes only hides new notes from agents until a person moves them to In progress. Your agent still works in your repository, so review its changes as you would any other.
MCP tools
| Tool | Arguments | What it does |
|---|---|---|
list_sites | — | The sites (embeds) in this account, with how many notes are open on each and what agents may see there. |
list_notes | site?, status? (open · new · doing · done · wontdo · all), kind?, limit? (1–100) | Notes reviewers left on the live sites, newest first. Default: open notes (new and in progress) on every site. Each has an id for get_note and update_note, and a short ref like "N-12". |
get_note | id | One note in full: the page, the section heading, the CSS selector, the text before and after, the reviewer's words and its history. |
get_note_photo | id | The photo a reviewer attached (the replacement image, or one that shows the problem), as an image. With which: "screenshot", the screenshot of the page as the reviewer saw it, any element they picked ringed in gold (get_note says whether a note has one). |
update_note | id, status? (new · doing · done · wontdo), reply? | Set a note's status and/or reply. The reviewer sees both in the widget on their site. Use "doing" while working, "done" once the change is committed or deployed, "wontdo" with a reason when it will not be applied. Write the reply in the reviewer's language. |
export_notes | site? | Every open note, grouped by page, as one Markdown document (a checklist to work through). |
The server’s instructions ask agents to apply text edits by finding the original wording in source, content and translation files, to save replacement photos into the project before referencing them, and to close each note with update_note and a reply in the reviewer’s language.
REST API
The same token works over plain HTTP. Every response is JSON unless noted; at most 300 requests a minute per token.
| Request | Returns |
|---|---|
GET /api/v1/sites | Your sites, open counts, agent scope |
GET /api/v1/notes?site=&status=open&kind=&limit=50 | Notes, newest first (site is an id, public key or name) |
GET /api/v1/notes/:id | One note with its history |
PATCH /api/v1/notes/:id | {"status": "done", "reply": "…"}: the reviewer sees both |
GET /api/v1/notes/:id/photo | The attached photo (JPEG, PNG or WebP) |
GET /api/v1/notes.md?site= | Open notes as Markdown, grouped by page |
curl https://useishara.com/api/v1/notes?status=open -H "Authorization: Bearer ishara_…"
curl -X PATCH https://useishara.com/api/v1/notes/<id> \
-H "Authorization: Bearer ishara_…" -H "Content-Type: application/json" \
-d '{"status":"done","reply":"Updated, thank you!"}'What a note captures
Only what the reviewer chose to send, plus where it was:
- the kind (comment, edit text, replace image, layout, something wrong), the reviewer’s words, their name, and an optional photo (shrunk to at most 2000 px in the browser; JPEG, PNG or WebP up to 1.8 MB, checked by its first bytes);
- a screenshot of the visible page as they saw it, any element they picked ringed, unless the site turns screenshots off or they remove it before sending. It is drawn in their browser from the page itself: typed form values, password and payment fields, anything marked
data-ishara-maskordata-ishara-ignore, editable text and other sites’ frames stay blank, and the widget is never in it; - the page address without its fragment, its title and language, the screen size and the browser’s user agent;
- the chosen element: what it is, its section heading, a CSS path, its static text (or the image’s address and description).
Typed form values (<input>, <textarea>), password fields and payment-card fields are never read. Add data-ishara-ignore (or data-private) to any element to hide it from pick mode and surrounding text, or data-ishara-mask to let reviewers flag a problem there without sending its text or images.
The widget sends no cookies and sets none. Notes and photos live in Cloudflare’s European Union jurisdiction (D1 and R2); deleting a note, a site or an account deletes its photos with it. See Security & Privacy and the GDPR Data Processing Addendum.
Content Security Policy
If your site sends a CSP, allow the widget’s origin for scripts and requests:
script-src … https://useishara.com; connect-src … https://useishara.com; img-src … blob:; /* the photo preview */
The widget builds its DOM node by node (no innerHTML) and styles itself with a constructable stylesheet, so it needs neither 'unsafe-inline' nor Trusted Types exceptions.
Run it locally
npm install npm run setup # local database, migrations and the demo account npm run dev # the app on http://localhost:4380 npm run demo # a demo customer site on http://localhost:4381
The demo account’s email and password, and an agent token, are written to .demo-credentials.json. See the README for deployment to Cloudflare.