CountLink

A free, zero-backend countdown timer. Set a duration, copy the link, send it to a room — everyone who opens that link sees the identical countdown, perfectly in sync, because the deadline is a timestamp encoded in the URL itself. No account, no server, no database.

Live at countlink.app. For local dev, open index.html directly or serve the folder — see below.

License: source-available, not open source. No LICENSE file means all rights reserved by default — this repo is public so the "nothing you paste is uploaded" claim is checkable, not an invitation to redistribute or relaunch it as your own product.

Why this exists

Full research and reasoning is in the project memory (see /Users/bruno/.claude/projects/-Users-bruno-Code-boring-apps/memory/), but the short version: single-purpose "boring" utility sites (vClock, Wheel of Names, word counters) generate real, verifiable ad revenue at near-zero operating cost. vClock specifically — a free online timer — earns an estimated ~$500K/yr from Google AdSense on ~5.4M monthly visits. CountLink copies that proven business model (free tool, one ad slot, programmatic SEO pages) while adding a genuine feature vClock doesn't have: shareable, synced-by-link countdowns.

Project structure

index.html              the tool — home page, canonical version of the UI
control.html            phone-control remote (opt-in, off by default — see docs/phone-control-setup.md)
assets/
  style.css             all styling, shared by index.html and every /timers/ page
  app.js                all timer logic, shared the same way
  control.js             control.html's logic — separate file, different DOM shape
  realtime.js            thin Ably pub/sub wrapper for phone control, inert with no key configured
  realtime-config.js     the on/off switch — window.COUNTLINK_ABLY_KEY, empty by default
features.html           generated — every capability, named (see "The feature inventory")
timers/                 programmatic SEO landing pages (see docs/monetization.md)
  meeting-timer.html     the Meetings cluster hub
  exam-timer.html
  ...                    (the eight fixed-duration pages were consolidated into
                          /timers/ on 2026-07-29 — see _redirects for why)
guides/                 generated long-form articles
vs/                     generated head-to-head comparison pages (/vs/<competitor>)
functions/              Cloudflare Pages Functions — the only server-side code here
  mcp.js                 the MCP server at /mcp
  badge.svg.js           the README badge image
  j/[code].js            join codes: /j/<code> -> the ordinary #t= link
scripts/
  build-timer-pages.mjs  regenerates /timers/, /guides/, /vs/, features.html,
                          sitemap.xml and llms.txt from one data list
  articles.mjs           the /guides articles, as data
  comparisons.mjs        the /vs/ comparisons, as data — read its header before
                          editing: these pages make factual claims about other
                          companies and the rules are not stylistic
docs/
  monetization.md        step-by-step: analytics, AdSense, Pro/Stripe, growing /timers/
  perception-gap-2026-09-06.md  why assistants called this site "minimalist", and the fix
  phone-control-setup.md how to turn on pause/adjust/stop from a phone (currently dark — needs an Ably key)
ads.txt                 AdSense seller-verification file (fill in once approved)
robots.txt              allows crawling, points to sitemap.xml
sitemap.xml             generated — do not hand-edit, re-run the build script instead
archive/                earlier prototype ideas explored before CountLink (kept for reference)

Running it locally

No build step, no dependencies. Any static file server works, but use the included one during development — it sends Cache-Control: no-store so edits always show up on reload (a plain file server can leave your browser serving stale CSS/JS after a change):

cd /Users/bruno/onepage
node scripts/dev-server.mjs 4173
# open http://localhost:4173

(This is also what .claude/launch.json runs when using the Claude Code preview.)

How the sync mechanic works

assets/app.js writes the countdown's end-timestamp and label into the URL hash on start, e.g. #t=1783378107213&l=Workshop%20resumes. Opening that same URL on any other device reads the same timestamp and counts down to it using the device's own clock — so there's nothing to host, nothing to keep running, and no possibility of the "server" going down.

The URL contract: #t= vs #for=

There are two shapes of link, and the difference is the product:

#for= exists because until it did, only a human in a browser who had already pressed start could produce a working CountLink URL — the share link carries an absolute timestamp, so nothing that doesn't know the current epoch time could write one. That ruled out every context that wants to write a timer down in advance: an AI assistant answering "give me a 25 minute shared timer" (the largest traffic channel this site has), a bookmark, a calendar invite, a lesson plan, a saved OBS scene.

It accepts the same grammar the board accepts on paste — 25m, 1h30m, 90s, 5:00, 1:30:00, 45 — by calling the very same parsePastedDuration(), so there is only one duration syntax on the whole site. Add a label with &l=. Works on any timer page.

A setup link deliberately does not start itself. If it did, three people opening the same #for=25m would each get their own countdown from whenever they clicked — the per-visitor "evergreen countdown" deliberately rejected in docs/ and the exact opposite of "one fixed instant, identical on every screen". e2e/setup-link.spec.mjs fails if that ever changes.

The one exception is &go=1, which starts on load. It is opt-in precisely so "a shared link never auto-starts" stays a visible rule rather than a hidden per-page exception, and it exists for the OBS overlay — a Browser Source is one scene on one machine with every control stripped out and no link to copy from it, so there is no second viewer to fall out of sync with. The full overlay URL is /embed/?overlay=1#for=10m&go=1; both halves matter — /embed/ is the ad-and-analytics-free build, ?overlay=1 is what actually makes it transparent. Never hand out /?overlay=1 (see docs/overlay-ads.md: it redirects to /embed/ too late to stop the preload scanner queueing the ad scripts, and ads on a content-free screen is a live AdSense violation).

The MCP server (/mcp)

functions/mcp.js is a Cloudflare Pages Function exposing CountLink over the Model Context Protocol, so an assistant can hand someone a working link rather than telling them to go and make one. Four tools, all genuinely read-only (there is no backend — a timer is string arithmetic over a duration): create_timer, create_agenda, create_badge and describe_timer_link.

create_agenda takes an ordered list of { duration, label? } segments and returns one link on /timers/agenda-timer that starts now (or at an optional start_at) and advances through every segment on every screen, plus a run sheet. It mirrors encodeAgendaHash() in assets/app.js byte for byte and is round-tripped through that page's own parseAgendaHash() in the tests. describe_timer_link reads agenda links too, including a scheduled one that hasn't started yet.

A scheduled start_at in the future shows a "Starts soon" countdown, not an inflated first segment — computeAgendaState()'s idx gained a -2 ("not started") sentinel alongside the existing -1 ("finished"), because every segment boundary being positive meant any negative elapsed time used to resolve to segment 0, folding the wait into that segment's remaining time. Mirrored in functions/mcp.js's describeUrl(). e2e/agenda.spec.mjs covers the live transition — a 2-second-out agenda actually ticking over into its first segment with no reload, across all 5 browser projects.

create_timer covers three shapes with boolean flags: a plain shared link by default, for_obs_overlay: true for a self-starting OBS Browser Source, and embed_on_website: true for a ready-to-paste <iframe> snippet for someone's own web page. The last two are NOT the same URL shape despite both routing through /embed/ — OBS is one viewer, so its link auto-starts per load (#for=…&go=1); a website has many visitors, so its link must be a single fixed instant (#t=…) they all see identically, or it degenerates into the "evergreen per-visitor countdown" this product exists not to be. The website embed also carries the attribution <a> OUTSIDE the <iframe> — a link inside a frame is attributed to the frame's own document, not the host page, so it earns no backlink; this is the one mechanism on the whole site that compounds links without per-instance outreach (see docs/monetization.md).