TellUs

Visual feedback · agent-ready

Pin feedback to any website.
Your AI agent does the rest.

Clients click, type, save. You get a structured report — CSS selectors, computed styles, replacement text — that a coding agent acts on without a clarification round-trip.

Get started See how it works
TellUs widget pinned to an element on a live web page, comment box open

The problem

01

Feedback that costs more to understand than to fix

"The thing on the left is kind of weird."

That message lands in Slack, attached to a cropped screenshot with a red circle drawn in Preview. Now begins the real work: 20–30 minutes of back-and-forth — which element? which page? which viewport? which device? — before touching a line of code for a change that takes five minutes.

Multiply by twelve notes per session, three clients per month. The feedback loop is where small web projects lose days.

The real cost

Developers spend more time translating feedback than executing it. That changes when feedback arrives pre-structured for a machine.

How it works

02

Four gestures. Done.

A non-technical client can leave a precise, machine-actionable note in under 60 seconds — with zero instruction. That is the hard requirement.

  1. Open the widget

    The reviewer visits the activation link — yoursite.com?tellus=reviewer@email.com. A small launcher appears. One click enters feedback mode. A session cookie persists across page navigations for 24 hours.

  2. Click any element

    Every element highlights on hover — headings, images, nav links, buttons, anything in the DOM. Click to anchor the note. TellUs captures the element's selector, XPath, text, computed styles, and bounding box automatically.

  3. Type the feedback

    A small comment box appears anchored to the element. Plain language: "make this the studio's actual name" or "this feels too small on mobile." Screenshot and voice are each one optional extra click — never required.

  4. Save

    One button. An orange indicator dot marks the element. The note is submitted. The reviewer continues to the next page — no re-activating, no re-logging-in. ?tellus=off deactivates the widget.

The four-gesture TellUs workflow: open, click, type, save
The complete reviewer workflow — four steps, no instruction required
Zero footprint

The embed script is entirely dormant for normal visitors. No DOM injection, no event listeners, no network calls — until ?tellus= appears in the URL. One script tag, no performance cost.

Why it's different

03

Feedback built for the agent, not the inbox

Every other feedback tool captures what a human sees: a screenshot with a red circle, a thread of replies to untangle. TellUs captures what a coding agent needs — structured anchors and current state.

When a client says "make this heading bigger," the note doesn't just say that. It contains the CSS selector, the current font size from computed styles, the XPath, and the page URL. An agent locates the element in source and executes the change in one pass.

cssSelector ▸ .hero h2 computedStyles ▸ fontSize: 24px boundingBox ▸ {x:5%, y:18%} replacementText ▸ Smith Creative Studio

The summary report delivers a task batch in Layer 1 (~250 bytes/note). An agent acts on most notes without ever touching Layer 2. When it needs to disambiguate — three .price elements on a page — it fetches the detail layer: XPath, bounding box, screenshot, voice transcript.

Structured feedback note flowing into an AI coding agent that edits the source
Note → agent → source edit. No clarification step.
GET /api/reports/example.com/summary 
{
  "site": "example.com",
  "session": {
    "reviewer": "Jan Smith",
    "device": "desktop / Chrome / macOS",
    "viewport": "1440×900"
  },
  "notes": [
    {
      "id": "note-uuid-001",
      "page": "/about",
      "selector": ".hero-section h2",
      "currentText": "Welcome to Our Site",
      "comment": "Change to our actual studio name",
      "replacementText": "Smith Creative Studio",
      "type": "text-change",
      "detailRef": "note-uuid-001"
    }
  ]
}
Layer 1 — summary

~250 bytes per note. An agent reads the batch and executes. Most notes never require the detail layer — which preserves context window for the work itself.

What's included

04

Every tier ships today.

Tiers 0–2 are production-ready. Tier 3 is roadmap. No waitlist, no gated beta.

01 · zero install

One script tag

Drop the embed on any site — WordPress, Wix, Webflow, Squarespace, static HTML, Next.js, Shopify, localhost. No framework dependency, no extension, no client account.

02 · activation

URL-driven sessions

Send a link: ?tellus=email@domain.com. The reviewer needs nothing else. A 24-hour session cookie keeps the widget active across page navigations. ?tellus=off ends it.

03 · data model

Two-layer reports

Layer 1 summary (~250 bytes/note) for agent task batches. Layer 2 detail — XPath, computed styles, bounding box, screenshot, voice transcript — queried per note only when needed.

04 · optional rich capture

Screenshot + voice

One extra click captures a focused screenshot of the annotated element. One extra click records a voice note, transcribed client-side where the browser supports it. Neither is ever required.

05 · MIT licensed

Self-hostable

Plain PHP + MySQL, no Composer, shared-hosting compatible. Set TELLUS_BASE_URL, run migrate.php, build the widget, deploy. Full guide in the repo.

06 · zero footprint

Invisible to visitors

The widget bundle is ≤25KB gzip. Core is ~10.5KB. Screenshot and voice chunks load only on first use. For every visitor without ?tellus=: no DOM injection, no listeners, no requests.

TellUs dashboard showing feedback notes grouped by session with a detail drawer
Dashboard: sessions panel left, note cards right, detail drawer on select — status filters open / told / resolved / archived

Vs. the alternatives

05

Other tools capture feedback.
TellUs structures it for execution.

BugHerd, Marker.io, Feedbucket — good products, $39–150/month, per-client SaaS subscriptions. Their reports are designed to be read by a human who then translates feedback into code changes. That translation step is the bottleneck.

TellUs eliminates the translation step. The structured report goes directly to a coding agent. The agent has selectors, current state, and replacement text. It doesn't interpret. It executes.

Human-readable SaaS TellUs
Report consumer Developer reads, translates AI agent executes directly
Clarification step Usually required Near-zero for most notes
Per-client cost $39–150/mo subscription Self-hosted, MIT licensed
Platform requirement Varies; often WordPress-only Any site, any stack
Client account Usually required None — URL activation only
Selector in report Rarely Always — primary agent target

Get started

06

Add one tag.
Send one link.

TellUs is live at tellus.alchemygraphics.com. Self-hosting is documented and straightforward. No signup page, no pricing table — get in touch or drop the snippet and go.

User guide Technical docs

Step 1 — embed (one-time per site)

Add to your site's <head> or before </body> 
<!-- No API key. Trusted by origin allow-list. -->
<script defer
  src="https://tellus.alchemygraphics.com/widget/dist/tellus.min.js"
></script>

<!-- Self-hosted? Point to your instance: -->
<!-- data-tellus-api="https://your-host/api" -->

Step 2 — send the activation link

Activation URL pattern 
# Paste this in a message to your reviewer:
https://yoursite.com?tellus=reviewer@email.com

# The email becomes the notification target.
# ?tellus=off deactivates the widget.
# Session stays active 24h across page navigations.

Step 3 — get the report

Feed the JSON to your agent 
# Layer 1 summary — agent task batch
GET /api/reports/{domain}/summary?status=open

# Layer 2 detail — one note, full context
GET /api/reports/{domain}/detail/{noteId}

# CLI (SSH on your server)
php api/cli/feedback.php example.com
php api/cli/feedback.php example.com --resolve note-id \
  --comment "Fixed in commit abc123"