neat.link has served small link-in-bio pages since 2022, made by chatting with a Telegram bot. The rewrite started from one line in the first prompt: it should be agentic first. Nine hours later, the same pages ran on Cloudflare as link-in-bio pages with an MCP server, an HTTP API and a Markdown version of every page, and the old users still signed in through the bot.
One neat page, written by a person or an agent
A neat.link page reads like a business card: a round picture, a name, a line about what you do, a few lines of Markdown and a column of buttons, at neat.link/<handle>. The first version was a Python bot. People edited their page in a Telegram chat; the bot rendered it with Hugo, took a screenshot in a headless Firefox for the link preview and uploaded the files to S3. Keeping it running took Redis, a job queue, Firefox, geckodriver and a Telegram user account that asked @WebpageBot to refresh previews. About 70 people had made 55 pages with it.
“It should be agentic first – with /mcp connection, api access, llms.txt, .md responses”
From the first prompt to Claude Code
The same prompt set the rest of the brief: keep the existing users, who sign in through the bot; Google-only sign-up for new ones; a small web editor that doubles as a Telegram Mini App; public pages in the sitemap; generated preview covers. It named aion.ly, an earlier Lab project, as the reference for the stack and for how agents connect, and left the static site open to question: “this solution could be revised as well if it doesn't make sense.” With about 60 pages, rendering each one on request at the edge turned out simpler than a publish queue, and an edit is live at once.
Nine hours from the first prompt to production
Claude Code did the work in one long session through chatcode.dev. The first prompt arrived at 15:56. A working rewrite with the real data imported ran locally 52 minutes later, staging was up at 17:16, and neat.link switched to Cloudflare at 01:06. The link previews were redesigned the next afternoon. These turns shaped the result most.
-
1
Run the old system before replacing it
The agent started by getting the legacy bot running, and first stopped to ask: could it install Redis (the owner's rules say to ask before system packages), was the old server still polling with the same bot token, and where did the Telegram user account's login live. The reply was short: “Install redis only”, load the last dump, and “I would move everything to CloudFlare.” The bot's SQLite file then became the test data for the rewrite: every imported page was checked against the original, including page text converted from Telegram's MarkdownV2 to CommonMark.
-
2
The owner knew the newer API
Web sign-in with Telegram was first built on the Login Widget, the flow the agent knew. The owner pointed at Telegram Login instead: OpenID Connect with PKCE at
oauth.telegram.org, asking only for the profile. The same message reported that/agents,/termsand/privacybroke when clicked, and asked: “did you use the same font as it was in legacy?” The agent hadn't, and said so. The broken links came from the.datarequests React Router makes when you click a link, and the bot's name turned out to be hard-coded in six places, so staging sent people to the production bot. -
3
Make the common visit cheap
Asked to make delivery fast while keeping Cloudflare costs minimal, the agent measured first. A public page shipped about 135 KB of compressed JavaScript for content that needs none. Now pages, the home page and the legal pages are plain HTML with no scripts; a test page went from 8 KB of HTML to 2.9 KB. Visitors without an account get them from the edge cache for up to a minute, with no database read, while a signed-in owner always sees their edit at once. Clearing the cache everywhere on each save would need a Cloudflare API token in the Worker, and a minute's delay didn't justify one.
-
4
A second agent tries to break it
While the look was being settled, the owner asked Codex to review every commit so far as one piece. Its findings went into a file, each backed by a probe. The one P1: the sign-in form read the whole request body before checking its rate limit, and a 2 MiB streamed form went straight through. Four P2s covered lost editor edits, sessions that never renewed, an agent connection lost after Google sign-up, and a race that could link two Telegram accounts to one user. A second round found three more, including white labels on service colours too bright to read them. Claude Code fixed each with a test, and checked one editor fix by running the same browser check against the old code, where it failed.
-
5
The switch stays with the owner
By 22:49 production was ready apart from the switch: the database held the imported users and pages, the pictures were copied, and the Worker was deployed without a route. Claude Code's auto mode then refused to attach
media.neat.linkto the picture bucket, a DNS change on a live zone, even after the owner's go-ahead in the chat. The agent wrote the remaining steps into a script that stops at the first failure and asked the owner to run it. It did stop: the new domain's certificate took longer than the script's five-minute wait, so nothing else had changed. When the agent tried to continue itself, auto mode refused again, because the next step stopped a running bot. The owner ran a resume script and wrote back: “Done.” -
6
Taste, down to a few pixels
The next afternoon, the owner sent a screenshot of a link preview: “I like that they look almost like business cards, but there's still more free space.” Three rounds followed. The name is now as large as it fits, the card is centred both ways, and the address gets the ⎆ sign, from JuliaMono SemiBold cut down to a 2 KB font and renamed, as its licence asks. Text that doesn't fit is dropped by whole sentences, not cut with an ellipsis: “better keep less text in this case to make it feel like a card.” The last note, “All three text sections are aligned differently to the left”, came down to side bearings, the space before a letter's ink, which grows with the font size. Each line now moves left by its first letter's bearing, read from the font, and a test checks that every line starts at the same point.
What the link-in-bio pages run on
Pages
- React Router 8, rendered on the server in one Cloudflare Worker
- Plain HTML for public pages, cached at the edge for a minute
- resvg-wasm draws each 1200×630 link preview from SVG
Data
- D1 with raw SQL, imported once from the bot's SQLite file
- R2 for pictures, served from
media.neat.linkwithout running the Worker - Images binding to crop uploaded pictures square
Accounts
- Better Auth with Google for new accounts
- Telegram as a linked identity: Telegram Login, the Mini App or a one-time link from the bot
- The bot is a webhook on the same Worker and keeps no state
Agents
- MCP server at
/mcpover Streamable HTTP, with OAuth 2.1 - HTTP API at
/api/v1with tokens stored only as hashes - Markdown of every page at
/<handle>.md, plus/llms.txt
What made the collaboration work
- A working reference. The MCP server, the OAuth flow and the security baseline were ported from aion.ly rather than invented. That is much of why a working rewrite existed within the first hour.
- The plan as a record. Every decision, from the one-minute cache to why Telegram cannot create new accounts, went into docs/plan.md with its reason. The README tells anyone, person or agent, to read it before changing behaviour.
- A reference page beats adjectives. The look was matched against an old page, with the owner's list: “Tinted background, font weights, links not underlined until hovered, small rounded corners”. The agent compared screenshots of both, in light and dark.
- Literal instructions need a second look. “Keep theme monochrome” made the page buttons black too, until the owner asked for colours by service. A faithful copy of the old dark grey read with less contrast, so at the owner's request dark mode went back to near-black, which lifted body text from about 5.8:1 to 8.4:1.
- Some calls stay human. Google-only sign-up, keeping old users on Telegram, the operating company in the terms, and the moment of the production switch were the owner's.
Not everything worked the first time. Telegram's sign-in page answered “redirect_uri required” until the allowed addresses were added in BotFather. The sitemap was cached before the data import and listed four pages for up to an hour. One commit lost the blank line after its subject, and a test in another broke the typecheck until it moved to the Workers test project. Two MCP error messages still said aion.ly.
Make a page, or point an agent at it
neat.link is live: sign up with Google, or open @neatlink_bot in Telegram if you made a page with the old bot. Any published page can be read as Markdown, and an agent connects over MCP after you approve it once in the browser:
curl https://neat.link/index.md
claude mcp add --transport http neat https://neat.link/mcp
To run your own copy, you need Node.js, a Google OAuth client and a test bot from @BotFather. .dev.vars.example lists every value:
git clone https://github.com/chatcode-lab/neat.git
cd neat
npm install
cp .dev.vars.example .dev.vars # Google client, test bot token, secrets
npm run db:migrate:local
npm run dev # http://localhost:5173