Skip to content

v0.1.0-rc.1 — Generative UI Protocol, first public release candidate

Pre-release
Pre-release

Choose a tag to compare

View all tags
@wanseob wanseob released this 24 May 01:35
v0.1.0-rc.1
9ced874

First public release candidate of @ggui-ai/* — initial npm publish, no prior version on the registry.

What ggui is

The Generative UI Protocol — an MCP-based open standard letting an AI agent describe a UI in natural language; the runtime generates an ephemeral, fully-typed, interactive React component the user can use immediately. No agent-side glue code; the protocol's tool descriptions teach the agent the wire flow.

Quick start — pick your path

1. Build an agentic app from the template

Most direct path if you want to ship an agent — the template scaffolds chat UI + MCP server + sample agent SDK loop in one repo.

  1. Open https://github.com/ggui-ai/agentic-app-template
  2. Click "Use this template" → create your repo → clone it
  3. Run /bootstrap in Claude Code (or pnpm bootstrap) — picks your agent SDK (claude-agent-sdk / openai-agents-sdk / google-adk), fetches it into servers/agent, seeds .env.local
  4. Add an API key for your chosen SDK
  5. pnpm dev:ggui / pnpm dev:todo / pnpm dev:agent — three terminals, then open http://localhost:6790

2. Self-host the OSS MCP server + test from claude.ai

For testing the ggui protocol against a real chat host. Localhost won't work from claude.ai — you need a public HTTPS URL, which cloudflared provides for free.

# terminal 1 — boot the OSS MCP server
npm install -g @ggui-ai/cli
ANTHROPIC_API_KEY=sk-… ggui serve --mcp-only       # http://127.0.0.1:6781/mcp

# terminal 2 — expose it to the public internet
cloudflared tunnel --url http://127.0.0.1:6781     # prints https://<random>.trycloudflare.com

Then in claude.ai → Settings → Connectors → Add custom connector, paste https://<random>.trycloudflare.com/mcp. Ask Claude to render any UI; the server generates and serves the component back into the chat.

(Install cloudflared via your package manager: brew install cloudflared on macOS; apt install cloudflared on Debian; or download from cloudflare.com/products/tunnel.)

3. Use the hosted ggui.ai cloud — mcp.ggui.ai (deploying soon)

For production, sign up at https://ggui.ai → create an app → get a managed MCP URL (form: https://mcp.ggui.ai/<app-id>/mcp). Paste into claude.ai's connector settings — no self-hosting, no tunnel, no key management.

🚧 The hosted endpoint is deploying — coming in a follow-up rc soon. Use path 1 or 2 in the meantime.

Building an agent that talks to a ggui MCP? Use the recommended posture-only system prompt from @ggui-ai/protocol:

import { GGUI_AGENT_SYSTEM_PROMPT } from '@ggui-ai/protocol';

The protocol's per-tool descriptions + the MCP server's instructions field teach the wire flow — no procedural script needed in your prompt.

Docs: https://docs.ggui.ai · Repo: https://github.com/ggui-ai/ggui · Template: https://github.com/ggui-ai/agentic-app-template

What's in the box (34 packages)

Layer Packages
Protocol + types @ggui-ai/protocol, @ggui-ai/artifact-manifest, @ggui-ai/gadget-signing
Wire (component ↔ agent) @ggui-ai/wire, @ggui-ai/channel-client, @ggui-ai/host-streams
Design system @ggui-ai/design, @ggui-ai/gadgets
Generation pipeline @ggui-ai/ui-gen, @ggui-ai/blueprint-probe, @ggui-ai/predefined, @ggui-ai/preview-a2ui
Runtime @ggui-ai/iframe-runtime, @ggui-ai/ggui-react, @ggui-ai/ggui-react-native, @ggui-ai/chat-self-hosted, @ggui-ai/agent-runtime
MCP server @ggui-ai/mcp-server, @ggui-ai/mcp-server-handlers, @ggui-ai/mcp-server-core, @ggui-ai/negotiator
Registry @ggui-ai/registry-core, @ggui-ai/registry-server, @ggui-ai/ui-registry
CLI + tooling @ggui-ai/cli, @ggui-ai/project-config, @ggui-ai/dev-stack, @ggui-ai/sandbox, @ggui-ai/embedding-local, @ggui-ai/console, @ggui-ai/shared
Conformance + testing @ggui-ai/protocol-conformance, @ggui-ai/protocol-reference-server, @ggui-ai/ui-visual-tester

Headline additions

  • DTCG-aligned design system — single canonical DtcgTheme shape with Material 3 surface-role pairs (surface/onSurface/surfaceVariant/onSurfaceVariant/container/onContainer/outline/outlineVariant), full 50–900 scales for success/warning/error/info, WCAG-aligned accessibility tokens, 12-stop zIndex ladder, composed motion.transition shorthands. Seven shipped themes (light/dark + five branded presets).
  • Wire SDK with runtime safety net — useAction includes task-scoped duplicate-dispatch coalescing so the LLM-generated double-handler pattern (<Card as={Clickable}> wrapping <Checkbox onChange>, both wired to the same action) cannot silently double-fire a user click. Loud console.warn on every suppression in both dev and prod; structured observability via WireConfig.onDispatchSuppressed for telemetry routing.
  • Tier-0 static checks — a precise AST detector blocks the nested-interactive double-wire pattern at gen time with a fail-level rule; the broader regex stays at warn-level (false-positive-aware). Pattern documented in docs/principles/no-silent-block.md.
  • Protocol verification suite — full scenario coverage including the canonical LLM-to-LLM round-trip (scenario 7), now CI-verified.
  • First-class operator path — ggui CLI (serve/blueprint/theme), project-config package for ggui.json schemas, hosted-runtime examples.

Verification

  • Publish gate (clean-room consumer registry round-trip): ✅
  • Source half (install / build / typecheck / unit / e2e including LLM scenarios): ✅
  • Scenario 7 (full LLM-to-LLM wire round-trip): ✅ 10/10 local + ✅ CI

Stability promise

This is a release candidate. Names and shapes for 0.1.0 (stable) are expected to land unchanged from rc.1 absent surfaced critical issues during the rc window. Once 0.1.0 ships, the public --ggui-* token surface and the DtcgTheme shape become semver-stable: renaming a token name or changing a type's required fields requires a major version bump.

Known limitations

  • LLM-generated UI quality depends on the model. We've tested against Claude (haiku 4.5 + opus 4.7); other providers via LiteLLM work but quality varies.
  • The protocol's nextStep action-routing is a hint, not enforcement — agents that ignore it just don't auto-chain (no protocol violation).
  • The OSS path is single-tenant; multi-tenant production runtimes are out of scope for the OSS release.

Issues / feedback

Open an issue at https://github.com/ggui-ai/ggui/issues — please include the package + version (@ggui-ai/<pkg>@0.1.0-rc.1) and a minimal reproduction.

Co-Authored-By: Claude Opus 4.7 (1M context) — pair-programmed throughout the rc.1 prep.

Assets 2
Loading