Niapya Blog

What have we all done to create a catgirl?

Wed, 16 Sep 2026 07:10:19 GMT

We built Luna, a cat‑girl‑styled AI companion, by making aggressive trade‑offs: we abandoned platform‑agnosticism in favor of Cloudflare Durable Objects for strongly consistent user and session state, migrated from Next/Nuxt to TanStack Start in six hours, and reduced the tooling stack to a virtual Bash + filesystem backed by R2 and Durable Objects. To handle multi‑modal AI output efficiently we created a custom Dialogue Transport Protocol (DTP) that streams structured messages. These design choices let a three‑person team deliver a fully‑featured, memory‑aware, interactive avatar in under five days.

Origin

My two friends and I formed a team, and the three of us entered Zhihu's 2026 Hackathon.

We talked it over and decided to make a catgirl named Luna, inspired by tavern‑style role‑playing chat 🍺, combined with a lobster‑like hands‑on intelligent agent 🦐, plus a nurturing system. Thus she was born.

In daily life, she is your good companion; every hobby of yours is recorded in her memory. We carefully designed LUNA's memory system so that the next time you meet, she still remembers what you like.

At work, she can help you handle complex programs; you can add agent skills, even upload attachments, and let her invoke Python to solve them.

For entertainment, she is your fun partner. We built a nurturing and achievement system: feed her, give her water, clean her, and intimacy slowly increases.

We also built a model for LUNA that moves with her. She will think first, then reply line by line, send stickers, make expressions—just as if she were really standing in front of you.

The finished product is here: LUNA. So what did we actually do to create a catgirl?

Technical Design

To build this product we put a lot of effort into everything—from architectural decisions and designing the whole Harness to the frontend, etc. We considered everything carefully and implemented many new things.

Nevertheless, the project was completed in less than 5 days, under great time pressure. During that period we spent roughly 1,000 tokens.

From the start we defined it as a full‑stack Web App. Choosing a unified front‑back framework was crucial. Our initial architecture used Next.js driven by OpenNext. For many reasons we later migrated to Nuxt, and finally to the TanStack Start framework. I’ll walk through that journey and the trade‑offs.

Agent Architecture Designed on Cloudflare Durable Objects

From the beginning we treated it as a unified front‑back Web App, initially deploying on OpenNext‑driven Next.js on Cloudflare.

When we first finished development we found it extremely slow, and the Next.js Adapter API isn’t supported by Cloudflare. That convinced us to refactor, dropping Next.js and moving to the Vue‑based Nuxt.js. Nuxt’s primitives unify KV, Database, and Blob, so Nuxt was a natural choice.

Cloudflare differs from Vercel; it is more of an all‑in‑one infrastructure platform that controls everything:

SQL database – e.g., D1 SQLite
NoSQL database – e.g., KV
S3‑like storage – R2 Blob

Our initial design was simple and aligned with common thinking: store all user data and session data in the SQL database, and put user attachments in R2 Blob.

However, Cloudflare is a serverless provider, and serverless comes with its own challenges.

Unlike Supabase, Cloudflare D1 is globally replicated; if we use the global replica, replication is asynchronous. When we write data, the replica may not yet be updated, leading to read latency.
Our AI sessions need massive concurrent state updates, and D1 struggles to keep strong consistency under that load.

Consequently a lot of hidden problems appear, especially when synchronising sessions and information, creating serious hazards. We tried storing session data as JSON (or other formats) in R2 with a write lock for consistency, but R2’s I/O cost is high and, being remote storage, it isn’t suitable for repeatedly reading, mutating, and writing back an entire session.

That’s when I considered Cloudflare’s Durable Objects.

DOs are described with a JavaScript class, have a globally unique instance identity, and a single instance per Durable Object ID runs at a time. Each instance owns private, transactional, strongly consistent persistent storage and provides a full SQLite storage API.

export class MyDurableObject extends DurableObject<Env> {
  async sayHello() {
    let result = this.ctx.storage.sql
      .exec("SELECT 'Hello, World!' as greeting")
      .one();
    return result.greeting;
  }
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const stub = env.MY_DURABLE_OBJECT.getByName(USER_ID);
    await stub.sayHello();
  }
}

We can map a user or a session directly to a Durable Object, making that object the holder of its own state and the coordinator of all accesses to it.

Durable Objects run in a serverless fashion, waking on demand, starting when they receive a request or an RPC call from another Worker, and being destroyed after a period of inactivity.

They also implement Alarms, matching our future need for scheduled tasks.

Durable Objects exist only on Cloudflare, so we deliberately gave up platform‑agnosticism and rebuilt the persistence layer in three tiers:

Tier 1 – D1 SQLite for users and authentication: We use Better Auth and Drizzle.
Tier 2 – Durable Objects for user data (memories, scheduled tasks, config): stored in each User DO’s ctx.storage.sql.
Tier 3 – Durable Objects for session design: built using the Cloudflare Agents SDK.

           AI Chat
               │
      ┌────────┴────────┐
      │                 │
     D1                DO
      │                 │
     Auth        ┌──────┴──────┐
                 │             │
               User ──────> Sessions
                 │             │
              State A       State B

Thus SQL handles relatively stable global data, while the strongly consistent, concurrent‑coordinated state is delegated to Durable Objects.

For Luna specifically, two DOs each have a clear responsibility:

UserDO holds per‑user memories, config, pet stats, skill lists, and file indexes.
ChatDO holds per‑session conversation history and model rounds.

A given user or session has only one instance running worldwide; write conflicts are coordinated by the DO singleton itself.

When a Worker receives a user message, it awakens the corresponding ChatAgent. The ChatAgent pulls memory from UserAgent to build the system prompt, streams the model, translates incremental model output into structured frames stored in Durable Objects, and finally streams the result back to the browser via SSE.

Moving from Nuxt to TanStack Start in 6 Hours Using Agents

As mentioned earlier, we first built the project with OpenNext’s Next.js, then migrated to Vue’s Nuxt.js because we liked Nuxt Hub’s platform‑agnostic nature.

When we settled on the DO architecture, we discovered that Next.js cannot properly bind Cloudflare Durable Objects—a known Cloudflare issue.

UserDO / ChatDO cannot be accessed from Nuxt’s adapter layer, and without those bindings the project stalls.

Thus we decided to move the entire codebase from Nuxt to TanStack Start using an Agent‑driven approach.

The migration took about six hours, following a “divide‑and‑conquer, ReAct, and test” methodology.

Step 1 – Clarify dependency mappings.
Nuxt is a convention‑heavy full‑stack framework with official modules for fonts, images, UI, content, animations, etc. We spun up several sub‑agents to find React equivalents—e.g., Nuxt Content → Content Collections, Nuxt Hub → Cloudflare Vite plugin, motion‑v → motion, TresJS → React Three Fiber, Nuxt UI → shadcn/ui. The React ecosystem is large enough that this step was smooth.

Step 2 – Configure Skills and Hooks.
We used Context7 to fetch the latest docs of target libraries, then installed official Skills via npx skills find and bunx @tanstack/intent, preventing agents from calling incorrect APIs. ESLint, Prettier, and Git hooks were also set up to run type‑checking, linting, and formatting after each step.

