A Conversational Website Builder with the Claude Agent SDK

TL;DR

SiteSpin is a new kind of website builder that focuses on conversation and works best on mobile devices. It uses the Agent SDK to go beyond what current agentic tools can do. SiteSpin takes a fresh approach to building websites.

Read on to learn more about the background and technical details.

Site builders and their limitations

Most site builders today claim to simplify website creation for non-technical users, but the truth is that users need to make a number of design and structural decisions, usually by choosing a template and arranging components themselves. This approach is inherently limited and can be frustrating, as it demands both time and an understanding of what makes a website effective. The result is often a generic site that lacks distinction or real utility for the user.

The main issue is that current website builders expect users to do most of the work. This is the traditional way, and it hasn’t changed much; even AI tools like Claude Code still need you to know what makes a good website, what accessibility and SEO mean, and how to give the right prompts. Instead of making things easier, these tools put the responsibility back on the user.

My process for building a new website often involves using Claude Code and referencing well-structured websites. While this works, it still relies on someone who understands what makes a good website and how to guide the process. For most people, the need is simple: a strong web presence, whether for business, discoverability, or credibility, but the path to get there is unnecessarily complex.

If Claude Code can scaffold and generate a solid website with clear guidance, why can’t this process be scaled to be accessible for everyone, regardless of technical background or design expertise?

SiteSpin aims to solve this by taking a different approach: providing an easier way to establish a web presence, without requiring users to learn the nuances of website structure. The philosophy is to reverse the current mentality: instead of making the user responsible for every aspect of setup, it takes on the heavy lifting. Unlike traditional builders, SiteSpin asks a few questions, makes many assumptions, and aims to deliver a well-architected site with minimal code, focusing on content and proper structure, good accessibility, and 100% Lighthouse scores.

The Agent SDK introduces new options and a better user experience

Claude released the Claude Agent SDK, which powers the agentic loop behind Claude Code and enables it to be programmable. Now, instead of just using Claude through chat or the command line, you can use it in workflows that let it use tools, read and edit files, run commands, manage context, and work through tasks step by step.

For website generation, this creates a new opportunity. If we can clearly define what makes a good website — strong visual hierarchy, clean spacing, good typography, relevant content, proper image placement, a responsive layout, and a clear conversion flow — then Claude can aim for that standard.

The real change is in the loop itself. Claude can create a first draft, check the result, adjust the structure, improve the text, refine the layout, and keep going until the site meets a set quality level. With a simple, conversational onboarding where the user shares their business, target audience, tone, and goals, building a website can feel less like picking a template and more like working with an agent who understands design and how to build it.

Technical deep dive

At a basic level, the idea is simple: we need an iOS app or another client to use it. I chose mobile because there aren’t many options there, and usually you need a laptop to set up a new website.

The backend service handles business logic and exposes a REST API, intentionally separating concerns from the Agent SDK environment. This separation ensures the API remains responsive to client requests, while the agent process — which requires considerable memory — runs independently. Website generation jobs are queued rather than processed simultaneously, enabling predictable scaling and resource management. All site files are stored in PostgreSQL, allowing the language model direct access to the source code and lessening traditional filesystem issues. This architecture underpins SiteSpin’s reliability and flexibility.

Quick overview

The core workflow is as follows: a chat client collects a user’s brief and submits it to the API, which enqueues a generation job. A worker process picks up the job and initiates the agent loop, where the site is actually generated. The resulting static site is deployed to a CDN via Vercel for fast, reliable delivery. All supporting infrastructure was designed to keep the agent loop efficient and isolated from real-time user requests. The rest of this section investigates the details of what happens inside the agent loop.

Component map

SiteSpin’s architecture is based on two main processes — a stateless API and a dedicated worker — alongside a single PostgreSQL database within a unified container. The API handles short-lived tasks (authentication, validation, status checks, queuing), while the worker undertakes long-running operations, such as job processing, site generation, building, and deployment. State is managed exclusively in PostgreSQL and never shared via memory or message buses. This deliberate separation permits asynchronous job handling, so long-running generations don’t block HTTP connections, and allows the API and worker to scale or restart independently. All client requests are routed through the API, which centralizes authorization, rate limiting, and business logic. Direct database access is restricted, except for read-only authentication. This unified approach delivers consistent capabilities across web and iOS clients, minimizing feature drift and simplifying maintenance.

Generation timeline

A key insight from the generation timeline is the uneven distribution of time across steps. Infrastructure operations — enqueueing, NOTIFY wakeup, Astro build, and Vercel deployment — happen rapidly, often within seconds. However, the bulk of the four-minute wait occurs inside the agent loop itself: the model reads the brief, defines the site structure, writes components, refines copy, triggers the build, reviews the output, and iterates. To meaningfully speed up site generation, improvements should focus on prompts, model efficiency, and workspace optimization rather than on infrastructure or deployment.

Progress reporting comes directly from the loop. The agent uses a custom tool called update_status(stage, percent) at key points: after reading the brief, deciding the structure, writing the hero section, and after the build. Each call writes to the job row. The client checks that row every second. There’s no separate progress channel, no WebSocket, and no extra system deciding what the user sees. The model itself is the main source of truth for what’s happening.

Agent loop deep dive

