(CASE STUDY · 05)

PROMPTLY

Browser Extension
UX | UI
TypeScript
Local-First
MCP

Promptly is a Chromium extension that reviews a prompt while you write it. On AI sites such as ChatGPT, Claude and Gemini it scores the prompt from 0 to 100 as you type, lists what is missing, and offers a rewrite as a diff that changes nothing until you press Accept. The same engine also runs in a terminal, inside Claude Code and as an MCP server.

ROLE: Product, Design & Engineering
TIMELINE: 9 Days
YEAR: 2026
TEAM: Solo

(MY ROLE)

Wrote the spec and a 16-task test-first plan, then built Promptly from it.
Built the diff view, then a toolbar and a four-tab panel modelled on an existing prompt extension.
Wrote 11 checks, a weighted scorer and a local rewriter that fills in what a prompt is missing.
Packaged the engine as bin/promptly.mjs: 4 CLI commands, a UserPromptSubmit hook and 2 MCP tools.

(WHY IT EXISTS): A prompt gets written in a plain box with no feedback. Promptly puts a score next to that box and a list of what is missing one click away, before the prompt is sent.
(FROM A BADGE TO A TOOLBAR): Version 1 was a score badge and one card. A day later it was a toolbar that shows before you type, and a panel with four tabs.
(AGENTS NEED TARGETS, NOT PERSONAS): A week in, coding agents got their own profiles and an 11th check, agent readiness. The built-in rewrite gives an agent no "Act as" line. It adds acceptance criteria and, where the site takes @-mentions, a target.

Process

01
Spec & Budgets

The spec came before any code: 10 checks, 7 weighted parts and a 50 ms budget for each analysis. An in-page content script won over a background analyzer and an iframe overlay.
02
Test-First Build

Version 1 was split into 16 test-first tasks, each reviewed before the next began. A review of the whole branch closed it with one round of fixes.
03
Inside Other Apps

Chat apps move and rewrite their prompt box without events. Promptly re-anchors every frame, re-reads the text every 600 ms and writes back through each editor's own input path.
04
Review Loop

The day the CLI shipped, three review rounds followed. Copy stopped failing silently, the CLI stopped hanging when run with no text, and clip stopped garbling non-ASCII text on Windows.

How It Works

Type in the prompt box. 200 ms after you stop, 11 checks run inside the page and the score lands on a toolbar above it. Improve writes a rewrite at once and shows it as a diff.

(ONLY THE WORKER SENDS A KEY): API keys stay in the extension's local storage. They are stripped from the overlay's copy of the settings, and only the service worker sends a key anywhere.

WHERE YOUR PROMPT GOES

Built-in rewriter: The default. Runs in the page with no key and no network.
Ollama: localhost:11434 on your own machine. Its own toggle, no key.
Anthropic / OpenAI: Off by default. Needs a toggle, a granted permission and a key, then runs only when you click, with a 15 s timeout.
Saved prompts: Kept on this device. Account sync is scaffolded but not connected.

The Panel

Promptly lives on other people's pages. A glass toolbar sits above the prompt box, and one panel holds four tabs: Improve, Refine, Breakdown and Library. It follows the browser's light or dark setting and is styled inside a shadow root, so the site's CSS never reaches it.

The Breakdown tab over a dark chat page: "make website" scores 40, Weak, with a bar for each of the 7 parts and the first suggestions, starting with "Prompt is very short".

The Improve tab in light mode: "make website" struck out and the built-in rewrite added as a diff, with Dismiss, Copy and Accept.

In The Detail

One chip carries the verdict: red under 50, amber to 79, green from 80. A weak chat prompt gets a role and an output format. On Claude Code the same button can also turn the ask into a skill command, such as /review.

The toolbar twice: a red 40 above "make website" and a green 100 above the accepted rewrite.

The Engine

Version 0.4 took the analyzer and the scorer out of the browser. They are plain TypeScript with no network calls, so one bundled Node file gives the same verdict in a terminal, in a Claude Code hook and in any agent that speaks MCP.

(IT NEVER BLOCKS): The Claude Code hook scores each prompt as it is submitted. Under 70 it adds a stronger framing as extra context. It never blocks the prompt and never edits the user's words.

(SCOPE)

prompt checks: 11
weighted score parts: 7
automated tests: 107

A terminal: "promptly score" rates "make website" 40/100, Weak, with six findings, and "promptly improve --local" prints the same rewrite the extension shows.

Platform Profiles

24 platform profiles: 13 chat and 11 agent. Claude and ChatGPT each have both, told apart by path (/code, /codex). On 5 chat sites a tuned selector finds the prompt box. Everywhere else a heuristic picks it: a wide box, low on the page, near a send button. While a rewrite runs, the panel names the profile it is writing for.