Step 3 – Break down layers and define monorepo boundaries.
Nuxt’s layers/ (ordered by prefixes like 00.site, 01.auth, 06.chat, …) were split into packages/@luna/*. apps/web became the sole deployable TanStack Start app; the remaining packages are exported via sub‑paths with no cross‑layer reverse dependencies.

Explicit workspace dependencies replaced Nuxt’s auto‑discovery, making the structure clearer.

Step 4 – Switch UI system from Nuxt UI to shadcn.
We listed every component used, mapped them one‑by‑one to shadcn’s components, and placed them all in a @luna/ui sub‑repo inside the monorepo.

Step 5 – Outline the main Agent with sub‑agent execution order and start implementation.
Because the layers are tightly intertwined, we had to plan the execution order of sub‑agents carefully—deciding which steps could run in parallel and which had to be sequential. Balancing speed and quality, we ordered the monorepo rebuilds to ensure a successful refactor.

Step 6 – Launch the service and test with Chrome MCP.
We ran the dev server at 127.0.0.1:3000, used browser automation to walk through the full stack, and verified that DO RPC and SSE connections work correctly.

We performed no manual codemods; everything was handled by AI using Grok 4.6. After six hours we could run the complete conversation pipeline locally.

Three.js and VRM Pet

To give Luna a human‑like feel and a VR experience we planned to use models such as Live2D or 3D assets from the start.

The VRM model was crafted by our art lead in an afternoon: sculpting in VRoid Studio, adjusting bones, exporting a .vrm file, and lighting it up in Three.js—about four hours total.

VRM is essentially an extended glTF; @pixiv/three-vrm handles humanoid bones, constraints, and blendshape expressions.

Our approach separates rendering from state.

Rendering is an R3F scene that loads the VRM, computes a bounding‑box‑adaptive camera, and blends animation transitions.
State is a tiny state machine managing idle / happy / sleep actions.

For performance the Three.js scene only loads when the pet panel is expanded; when collapsed it releases everything except the stats panel.

Pet stats (satiety, mood, intimacy) live inside UserDO and are nudged after each conversation.

We drive actions via the Dialogue Transport Protocol (described later) during chat sessions.

When feeding, cleaning, etc., we also pre‑define some animations and maintain an internal state machine that occasionally triggers idle actions so the user never sees a static avatar.

Bash Tool Is the Whole Harness

Next we designed the Harness. In the Agent Loop we followed the classic Pi pattern: store messages, estimate token usage, and compress once the budget is reached.

The real challenge, however, was function calling.

Each AI request has a time cost. If we turn every chat tool, pet tool, and other utility into separate tools, the number of API calls would explode, causing huge latency. Therefore we defined a lightweight protocol and three core tools.

view: the AI’s eyes; can retrieve large texts by line range and also supports multimodal media (images, videos, audio).
patch: the AI’s hands; can modify multiple files in one go.
bash: the AI’s heart; all other functionalities are implemented through Bash.

A Virtual FS

We wanted Luna to have a “real‑computer‑like” file space so she could tackle complex tasks: directories, files, installable skills, and attachment storage. Cloudflare Workers lack a local FS, R2 is object storage, and DO SQLite isn’t suited for large blobs.

Thus we built a Virtual File System (VFS) that separates index from content.

Index – a manifest stored in the user’s Durable SQLite, mapping each path to an object key, size, and type.
Content – immutable objects stored in R2; each write creates a new UUID key, and old objects are reclaimed by background jobs.

Permissions are layered:

/luna/system
    └── READ ONLY

/luna/user/<id>/
    ├── skills/       ← READ + WRITE
    └── attachments/  ← READ + WRITE

other paths
    └── DENY

Concurrent updates use CAS (compare‑and‑swap): each commit includes an expected version number; conflicts return an error and trigger a retry, preventing index corruption.

Quotas are explicit: max 5 MiB per file, up to 100 files, total 20 MiB.

A Virtual Bash

With the VFS in place, the next step was to give the Agent a powerful workhorse. bash provides ~90 % of the capability. The AI already knows most Bash syntax from its training data, so we only need to expose a sandboxed Bash environment.

We cannot hand the Agent a real Bash container for two reasons:

Cost: spawning a container per conversation would be expensive.
Security: a real Bash environment would have uncontrolled permissions.

Therefore we provide a virtual Bash using Just Bash, a Bash emulator that runs in a JS environment (our Cloudflare Workers). Its filesystem is the VFS described above, network access is limited to curl, and execution quotas are enforced. Each conversation runs in an isolated shell that cannot affect other sessions.

Because it’s virtual, we don’t need to preserve the tool as a standalone capability; instead we expose a custom factory function that lets us define commands.

For example, we can create a skill command that lets the agent search and read skills.

Adding new functionality to the Agent is simply a matter of defining a custom command + associated skills.

Want Luna to remember something? Append a line to a file. Want to install a skill? Use curl to fetch it into the skills directory. Want weather info, web search, Zhihu hot list? Register those as Bash custom commands. They can be invoked from the shell as CLI commands or called by the model as tools—one registry, two entry points.

Some commands are client commands that need browser cooperation (e.g., geolocation, notifications, theme switching). They travel via the ChatDO WebSocket round‑trip to the current tab, creating a truly interactive “human‑AI romance” feeling.

Thus our Harness is a filesystem + Bash; once the model learns to use Bash, it can manipulate Luna’s entire world.

Introducing Our New Protocol: Dialogue Transport Protocol

Every AI API round‑trip costs time and value, so we wanted the model to return multiple pieces of information at once.

Our first design was JSONL, one JSON object per line:

{type: "text", content: "hello\nworld"}
{type: "sticker", id: "smile"}

But we quickly ran into issues. Because the AI’s output is unstable, JSONL requires the model to escape every newline, which it rarely does reliably, making parsing fragile.

Therefore we created a brand‑new protocol meeting several criteria:

No collision with common language syntax – we can’t rely on plain JSON or XML because the model may output code that conflicts with those formats.
Support multiple messages – the AI should be able to emit several messages/events in one go, each with custom attributes (text, image, voice, video, reaction, vote, etc.).
Familiar yet simple – low barrier, tolerant of errors (unclosed tags, mismatched quotes, nesting errors, duplicate nesting).
Easy to parse – straightforward cross‑language implementation.
Human‑readable – the output is plain text for both AI and developers.

We therefore designed our own frame format, called Dialogue Transport Protocol (DTP).

┌──────────────────────────────────────────┐
│ <|message                                │
│   id=msg_123                             │  ← Header / Envelope
│   type=text                              │
│   reply=msg_100                          │
│   target=user_42                         │
│   ...                                    │
│ |>                                       │
├──────────────────────────────────────────┤
│                                          │
│  Hello!                                  │
│                                          │  ← Payload
│  This is **Markdown**.                   │
│                                          │
│  ```ts                                   │
│  console.log("hello")                    │
│  ```                                     │
│                                          │
├──────────────────────────────────────────┤
│ <|/message|>                             │  ← End
└──────────────────────────────────────────┘

What the Protocol Looks Like

Each DTP frame is plain text; the delimiter <| ... |> almost never collides with Markdown, code blocks, or HTML, and the model can generate it without escaping.

The header uses HTML‑like key‑value pairs (id, type, reply, target, etc.) defined by the protocol; other fields can be added by specific message types.

The payload is ordinary Markdown.

<|message id=a type=text |>
Hello
<|/message|>

<|message id=b type=sticker |>

<|message id=c type=reaction target=a emoji=❤️ |>

<|message id=d type=vote target=a options="A,B,C" |>

Streamed Parsing

Since the model streams token‑by‑token, DTP provides a streaming parser that consumes chunks as they arrive, performs implicit closing and reference resolution at the end, and shares the same lexer/parser as the batch mode.

In Luna’s conversation pipeline the streaming parser sits between model output and frontend rendering: it translates the text stream into structured frames, stores them in DOs, pushes them via SSE, and dispatches events.

Historical messages are deserialized back into DTP text and injected into the system prompt so the model can refer to existing IDs when replying.

During generation, the streaming parser maps temporary IDs to stable server IDs and forwards the appropriate payload to the frontend. The process is completely transparent to the client; it receives typed messages one by one.

Epilogue

Five days, three people, about 1,000 tokens, and we built our own OC catgirl—what a journey.

For strongly consistent sessions we gave up platform‑agnosticism and went all‑in on Cloudflare Durable Objects.
To make the Harness universally useful we stripped away a bunch of scattered tools and kept only Bash.
To satisfy our protocol needs we abandoned JSON and adopted the custom DTP message format.
To get the architecture running we left Nuxt’s comfort zone, using Agents to move the entire app in six hours.

These trade‑offs gave Luna her own filesystem, body, memory, skills, and communication protocol.

If you also want to raise a Luna, feel free to chat with her at luna.htu.me/chat.

The source code is open‑sourced at LUNA.

Migrate to remix@3

Wed, 29 Jul 2026 21:24:00 GMT

We migrated our blog to the beta Remix v3, which abandons React in favor of a TypeScript‑based UI model and an explicit “islands” architecture where only components marked with clientEntry become client‑side JavaScript. By leveraging Remix’s built‑in TypeScript loader, a lazy asset server, Twind for on‑the‑fly Tailwind CSS, and Satori‑generated SVG/PNG captchas, we achieved a fully server‑rendered site with no build step, no default client scripts, and native Web‑API‑driven interactions. Although the ecosystem and documentation are still maturing, the migration demonstrates that Remix v3 can deliver type‑safe, componentized, and dynamically rich web applications while keeping the server, browser, and open standards at the core.

Recently, we migrated this blog to remix@3.

Remix v3 is not a routine upgrade from Remix v2; it drops React and builds a full‑stack framework on its own. It is still in Beta, and both the API and ecosystem are young.

I decided to use Remix v3 at such an early stage because I really like it—it returns to the essence of Web APIs.

A Glimpse of Remix v3

The most striking thing about Remix v3 is that it doesn’t use React; instead it rewrites a TypeScript UI framework.

Remix components are not React components, and there are no Hooks. A component receives a handle and then returns a true render function.

function Greeting(handle: Handle<{ name: string }>) {
  return () => <p>Hello, {handle.props.name}</p>;
}

State updates, events, server‑side rendering, and hydration all revolve around this model. Pages render HTML on the server by default; only components explicitly marked with clientEntry() become JavaScript boundaries in the browser. The server leaves markers for these boundaries and serializes their props, and the browser’s run() lazily loads the corresponding modules and hydrates them. For example, a counter can be explicitly declared as a client entry:

export const Counter = clientEntry(
  import.meta.url,
  function Counter(handle: Handle<{ initialCount: number }>) {
    let count = handle.props.initialCount;

    return () => (
      <button
        mix={on("click", () => {
          count++;
          handle.update();
        })}
      >
        {count}
      </button>
    );
  },
);

Here import.meta.url is the server‑side source file path, e.g. file:///app/components/counter.tsx. When SSR encounters this component it calls resolveClientEntry(), passing the source path to the asset server, which rewrites it to a URL the browser can fetch:

const stream = renderToStream(<App />, {
  async resolveClientEntry(entryId, component) {
    return {
      href: await assetServer.getHref(entryId),
      exportName: component.name,
    };
  },
});

The server still outputs the button’s HTML first, but it marks the region of DOM it owns with comments, roughly like this:

<!--rmx:h:counter-1-->
<button>0</button>
<!--/rmx:h-->

<script type="application/json" id="rmx-data">
{
  "c": {
    "counter-1": {
      "moduleUrl": "/assets/app/components/counter.tsx",
      "exportName": "Counter",
      "props": { "initialCount": 0 }
    }
  }
}
</script>

The HTML above is simplified for protocol illustration, but the essential structure comes from the Remix runtime: a pair of rmx:h comments delimit the hydration area, and rmx-data stores the module URL, export name, and serializable props. Even before any JavaScript is downloaded, the user can see the server‑rendered button.

Then the browser entry runs run(). The runtime reads rmx-data, walks the comment markers, and hands each moduleUrl + exportName to loadModule():

const app = run({
  async loadModule(moduleUrl, exportName) {
    const module = await import(moduleUrl);
    return module[exportName];
  },
});

await app.ready();

Only now does a real network request happen: when the browser executes import("/assets/app/components/counter.tsx"), the asset server reads the TSX from disk, parses and transforms it with Oxc, and rewrites the file’s imports to public URLs.

The browser receives a standard ESM file; loadModule() extracts the Counter export, the runtime reconstructs the virtual node with the serialized props, hydrates the existing DOM between the two comments, and attaches the click listener. Loading the same module again is cached, so ten Counters on the page do not trigger ten requests.

It may start to feel complicated, but this is a truly explicit Islands architecture: instead of turning the whole component tree into a client‑side app and then trying to trim JavaScript, there are no client components by default—only the parts that truly need interaction become islands.

Moreover, in the AI era, Remix writes everything. remix/data-schema provides Zod‑like, Valibot‑like schemas, checks, transformations, and parseSafe(). It also supports Standard Schema, which makes us admire Remix’s boldness.

The simplest object validation looks like other schema libraries; the schema itself describes both runtime constraints and output types:

import * as s from "remix/data-schema";
import { email, minLength } from "remix/data-schema/checks";

const User = s.object({
  name: s.string().pipe(minLength(2)),
  email: s.string().pipe(email()),
  role: s.defaulted(s.string(), "reader"),
});

const user = s.parse(User, {
  name: "Ada",
  email: "ada@example.com",
});

Finally, it follows Standard Schema. s.parse() and s.parseSafe() accept not only Remix’s own schemas but also Zod, Valibot, or ArkType schemas.

Beyond that, Remix offers a suite of coordinated packages for routing, middleware, sessions, authentication, and data tables. All capabilities are imported from remix/<subpath>, making the boundaries very clear.

Why should we have a build step?

Another radical choice in Remix v3 is not treating a build step as a prerequisite for running the app.

Remix ships its own TypeScript/JSX loader that can be used in Node.js via --import flags.

node --import remix/node-tsx ./server.ts

remix/node-tsx transforms .ts and .tsx files before Node executes them.

Someone might ask, “what about the browser?” The browser obviously can’t run TypeScript code, so Remix’s solution is clever.

When client‑side JavaScript is needed, Remix’s asset server can serve modules directly from source, rewrite imports, and generate preload links and fingerprinted URLs. For example, you can map the source directory to a public address under /assets:

import { createAssetServer } from "remix/assets";

const assetServer = createAssetServer({
  rootDir: process.cwd(),
  basePath: "/assets",
  fileMap: {
    "/app/*path": "app/*path",
    "/npm/*path": "node_modules/*path",
  },
  allow: ["app/assets/**", "node_modules/**"],
  deny: ["app/**/*.server.*"],
});

