Vibe Coding Guide

Build a custom chat experience with Claude Code, OpenAI Codex, or Google Antigravity — even if you've never touched the SDK before. This guide walks you through the entire flow, from "I have an empty folder" to "I have a working, branded chat I can show off."

"Vibe coding" means describing what you want in plain English and letting a coding agent do the wiring. This SDK is built for it: typed message parts, mock-first transport, schema-backed tools, and an installable agent pack that teaches your agent the patterns it should follow.

Table of Contents

• Who This Is For
• What You'll Build
• Before You Start
• Pick Your Agent
• Step 1: Scaffold The App
• Step 2: Open The Project In Your Agent
• Step 3: Ask The Agent To Build A Chat
• Step 4: Run It
• Step 5: Make It Yours
• Step 6: Verify Before Shipping
• Recipes To Remix
• Troubleshooting
• Where To Go Next

Who This Is For

You should feel at home here if you are:

• A weekend hacker who wants a real, polished chat UI in an afternoon.
• A product engineer prototyping a new support, commerce, or account experience.
• A designer or PM who pair-codes with an agent and ships what works.
• A team lead evaluating the SDK with a small team.

You do not need to be an expert in TypeScript, React, or chat protocols. You do need to know how to run a shell command and open a project in an editor.

What You'll Build

By the end of this guide you will have:

• A Next.js app running on http://localhost:3000.
• A custom chat surface powered by gecx-chat with streaming, typed messages, and at least one tool call.
• A mock transport so you can develop without any credentials.
• A short test that proves it works.

Everything stays on your laptop. No API keys required.

Before You Start

Install the basics if you don't already have them:

• Node.js 20 or newer — download here.
• pnpm 9.15+ — run corepack enable to make it available.
• Git — most agent tools assume a git repo.
• One of: Claude Code, Codex CLI, or Google Antigravity installed.

Sanity-check your environment:

node --version    # v20.x or newer
pnpm --version    # 9.15.x or newer
git --version

Pick Your Agent

All three agents work. The patterns are the same; only the files and commands differ.

The repo has tri-agent parity as a first-class goal. The canonical skill source at skills/headless-chat-vibe-coding/ syncs on pnpm install to .claude/skills/, .agents/skills/, and .agent/skills/. AGENTS.md, CLAUDE.md, and GEMINI.md are pointer files. Don't overthink the choice — pick whichever agent you already have installed; the rest of the guide works for all three.

MCP server v1

Each of the three agents can also load the SDK's MCP server, which exposes 14 tools, 12 resource templates, and 14 prompts (10 general + 4 commerce). Install with one command:

pnpm dlx gecx-chat-mcp-server --install

This writes the right config file for each detected agent (merging non-destructively) so prompts like "use the gecx-chat MCP to add a new client tool" work without further setup.

gecx lab init

For agentic iteration inside your running app, gecx lab init --template <commerce|support> generates a /lab route powered by the @gecx/lab package. The route ships with an agent-target picker (CC / Codex / AG), per-agent prompt variants, and copy/verify/walkthrough buttons.

Walkthrough artifact protocol

gecx walkthrough capture --task=<task-id> emits a PNG + manifest pair conforming to schemas/walkthrough.schema.json. gecx walkthrough verify round-trips a captured artifact. The format is the cross-agent "show your work" contract — use it when you want an agent to prove a flow before merging.

Step 1: Scaffold The App

You have two zero-config paths.

Fastest: Start Studio — a 4-step wizard that downloads a ready-to-run repo.

pnpm dev:studio
# or open start.gecx.chat

Pick a template (Support or Commerce), choose tools and a handoff target, optionally enable analytics, and click Download. Unzip and run — install-to-first-conversation in under three minutes. The downloaded project includes AGENTS.md, CLAUDE.md, and the headless-chat-vibe-coding skill, so the rest of this guide picks up unchanged after step 1. See Start Studio.

Manual: create-gecx-chat — one CLI command gives you a fresh Next.js + GECX Chat project with the agent pack pre-installed, a mock-first chat surface, a smoke test, and a verify.sh script:

pnpm create gecx-chat my-chat
cd my-chat
pnpm install

You can also use npm create gecx-chat my-chat or yarn create gecx-chat my-chat.

The scaffolder prompts for framework (next / vite-react / vanilla), template (support / commerce / blank), and backend (mock / gecx / custom). Accept the defaults or pass them as flags:

pnpm create gecx-chat my-chat -- --framework next --template support --backend mock

You now have a project that looks like this:

my-chat/
  app/page.tsx                                            # mock-first chat component
  test/gecx-chat-smoke.test.ts                            # passes out of the box
  AGENTS.md                                               # for Codex + Antigravity
  CLAUDE.md                                               # for Claude Code
  .agents/skills/headless-chat-vibe-coding/SKILL.md        # canonical SDK skill
  .claude/skills/headless-chat-vibe-coding/SKILL.md        # canonical SDK skill
  verify.sh                                                # typecheck + test + doctor
  package.json
  tsconfig.json
  next.config.mjs

Commit it before you start prompting an agent — you'll want a clean baseline:

git init && git add . && git commit -m "chore: scaffold gecx-chat app"