Here, the Agent SDK demonstrates its strengths. Claude is provided with a working directory, a system prompt, and a tightly scoped set of tools — Read, Write, Edit, Bash, and a custom update_status utility. No web access, shell access outside the workspace, database connections, or network calls are allowed. The sandbox is enforced by the SDK’s current working directory and an explicit allowed_tools list, ensuring that the model can access only resources and actions that have been deliberately provisioned.

Each agent loop begins with a real Astro project template pre-copied into the workspace. Rather than generating a file tree from scratch, Claude extends and modifies this known-good baseline. This design decision avoids the inefficiency and inconsistency of model-generated scaffolding. By working within a pre-built, compilable structure, the model can focus on high-value tasks — copywriting, layout, and visual hierarchy — instead of low-level configuration and boilerplate.

The custom update_status tool acts as an in-process MCP server. When Claude reports progress, it invokes update_status, which writes a new row to Postgres. The agent loop directly updates the UI, so the model itself drives the user-facing loading spinner and progress indicators.

Edits follow the same pipeline as the initial generation, with one key distinction: the resume=session_id parameter. By resuming the previous session, the SDK restores all files from the first run, allowing the model to make targeted, incremental changes rather than rebuilding the entire site. This approach dramatically reduces both cost and latency. Initial generation typically costs around $1 and takes 3–4 minutes, while an edit costs about $0.10 and completes in just 20 seconds. The performance improvement comes not from a different model or prompt, but from the SDK’s session protocol, which eliminates redundant file reads and automatically improves the editing process.

Image placement is a content-routing problem

When a user uploads a photo, we deliberately avoid asking them where it should go. Most users aren’t familiar with optimal website structures — if they were, they wouldn’t need a chat-based builder. To streamline the process, every uploaded image is immediately classified.

Each image is processed through a Claude vision call at upload time. The classifier assigns a role (hero, about, gallery, product, team, testimonial, logo), identifies the subject, suggests a fit, and provides a caption hint. The agent receives this formatted input and places images accordingly, only deviating if the user’s brief specifies otherwise. Decisions before the agent loop save time and resources, and image routing is an ideal candidate for early resolution.

Job queue state machine

Using Postgres as a job queue is a deliberate architectural choice, often questioned but effective for this context. The queue consists of a single table: inserting a row enqueues a job, and a worker claims it via an atomic UPDATE with FOR UPDATE SKIP LOCKED. This ensures two workers cannot claim the same job, as the row is locked on access. Status transitions are handled via standard UPDATE statements on the same row.

The claim is one statement:

UPDATE jobs
  SET status='claimed',
      worker_id=$1,
      lease_until=now()+'300s'
  WHERE id = (
    SELECT id FROM jobs
    WHERE status='queued'
    ORDER BY created_at
    FOR UPDATE SKIP LOCKED
    LIMIT 1
  )
  RETURNING *;

Common queue failure modes — lost messages, duplicate deliveries, and head-of-line blocking — are either non-issues here or easier to solve within this single-table design than with additional infrastructure. Workers acquire a 300-second lease when claiming jobs, and a periodic sweeper reclaims any jobs that exceed their lease. The full failure recovery mechanism fits into a single SQL function.

The wake-up mechanism relies on Postgres LISTEN/NOTIFY: each job insertion triggers a notification, awakening the worker within milliseconds. A backup 10-second polling loop ensures reliability in the rare event of a dropped notification. This mixed approach is cost-effective, transparent in psql, and eliminates the need for extra services.

Edit vs. generate

Both generation and editing are handled by a unified function with two modes. They share the same code path, prompt template, toolset, and sandbox. The sole difference is the resume parameter — toggling it is as simple as updating a dictionary key.

When a session is resumed with a session ID, the SDK restores the former conversation and loads all existing files into the model context. This permits precise, surgical edits rather than a full site reconstruction. The result is a dramatic reduction of cost and latency by roughly an order of magnitude. These improvements stem not from a model or a prompt change, but from leveraging persistent conversation state. The SDK’s resume primitive is the foundation of the smooth editing experience.

Page weight comparison

Most small-business homepages don’t need the bloat of JS frameworks, slideshow libraries, analytics SDKs, chat widgets, font loaders or other extras bundled by default in many hosted site builders. What matters are five content sections, a couple of images, a contact link, and solid typography — bytes on the wire should reflect this simplicity. SiteSpin sites are compiled Astro projects: HTML is generated at build time, and Tailwind runs in the same step, emitting only CSS classes actually used. No components hydrate on the client, because everything compiles to static markup. Achieving a Lighthouse 100 isn’t an optimization goal; it’s the baseline, enforced by strictly restricting what the agent can introduce.

Moving forward

There are many directions for SiteSpin to evolve, but I’ve intentionally kept the functionality minimal to start.

Enabling users to download source code and continue development independently is my top priority — minimizing lock-in so users stay because the service delivers real value, not because they’re forced to. While the platform allows post-onboarding changes, there’s a clear need for more upfront customization for advanced users: broader styling options, support for multiple site types, and the ability to reference sites they already like for inspiration.

A built-in scheduling module is another high-value addition; most local businesses need booking functionality, flexible time slot configuration, and immediate booking capability.

I’m eager for user feedback and to iterate based on real-world needs. As new and better models become available, SiteSpin will only improve with each update to the agentic SDK, which enhances site generation. I’m particularly interested in more efficient tool invocation and faster generation times. With the recent release of OpenAI’s agent SDK 2, I’m open to exploring new providers, but so far, Claude Code has delivered excellent results.

SiteSpin is available on the App Store.