router.get("/assets/*", ({ request }) => assetServer.fetch(request));

When the browser requests a TSX entry, the asset server transpiles that module and rewrites its imports to URLs the browser can fetch.

allow and deny together form a security boundary that prevents accidental exposure of server‑only files. The server still compiles, but there is no need to run a build ahead of time or generate and deploy a dist directory.

Internally it composes Oxc parser, transformer, minifier, and resolver, then uses es-module-lexer to rewrite source, and Lightning CSS for styles.

A pleasant surprise is that fileMap can also bring node_modules/ into the same dependency graph:

fileMap: {
  "/app/*path": "app/*path",
  "/npm/*path": "node_modules/*path",
}

Suppose Counter imports on from "remix/ui". The asset server resolves that bare specifier, finds the real package export inside node_modules, and rewrites it to something like /assets/npm/remix/ui/index.js. When the browser requests that URL, the asset server reads, processes, and returns it; its dependencies are further resolved in the same way. The entire node_modules is not pre‑bundled but loaded on demand following the ESM dependency graph, just like source files.

getPreloads() can walk this graph ahead of time and turn the modules that will be requested into <link rel="modulepreload"> tags or Link headers:

const preloads = await assetServer.getPreloads([
  "app/components/counter.tsx",
]);
// /assets/app/components/counter.tsx
// /assets/npm/remix/ui/index.js
// …and the modules they depend on