Already in an existing app? Run pnpm exec gecx agent-pack init --out . in any project to drop in the agent pack without scaffolding a new app.

Step 2: Open The Project In Your Agent

Claude Code

claude

Claude reads CLAUDE.md automatically on the first turn. If you want to confirm, ask: "What does this project's CLAUDE.md say?"

OpenAI Codex

codex

Codex reads AGENTS.md from the project root and walks up the directory tree merging guidance. To confirm: "Summarize the agent rules you're following for this repo."

Google Antigravity

Open the project folder from the Antigravity workspace launcher. Antigravity loads AGENTS.md and any .agents/skills/ it finds, then asks you whether to run in Plan Mode or freeform. Plan Mode is recommended — it generates a checklist artifact you can review before code lands.

Step 3: Ask The Agent To Build A Chat

Paste this exact prompt into your agent. It is calibrated for this SDK:

Build a working chat experience with `gecx-chat` in this Next.js app.

Use the installed Headless Chat SDK skill (.agents/skills/headless-chat-vibe-coding
or .claude/skills/headless-chat-vibe-coding). Follow it.

Requirements:
- Mock-first. Use `createMockTransport` and `scenarioCatalog.list()` from
  `gecx-chat/testing`. No real credentials.
- Use `useChatSession` and `MessagePart` from `gecx-chat/react`.
- Render `message.parts` with `<MessagePart key={part.id} part={part} />`.
- Add one client tool with `defineClientTool`: `lookup_order(orderId)`.
  Include a JSON Schema, `timeoutMs`, and `ctx.signal`. Approval not required.
- Add a Stop button while streaming.
- Add a Vitest smoke test using `createMockChatClient` and `scenarioCatalog`.
- Do not put secrets in browser code. Do not use `dangerouslySetInnerHTML`.

Verify with `pnpm typecheck` and `pnpm test` before you finish.

The agent will:

1. Read the Skill and the SDK docs it points at.
2. Add a Chat.tsx component (or similar) under app/.
3. Wire useChatSession with the mock transport.
4. Register the lookup_order tool.
5. Add a Vitest file and run it.

If your agent supports plan-first mode (Antigravity, or Claude Code with /plan), let it produce the plan first. Skim, then approve.

Step 4: Run It

pnpm dev

Open http://localhost:3000 and send a message. You should see:

• A streamed assistant reply.
• The Stop button appearing mid-stream.
• The lookup_order tool firing if you ask "Where is order ORD-1234?"

If something is off, ask your agent: "Open the running app and tell me what's broken." Antigravity can take a screenshot and reason about it; Claude Code and Codex can read the dev server logs.

Step 5: Make It Yours

Once the baseline works, layer on personality. Try one of these follow-up prompts:

Brand it

Style the chat to match this brand: <paste 2–3 sentences about the brand,
colors, and tone>. Use CSS modules. Keep the message list accessible —
ordered list, live region for streaming text, focus management on send.

Add product cards

Add a typed `product-carousel` renderer. Use the recipe at
recipes/product-carousel/ from the SDK monorepo as the reference shape.
Add a mock scenario that returns at least one product card so I can see it.

Add live-agent handoff

Add a "Talk to a human" affordance. Use the SDK's handoff state machine.
Show requested → queued → connected → ended states. Use the mock handoff
scenario for local proof.

Add a real backend later

Swap the mock transport for a real one. Implement a `ChatTransport` adapter
that calls /api/gecx-chat-proxy on this app. Keep the mock transport
available behind a NEXT_PUBLIC_USE_MOCK=true env flag.

Each follow-up is a single prompt. The Skill keeps the agent aligned to SDK rules so you don't have to re-explain them every time.

Step 6: Verify Before Shipping

The scaffold includes a verify.sh that runs typecheck, tests, and gecx doctor (which scans your source for five SDK footguns) in one command:

./verify.sh
# or, equivalently:
pnpm exec gecx verify

gecx doctor flags these footguns automatically:

If verify.sh exits non-zero, ask the agent to fix the findings:

Run ./verify.sh. Read every doctor finding (file, line, rule). Fix the
root cause for each. Re-run ./verify.sh until it exits 0.

A green verify.sh + a manual click-through is the bar for "done."

Recipes To Remix

The repo ships copy-owned recipes you can drop into your app. Each recipe is a folder with a README, code, and tests:

Tell your agent: "Install the <recipe-name> recipe into this app." It will copy the files, wire them up, and add a smoke test.

Troubleshooting

For a fuller list, see the Error Codes Reference. To produce a redacted bug report your team can hand back to support, call chat.createDebugBundle() from the running app.

Where To Go Next

• Agent Prompt Library — 20+ copy-paste prompts for common follow-ups (debug, deploy, extend).
• Product Guide — plain-language tour of the SDK's architecture and product model.
• React Quickstart — the same chat, hand-built without an agent.
• Client Tools Guide — approval flows, timeouts, and validation in depth.
• Generative UI Guide — let the AI design the UI layout with A2UI.
• Testing Guide — mock client, scenario fixtures, and Playwright e2e patterns.

When you're ready to ship to production: Proxy Deployment covers the server-side boundary, redaction, and rate limiting your live transport will need.