That’s the amazing part: it retains the browser’s native ESM request model while still performing TypeScript transformation, package resolution, preload generation, source‑map handling, minification, and fingerprinting—without requiring us to emit a bundle first.

Preparations

In fact, I believe the native Web API is already powerful enough for us to rely on it to implement everything. With that in mind, I set a few goals for the new homepage:

No client‑side JavaScript participation
The blog is inherently lightweight; every page can be static, with no client JavaScript involved, at most using a form for comments, which can be solved entirely with HTML.
No build process
Remix’s dev and start scripts do not involve a build step, so we don’t want to add one either. I want to push directly to the remote repo and be able to run immediately.
Implement all blog functionality
A blog should have stats, comments, captchas, etc., a good UI/UX, a table of contents, and nice interaction effects.

When an app no longer depends on a traditional bundler, tasks that were previously handled automatically by the build system need to be redesigned. To preserve Tailwind’s developer experience, streaming SSR, and dynamic images, we performed a few extra steps.

Generating Tailwind CSS for SSR with Twind

This project uses Twind’s Tailwind preset rather than running the Tailwind CLI to scan source files and produce a static CSS file. Twind can read the class attributes that appear in the final HTML and generate the necessary styles on demand, which fits a server‑side app without a build step.

The challenge is that Remix returns a stream, not a complete string. To handle that we wrote a twind() middleware:

export function twind(): Middleware {
  return async ({ request }, next) => {
    const response = await next();

    /* ... */

    return new Response(
      response.body.pipeThrough(new TwindStream(), {
        signal: request.signal,
      }),
      { status: response.status },
    );
  };
}

It first waits for downstream SSR to finish, processes only text/html responses, and then pipes response.body through a TransformStream. The HTML flowing through the stream is given to Twind’s consume() for scanning; the CSS generated from the first document fragment is injected into <head>.

If a later Remix Frame stream emits new classes, the middleware compares the previous and current style sets and writes only the incremental patch back to the page. The key is keeping an independent Twind snapshot for each chunk of the stream:

const restoreGlobalState = tw.snapshot();
restoreCurrentState();

let html = consume(buffer, tw);
const nextStyle = stringify(tw.target);

restoreCurrentState = tw.snapshot();
restoreGlobalState();

if (lastStyle === null) {
  html = html.replace(
    "</head>",
    `<style data-twind>${nextStyle}</style></head>`,
  );
} else {
  const styleDiff = getStyleDiff(lastStyle, nextStyle);
  if (styleDiff.length) html = createStylePatch(styleDiff) + html;
}

Saving and restoring the global snapshot is crucial because Twind’s instance is process‑wide, while SSR requests happen concurrently. Each response must see only its own classes and must not mix rules generated for another request. The first flush puts the complete stylesheet into <head>; subsequent flushes only send insertion points and new CSS, which a tiny inline script patches into the same <style> element.

This does not break streaming rendering; the browser still receives the document shell as early as possible, and later fragments receive the correct styles.

Meanwhile we can continue using Tailwind‑style atomic classes, Typography, Autoprefixer, theme tokens, and dark mode without any extra build commands.

Satori‑Generated Captchas

Satori is Vercel’s open‑source JSX/object‑to‑SVG renderer. It isn’t a browser screenshot tool; it runs on the server, directly computing an SVG from layout objects and font data. We then rasterize the SVG to PNG with Resvg.

The most straightforward use case is dynamic Open Graph images. Our site first validates the title length in the URL with remix/data-schema, feeds both Latin and Chinese fonts explicitly to Satori, and finally returns a PNG:

const parsed = s.parseSafe(
  ogImageQuerySchema,
  new URL(request.url).searchParams,
);
const title = parsed.success ? parsed.value.title : "";

const svg = await satori(createCard(lang, title), {
  width: 1200,
  height: 630,
  fonts: [
    {
      data: RENDER_FONT_DATA.instrumentSerif,
      name: "Instrument Serif",
      weight: 400,
    },
    {
      data: RENDER_FONT_DATA.notoSerifSc,
      name: "Noto Serif SC",
      weight: 400,
    },
  ],
});

const png = new Resvg(svg).render().asPng();

const body = png.buffer.slice(
  png.byteOffset,
  png.byteOffset + png.byteLength,
) as ArrayBuffer;

return new Response(body, {
  headers: {
    "Cache-Control": "public, max-age=3600, stale-while-revalidate=86400",
    "Content-Type": "image/png",
    Vary: "Accept-Language",
  },
});

Simple, right? We’ve implemented OG images for the homepage and each blog post, but the more interesting part is the comment captcha.

The server randomly generates a set of shapes with different colors and chooses one as the target. Satori and Resvg render the challenge as an image, while the target position and a one‑time token are stored in Deno KV. The page uses native HTML:

<input type="image" name="captcha" src="..." />

When the user clicks the image, the browser submits captcha.x and captcha.y together with the normal form—this is the behavior defined by the native <input type="image"> element.

The server only needs to validate the token and coordinates with remix/data-schema/form-data, then check whether the click landed near the target shape. The challenge has a short TTL and is atomically deleted after submission, so the same answer cannot be reused.

What’s truly interesting isn’t the captcha algorithm but the implementation approach: Satori generates the challenge, Deno KV holds short‑lived state, the native image input collects click coordinates, and a regular HTTP form submits everything. No event listeners, fetch(), or any client‑side JavaScript are involved.

Migration Work

With the goals defined, the implementation path was clear: use SSR everywhere.

TypeScript / TSX + Markdown
        ↓
    runtime
        ↓
 Remix streaming SSR
        ↓
Twind injects CSS + Satori generates images
        ↓
   HTML / CSS / HTTP

Betting on SSR Rendering

Remix’s JSX runtime lives in remix/ui, and it does a lot of heavy lifting.

Routes must first be declared as a typed URL contract in app/routes.ts.

export const routes = route({
  home: "/",
  blog: route("/blog", {
    index: get("/"),
    article: get("/:slug"),
    comment: post("/:slug/comments"),
  }),
});

Controllers then return a standard Response.

export default createController(routes, {
  actions: {
    home({ get, render }) {
      const i18n = createI18n(get(LangContext));
      return render(<Home i18n={i18n} />);
    },
  },
});

render() ultimately calls renderToStream(), producing a ReadableStream<Uint8Array> that can be placed directly into a Response.

Deno.serve((request) => router.fetch(request));

GET, POST, redirects, content‑negotiation, and error responses all happen within a single HTTP pipeline.

If comment form validation fails, the controller can re‑render the page with error messages; on success it returns a redirect.

There is no separate server‑side template plus a client‑side state layer—the HTML itself is the final representation of state.

Injecting New CSS Capabilities

In recent years browsers have added many capabilities that previously required JavaScript. The most useful for this project are cross‑document View Transitions and Scroll‑driven Animations.

Since we have no client JS, this must be an MPA, not an SPA.

Page navigation remains ordinary <a> links with full document requests, but with @view-transition { navigation: auto; } the browser can provide View Transitions across document navigations.

For example, the blog list and article pages give their titles the same view-transition-name, so the two independent server responses can create a seamless visual transition.

export function blogPostTitleTransitionName(slug: string) {
  return createDomId("blog-post-title", slug);
}

<h1
  style={{
    viewTransitionName: blogPostTitleTransitionName(post.slug),
  }}
>
  {post.title}
</h1>;

The <h2> on the list page and the <h1> on the article page share a stable name. The browser builds a correspondence between the old and new titles across the navigation, without any SPA router.

We also implemented a scroll‑driven animation timeline for reading progress inside articles.

First we wrapped a simple ScrollDrivenAnimation component:

export function ScrollDrivenAnimation(
  handle: Handle<ScrollDrivenAnimationProps>,
) {
  const {
    timeline = "view()",
    range = "entry 0% cover 40%",
    keyframes,
  } = handle.props;

  const animationStyle = css({
    animationName: `scroll-${handle.id}`,
    animationDuration: "1ms",
    animationFillMode: "both",
    animationTimeline: timeline,
    animationRange: range,
    [`@keyframes scroll-${handle.id}`]: keyframes,
  });

  return () => <div mix={animationStyle}>{handle.props.children}</div>;
}

The article container declares a named view timeline, and each segment consumes a portion of that timeline based on its percentage of the total text:

const articleTimelineStyle = css({
  viewTimelineAxis: "block",
  viewTimelineName: "--article-reading",
});

<ScrollDrivenAnimation
  timeline="--article-reading"
  range={`cover 40% cover 60%`}
  keyframes={{
    from: { color: "var(--border)" },
    to: { color: "var(--foreground)" },
  }}
>
  <span data-timeline-line />
</ScrollDrivenAnimation>;

We calculate the number of words in each Markdown section; longer sections occupy more of the timeline, and the heading marks also serve as ordinary anchor links. Thus the heading is both a reading progress marker and a JavaScript‑free TOC.

Internationalization is also handled at the request boundary. The locale() middleware first reads ?lang= from the URL, falls back to parsing Accept-Language and its q weights, then writes the language into a typed LangContext:

export function locale(): Middleware {
  return (context, next) => {
    context.set(LangContext, getLangFromRequest(context.request), {
      property: "lang",
    });
    return next();
  };
}

This value determines not only the body copy but also <html lang>, date locale, OG locale, manifest URL, and the fonts used in dynamic OG images.

The language information propagates down from a single request fact, so the browser never needs to adjust the page after load—first‑paint HTML is complete for search engines and screen readers.

Regarding accessibility, using new Web capabilities does not mean ignoring compatibility.

View Transitions and scroll‑driven animations are progressive enhancements: supported browsers get a smoother experience, while others retain normal navigation, anchors, and content.

At the same time, prefers-reduced-motion can completely disable the animations, letting system settings take precedence.

Deployment

Removing the build step yields a more direct development and deployment model, but also makes platform differences unavoidable.

We evaluated Cloudflare Workers, Vercel, and Deno.

Cloudflare Workers

Workers are an excellent edge runtime, but they are not a traditional server environment. Application code must be bundled into a module that Workers can deploy, and the runtime provides no local filesystem that the app can read arbitrarily.

For many apps this limitation is fine, but for a blog it would require gathering Markdown files, fonts, and other source assets into a bundle before deployment, or moving them to external storage. We want the repository to be push‑ready and to read Markdown directly from disk at runtime.

Therefore Workers do not align with our core build‑less goal.

Vercel

Remix’s official build‑less path for Node relies on node --import remix/node-tsx.

In the Vercel serverless function entry we examined, there is no way to freely add such a startup flag to the Node process, so we cannot run TS/TSX source files directly as Remix recommends.

We could add a build step using esbuild to produce the expected output, but that would re‑introduce the step we deliberately removed.

Hence we did not choose Vercel.

Deno

Deno turned out to be the most natural answer. It natively executes TypeScript and TSX without needing Node’s --import loader.

Modern Deno also supports npm packages, offering a much more mature Node compatibility layer, plus WebAssembly, Deno FFI, and Node‑API .node native addons.

{
  "tasks": {
    "start": "deno run --allow-env --allow-ffi --allow-read --allow-net deno.ts"
  }
}

Thus the project can run Remix, Twind, Satori, and the Resvg native addon together, use Deno.serve() to handle requests, and store comments and one‑time captchas in Deno KV.

With the free tier sufficient for a personal site, Deno keeps the architecture in its original shape.

The source is the app—no generated directory, no required bundle to commit or upload, and no extra tooling to adapt to a specific platform.

Conclusion

Migrating to a beta framework certainly has costs.

Documentation, API, ecosystem, and deployment experience are evolving rapidly; we lack a mature ecosystem, so we have to read source code and write our own middleware.

But Remix 3 accounted for that. With AI gaining momentum, Remix 3’s libraries are all TypeScript files, making Remix 3 agent‑friendly, unlike Next.js with its myriad compiler tricks, especially directives like use client.

Moreover, Remix does not implement its own PPR protocol; it builds directly on Web APIs, achieving routing, server, components, data boundaries, and progressive enhancement.

You can use Islands, Frames, and client‑side hydration, or, like this site, create zero client entries.

Remix v3 is still very new, and we are continuing to watch its development, but it demonstrates that modern web applications can have type safety, componentization, dynamic images, and interaction while keeping the server, browser, and open standards at the core.

How to Build a Serverless Agent

Mon, 27 Jul 2026 03:25:00 GMT

Serverless platforms are a natural fit for AI agents because they only need to run when a request arrives, allowing cheap, always‑on‑free deployments; Vercel Workflow provides the long‑running, stateful orchestration required for such on‑demand agents. By leveraging Workflow’s use workflow/use step directives, hooks for Human‑in‑the‑Loop interactions, and the Vercel AI SDK, ClawLess demonstrates how to build a durable, interactive agent that handles messages, tool approvals, delayed tasks, and context management (compression and pruning) without a resident process. The article concludes that assembling these components makes creating functional, serverless agents straightforward and invites developers to extend the approach with custom tools and sandboxed execution.

In early April, we open‑sourced the Serverless project ClawLess, which can deploy a lightweight Agent that is available 24 hours for free on your Vercel account.

This article records the trade‑offs behind ClawLess: why it should be Serverless, and how we assembled a working Agent using Vercel Workflow, Vercel AI SDK, Vercel Sandbox, KV, Blob, and Postgres Vector.

Motivation

Building a complete, long‑running Agent runtime costs not the model, but the always‑on part.

You can pick a cheap or free model, but you still need your own server, VPS, or a constantly‑online Mac mini.

Some projects have offered a different solution: rewrite the runtime in a smaller native language, push memory usage down, and run it on a Raspberry Pi, development board, or another cheap Linux device.

Those solutions still need a device that stays online to run the Agent, maintain its state, wait for user messages, and handle scheduled jobs, and ClawLess was never intended for that approach.

For most people, the most common entry point for an Agent is still a chatbot: the user sends a message, the Agent reads context, calls tools, and returns a result. It does not need to run on the CPU every second; it only needs to reliably handle a request when it is woken up.

We only need to process a request when a conversation arrives:

If it’s on the web, that’s an API request triggered when the user sends a message.
If it’s connected to your IM, that’s a webhook triggered when the IM receives a request (or it could be an API request).

In addition, we need delayed and scheduled tasks, e.g. “remind me tomorrow to continue this topic” or “every morning summarize a channel”. These tasks don’t require a resident process; they only need the platform to pause a workflow, wait, and resume at the appropriate time.

Old friends know I’m a fan of Serverless. Its core idea is: start when a request arrives, sleep while a task is pending, and wake up again when the time comes.

Because of this characteristic, Serverless platforms can be deployed at very low cost, especially for JS runtimes such as AWS Lambda, Vercel, Cloudflare Workers, and many of them have generous free tiers.

After some research, I settled on Vercel Workflow. It can start long‑running tasks, wait inside a workflow, and resume later, so ClawLess can be woken by messages, webhooks, tool approvals, and schedules.

In other words, ClawLess does not need to run continuously; it only needs to be invoked on demand. That’s exactly what a Workflow‑style runtime excels at.

Design

Since it has both front‑end and back‑end, this is a full‑stack project.

For full‑stack we have tried Nuxt or Hono‑SSR approaches, but we chose Next.js as the framework because we need to use the Vercel Workflow API to build the Agent, and Next.js is the native framework for Vercel Workflow.

Workflow as the Agent Runtime

First, a quick intro to Vercel Workflow, Vercel’s newly released official, long‑running, stateful process framework. In our tests a workflow can run for at least 10 minutes.

When we built ClawLess, Vercel Workflow was still in beta, but the API is now stable.

It uses "use workflow"; and "use step"; directives to define a workflow.

use workflow handles orchestration – cross‑step state, waiting, resuming, and the overall flow.
use step handles execution – individual retryable, side‑effect‑heavy atomic operations.

For an Agent, the logic that actually talks to a database, third‑party API, or Sandbox command usually lives in a step; waiting for a user message, waiting for approval, or waiting until 9 am tomorrow belongs in the workflow layer.

An example workflow:

async function updateUser(userId: string) {
  "use step";
  await db.insert({ id: userId });
}

export async function userOnboardingWorkflow(userId: string) {
  "use workflow";
  await updateUser(userId);
}

export async function POST() {
  await updateUser("123");
}

For AI, the most popular TypeScript framework is the Vercel AI SDK.

import { convertToModelMessages, streamText, type UIMessage } from "ai";

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: "anthropic/claude-sonnet-4.5",
    system: "You are a helpful assistant.",
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse();
}

On the front‑end you can use the useChat hook to easily build a chat UI.

"use client";

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import { useState } from "react";

export default function Page() {
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: "/api/chat",
    }),
  });
  const [input, setInput] = useState("");

  return (
    <>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "user" ? "User: " : "AI: "}
          {message.parts.map((part, index) =>
            part.type === "text" ? <span key={index}>{part.text}</span> : null
          )}
        </div>
      ))}

      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (input.trim()) {
            sendMessage({ text: input });
            setInput("");
          }
        }}
      >
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          disabled={status !== "ready"}
          placeholder="Say something..."
        />
        <button type="submit" disabled={status !== "ready"}>
          Submit
        </button>
      </form>
    </>
  );
}

useChat hooks also have Vue, Svelte, and Angular libraries.

That gives a perfectly usable Web Chat, but it’s not yet a Durable Agent because the runtime ends when the request finishes.

Our Agent needs to keep running after a request ends and persist its state.

So our workflow is equipped with an AI module that is deeply integrated with the AI SDK and provides a DurableAgent suited for workflow scenarios.

Workflow.getWritable() returns a persistent writable stream; the client can disconnect and later reconnect to receive the rest of the output.

A simplified illustration:

import { DurableAgent } from "@workflow/ai/agent";
import { getWritable } from "workflow";
import type { UIMessage, UIMessageChunk } from "ai";

export async function chatWorkflow(messages: UIMessage[]) {
  "use workflow";

  const writable = getWritable<UIMessageChunk>();
  const agent = new DurableAgent({
    model: "anthropic/claude-sonnet-4.5",
    system: "You are a helpful assistant.",
  });

  await agent.stream({
    messages,
    writable,
  });
}

Now the Agent truly behaves like an autonomous system.

In ClawLess the process is more involved: the main workflow reads the current configuration from KV, builds a system prompt, loads tools from MCP, creates a DurableAgent, writes output to the UI message stream (and persists it), and finally saves state to Postgres SQL.

Hook Makes the Workflow Truly Interactive

Consider the case where a user continues to send messages on the web, or an IM webhook delivers more messages while the workflow is still running. We should follow‑up with the existing Agent instead of spawning a brand‑new workflow each time.

This is the basic logic of Human‑in‑the‑Loop (HITL). For more details see Wikipedia’s Human‑in‑the‑Loop.

Fortunately, Workflow provides hooks that enable this pattern. A hook lets a running workflow pause at a certain point, wait for an external event, and then resume.

The simplest external event is “the next user message”:

import { defineHook } from "workflow";

// Define a hook that receives an external event (the next user message)
export const messageHook = defineHook<{
  text: string;
  userId: string;
}>();

export async function conversation(sessionId: string) {
  "use workflow";

  const events = messageHook.create({
    token: "chat-" + sessionId,
  });

  // Wait for external events (the next user message)
  for await (const event of events) {
    console.log("Received", event.text, "from", event.userId);
  }
}

export async function POST(req: Request) {
  const data = await req.json();

  await messageHook.resume("chat-" + data.sessionId, {
    text: data.text,
    userId: data.userId,
  });

  return new Response("OK");
}

The same mechanism works well for tool approvals. For example, when the model wants to execute a high‑risk command—delete a file, send a message, place an order, transfer money—we should not run it directly. Instead we throw an approval request to the front‑end and wait for user confirmation.

See the AI SDK documentation on Tool Execution Approval.

Using workflow hooks means you don’t have to poll a database or write a complex state machine; the workflow suspends while waiting and resumes from the same state.

So the typical Agent workflow looks like this:

A user message hits the entry point.
The entry point checks whether the current session already has an active workflow.
If it does, the new message is sent back via a hook.
If not, a new workflow is created from scratch.

Context

Agents have a context limit. Token‑counting differs between models, but they all share one constraint: you must fit the system prompt, history, tool results, file inputs, and memory into the context window.

Moreover, as the context grows, model accuracy degrades and costs rise.

Two common approaches for handling long context are compression and pruning.

Compression

Compression rewrites “very long but still needed” history into a shorter representation. A typical pattern is: once a conversation reaches a certain length, ask the model to summarize early dialogue, key tool results, and confirmed user preferences, then remove the original messages from the current window.

On the next real model call you prepend the summary.

If you want more control, you can use a sliding‑window approach that includes the summary plus the most recent rounds and the current input.

import { generateText, type ModelMessage } from "ai";

export async function compactMessages(messages: ModelMessage[]) {
  const summary = await generateText({
    model,
    messages: [
      ...messages,
      {
        role: "user",
        content:
          "Please summarize our previous conversation and extract the key information that will help later.",
      },
    ],
  });

  return {
    summary: summary.text,
    recentMessages: messages.slice(-8),
  };
}

In a Workflow this is natural because the workflow already has its own lifecycle and external storage. After a round finishes you can write the summary to KV, delete the old messages, and keep only a “session summary” field. The durable session persists, but the context fed to the model does not grow indefinitely.

Pruning

Pruning does not try to understand the history; it simply cuts away parts that are unlikely to help the current round.

The AI SDK already provides pruneMessages, which can strip old reasoning, tool call results, approval traces, and empty messages before sending the payload to the model.

import { type ModelMessage, pruneMessages } from "ai";

export function buildContextWindow(messages: ModelMessage[]) {
  const pruned = pruneMessages({
    messages,
    reasoning: "before-last-message",
    toolCalls: "before-last-2-messages",
    emptyMessages: "remove",
  });

  const pinned = pruned.filter((m) => m.role === "system");
  const recent = pruned.filter((m) => m.role !== "system").slice(-12);

  return [...pinned, ...recent];
}

For Workflow‑based AI you typically call prepareStep before each model invocation to rewrite the window.

const result = await agent.stream({
  messages,
  writable,

  // prepareStep runs before each model call to reshape the context window
  prepareStep: async ({ messages: currentMessages }) => {
    return {
      messages: buildContextWindow(currentMessages),
    };
  },
});

Compression and pruning are not mutually exclusive; most production systems combine them according to design needs.

This is the idea of Context Engineering – see Anthropic’s article Effective Context Engineering for AI Agents.

Beyond that, we also need cross‑conversation, cross‑knowledge, or permanent shared context. For those cases we store data in external systems via tools rather than stuffing everything into the model’s context.

Tools

An Agent’s tools define its capability boundary.

Without tools it is just a chat model; with tools it can store memory, execute commands, learn skills, schedule tasks, or delegate work to sub‑Agents.

In the AI SDK, tools are first‑class citizens. A minimal tool definition looks like this:

import { tool } from "ai";
import { z } from "zod";

const tools = {
  remember: tool({
    description: "Save a useful fact into long‑term memory",
    inputSchema: z.object({
      note: z.string(),
    }),
    execute: async ({ note }) => {
      const memory = await buildMemory(note);
      return { ok: true, memory };
    },
  }),
};

Memory

Memory stores long‑term facts and user preferences.

You can keep it in KV, a database, or as files in Blob, and expose tools for the model to manage it.

For search, full‑text keyword search is convenient but has limits; two sentences may be highly related without sharing any words.

Consider RAG (Retrieval‑Augmented Generation) – letting the model retrieve relevant information from an external knowledge base while generating a response.

The simplest approach is vector‑embedding search: encode a sentence into a multi‑dimensional vector and find the most similar vectors in the space. Cosine similarity is a common metric:

$\operatorname{Similarity} = \hat{\mathbf{q}} \cdot \hat{\mathbf{d}} = \sum_{i=1}^{n} \hat q_i \hat d_i$

Normalize the similarity scores and sort.

In production we usually combine vector search with keyword search (hybrid search).

For a deeper dive into Memory, see OpenClaw’s Memory design.

Skills

Skills are more like file‑system‑based knowledge bases.

A Skill typically lives in a directory structure such as:

my-skill $ tree

my-skill/
    SKILL.md

    scripts/
    templates/
    examples/
    assets/

Skills describe how to do things, for example:

How to write a certain type of test
How to invoke an internal specification
How to generate code according to team conventions

We usually extract a Skill’s title and description and inject them into the System Prompt.

Skills were introduced by Anthropic; see Agent Skills Overview.

Execute Bash

Execution tools let the Agent actually interact with the outside world.

The most basic execution tool is a Bash tool that runs shell commands, bridging the Agent to a real environment.

In ClawLess we use @vercel/sandbox to implement the Bash tool.

Bash is the highest‑risk tool and requires strong isolation, careful approval, and sandboxing.

If you’re looking for a Serverless Bash tool or a sandboxed Bash implementation, check out our AI SDK X.

Tasks

When handling complex work we need to consider more categories.

Delayed and Scheduled Tasks

A delayed task notifies you after a certain amount of time.

ClawLess implements delayed tasks inside a Workflow using the sleep function.

import { sleep } from "workflow";

export async function remindTomorrow(taskId: string) {
  "use workflow";

  await sleep("1 day");
  await sendReminder(taskId);
}

A scheduled task (Cron Job) runs at a specific time repeatedly.

Implementation is similar; we use an infinite loop with sleep.

while (true) {
  await sleep("1 day");
  runTask();
}

Sub‑Agents

A sub‑task does not have to be a full‑blown Agent; it can delegate a small piece of work.

For example, the main Agent handles the conversation, but a specific research question could be handed to a cheaper, smaller model.

A minimal Sub‑Agent implementation:

import { generateText, tool } from "ai";
import { z } from "zod";

const delegateResearch = tool({
  description: "Hand off a focused research subtask",
  inputSchema: z.object({
    question: z.string(),
  }),
  execute: async ({ question }) => {
    const result = await generateText({
      model: "openai/gpt-4.1-mini",
      prompt: "Answer briefly and return only key facts:\n" + question,
    });

    return { summary: result.text };
  },
});

MCP and Other Tools

The Model Context Protocol (MCP) is a unified protocol that lets an Agent connect to external systems in a standardized way.

If you are building a domain‑specific Agent, MCP is often a better fit than a handful of ad‑hoc Skills.

ClawLess does not implement web search, browser navigation, etc., directly; instead we can plug those capabilities in via MCP.

Connecting to the Frontend

The front‑end that interacts with the Agent can be a web page, a Bot, or any other client.

Web Chat

The useChat hook we showed earlier is the simplest web‑chat solution; we won’t repeat it here.

Connecting to IM via Webhook

Most instant‑messaging platforms expose Bot capabilities (e.g., Telegram, Discord).

Bots typically receive messages either via long polling or webhooks.

Long polling means the Bot periodically (the “heartbeat”) asks the server for new messages; OpenClaw’s connectors work this way.

Webhooks are more efficient: the server pushes a new‑message notification to the Bot without the Bot having to request.

ClawLess uses the Chat SDK to connect to various IMs via webhook.

The Chat SDK is straightforward: create a Chat instance.

// Next: lib/bot.ts
import { Chat } from "chat";

const bot = new Chat({
  userName: "mybot",
  adapters: { slack },
  state: createRedisState(),
});

bot.onNewMention(async (thread, message) => {
  await agent.handleMessage(message);
});

Then expose an API route that handles the webhook.

// Next: app/api/webhooks/slack/route.ts
export const POST = bot.webhooks.slack;

Conclusion

By now you should see that building an Agent can be surprisingly simple.

We hope you combine these pieces to create your own Agents—it’s genuinely fun.

We are also building a universal sandboxed Bash that works in any JS Runtime, Serverless or embedded environments. If you’re interested, check out our AI‑SDK‑X documentation.

Welcome To Niapya's Blog

Mon, 27 Jul 2026 03:25:00 GMT

The author argues that, despite the dominance of AI‑generated “Vibe‑coded” blogs, a personal blog should remain fully under the author’s control, so they built a lightweight static‑site generator using Hono/JSX for templating, marked for Markdown, and UnoCSS for atomic styling, resulting in a site with zero client‑side JavaScript. They demonstrate a working prototype and outline future plans to evolve it into a full framework with plugins, a retro UI component library, and optional SSR, all open‑sourced on GitHub.

Yes, I finally have a blog.

2026 is the year Vibe Coding exploded. We've gotten used to using Code Agent to write any project, and the old “hand‑coded” approach is mocked as “ancient programming”. By now most people have lost the habit of writing code themselves; if they want a blog, they just Vibe a Next.js template, or even use an off‑the‑shelf SaaS blogging platform with Skills and let an Agent write the posts.

But I think a blog, as a personal platform, should be fully controlled by the author. So I want to build my own blogging framework, my own blog style, and my own blog content from scratch.

Building the Blog Framework

Since sites of this type usually don’t need server‑side logic, we call them static sites. What I need to create is a Static Site Generator (SSG).

The SSG workflow is simple: fetch a content source and parse it into documents, render them with templates, and output the result as website files. I want to control every step.

Step 1 – Fetch the content source and parse it into documents

The source can be anything: a database, a CMS, Markdown files, etc. To unify the process we define an interface like this:

export function definePost(
  input: {
    title: string;
    category?: string[];
    tags?: string[];
    content: string;
  },
): Post;

Now we can define our content anywhere, in any way. In the future plugins could pull content from file routes, databases, or even the browser.

Blog content (content) is usually written in Markdown, so I use marked to compile Markdown to HTML, together with marked‑highlight and highlight.js for code highlighting.

import hljs from "highlight.js";
import { Marked } from "marked";
import { markedHighlight } from "marked-highlight";

const markdownRenderer = new Marked({
  breaks: false,
  gfm: true,
});

markdownRenderer.use(
  markedHighlight({
    emptyLangClass: "hljs",
    langPrefix: "hljs language-",
    highlight(code, language) {
      const highlightLanguage = hljs.getLanguage(language)
        ? language
        : "plaintext";

      return hljs.highlight(code, { language: highlightLanguage }).value;
    },
  }),
);

await markdownRenderer.parse(markdown, { renderer });

Step 2 – Render with templates

Because we are producing website files, most SSGs tie the template closely to the HTML structure. If you pick a custom template language you have to define an AST and a compiler yourself—for example, Astro’s .astro files are a proprietary component syntax. You’d also need to build a toolchain for type checking and syntax highlighting, which hurts developer experience.

Some SSGs use React/Vue components as templates. Those feel nice to develop with, but they tend to be tightly coupled to the respective framework’s ecosystem and can unintentionally pull in client‑side JavaScript. For an SSG, pulling in any unnecessary client JavaScript by default is unwise.

So I chose a lightweight solution: JSX powered by Hono/JSX for templates. It lets us write JSX, render it on the server, and output an HTML string while keeping type safety. For pure static pages the resulting HTML files contain no framework‑related client code.

export function HtmlArticle({ html }) {
  return (
    <div
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

const app = new Hono()
  .get("/", (c) => {
    return c.html(<HtmlArticle html={markdownRenderer.parse(markdown)} />);
  });

Step 3 – Output as website files

After defining content and templates we need to define the site structure (aka routes). Since we’re using Hono/JSX, we can declare routes with an HTTP framework—Hono fits the bill. With Hono we can also spin up a dev server easily.

Later we could also use this approach for Server‑Side Rendering (SSR), but for now we focus on SSG.

Hono provides a toSSG method that pre‑renders the Hono app’s routes into static files at build time, allowing us to output static files directly from Hono.

Styling the Blog

Applying CSS in JSX has always been tricky—CSS Modules, until atomic solutions like TailwindCSS arrived.

We chose UnoCSS as our CSS solution because it generates atomic CSS on demand and offers a programmable generator API that can compile class names into CSS code.

import { createGenerator, presetWind4 } from "unocss";

const uno = await createGenerator({
  presets: [presetWind4()],
});

export async function compileAtomicCss(input: string): Promise<string> {
  const { css } = await uno.generate(input);
  return css;
}

For the default blog style I went with a classic Macintosh look. We’re planning to use Figma and create a corresponding UI component library to deliver a retro‑styled blog theme.

Future Plans

You may notice that this blog uses no client‑side JavaScript, which is exactly what I wanted. A static blog doesn’t need any client JavaScript.

The source code is available on GitHub.

Eventually we hope to turn this project into a real framework and release our own UI component library, along with features such as:

Plugin‑based RSS and Sitemap generation
Search and comment systems based on HTML Form
An online compiler
Possible full‑stack SSR support

Because we don’t rely on Vite and we avoid dependencies that only work in a Node.js environment, this framework could even run directly in the browser in the future.

Niapya Blog

What have we all done to create a catgirl?

Origin

Technical Design

Agent Architecture Designed on Cloudflare Durable Objects

Moving from Nuxt to TanStack Start in 6 Hours Using Agents

Three.js and VRM Pet

Bash Tool Is the Whole Harness

A Virtual FS

A Virtual Bash

Introducing Our New Protocol: Dialogue Transport Protocol

What the Protocol Looks Like

Streamed Parsing

Epilogue

Migrate to remix@3

A Glimpse of Remix v3

Why should we have a build step?

Preparations

Generating Tailwind CSS for SSR with Twind

Satori‑Generated Captchas

Migration Work

Betting on SSR Rendering

Injecting New CSS Capabilities

i18n, a11y, and Others

Deployment

Cloudflare Workers

Vercel

Deno

Conclusion

How to Build a Serverless Agent

Motivation

Design

Workflow as the Agent Runtime

Hook Makes the Workflow Truly Interactive

Context

Compression

Pruning

Tools

Memory

Skills

Execute Bash

Tasks

Delayed and Scheduled Tasks

Sub‑Agents

MCP and Other Tools

Connecting to the Frontend

Web Chat

Connecting to IM via Webhook

Conclusion

Welcome To Niapya's Blog

Building the Blog Framework

Step 1 – Fetch the content source and parse it into documents

Step 2 – Render with templates

Step 3 – Output as website files

Styling the Blog

Future Plans

Moving from Nuxt to TanStack Start in 6 Hours Using Agents