Give Codex a launch path for your agent app
Start from shadcn Create, install a production-ready Agent Demo slice through the registry, configure a provider, verify locally, and deploy. Use Foundation Chat for the fastest path, or choose the slice that matches your agent scenario. The source lives in the GitHub repository; the demo install follows the public shadcn registry namespace flow.
Before starting, ask the user whether they want the autopilot path or guided checkpoints. Do not assume the mode.
Start by creating a styled project in shadcn Create. Then add Foundation Chat as the recommended starter demo. It is the smallest production-ready slice of this repo's AI SDK plus AI Elements stack: one chat page, one API route, and the required AI Gateway env vars. If the provider choice changes after installation, use the AI SDK Providers docs as the reference before adapting the installed provider seam.
Quick point
Install the recommended starter demo
Foundation Chat is the smallest production-ready starting point: it drops a working chat page, API route, AI Elements UI, and AI SDK runtime wiring into the app you created.
pnpm dlx shadcn@latest registry add @agent-demos=https://agent-demos.hsawana9.com/r/{name}.json
pnpm dlx shadcn@latest add @agent-demos/foundation-chatCoding agents
Choose how your agent should operate
Both task briefs point the agent back to this guide as the source of truth. Before any setup starts, the agent should ask the user to choose a mode. Use autopilot for the fastest autonomous path, or use guided checkpoints when the user wants the agent to ask before theme, provider, API key, and deployment decisions.
Autopilot task brief
Let the agent create the app, install the recommended starter demo, configure the default provider, verify locally, and complete the Vercel deployment.
I want to quickly launch a production-ready AI project from a new shadcn Next.js app.
Use this guide as the source of truth before planning:
https://agent-demos.hsawana9.com/registry-guide
Follow the guide's autopilot path: create the shadcn Next.js app, install Foundation Chat as the recommended starter demo from the registry, configure the default AI Gateway provider env, verify one local chat message, then use the Vercel CLI docs to link or create the Vercel project, set the production env, and trigger a deployment.
Acceptance criteria:
- A new shadcn Next.js app is initialized.
- Foundation Chat is installed from @agent-demos.
- Local chat works with AI_GATEWAY_API_KEY.
- A Vercel deployment has been triggered.
- The deployment URL is reported.
- The deployed Foundation Chat URL is reported as <deployment-url>/demos/foundation-chat.Guided checkpoints task brief
Keep the same setup path, but require the agent to pause for shadcn Create choices, provider selection, API key setup, and deployment approval.
I want to launch a production-ready AI project from a new shadcn Next.js app, but I want to participate in the important setup decisions.
Use this guide as the source of truth before planning:
https://agent-demos.hsawana9.com/registry-guide
Follow the guide's guided checkpoints path. Ask the user before each checkpoint that needs a product or account decision: shadcn Create theme choices, model provider and API key choice, whether to deploy, and final deployment acceptance.
Foundation Chat should be installed as the recommended starter demo after the shadcn project is ready. When the code reaches provider configuration, default to Vercel AI Gateway. If the user already has a provider key or prefers another provider, read the AI SDK Providers docs first, then adapt the installed Foundation Chat provider seam and env contract to that provider.
Acceptance criteria:
- The user has chosen the shadcn Create setup or provided the generated command.
- Foundation Chat is installed from @agent-demos.
- The model provider is configured from AI Gateway or from the user's selected provider.
- Local chat works after the API key is configured.
- If the user wants deployment, a Vercel deployment is triggered and both the deployment URL and <deployment-url>/demos/foundation-chat are reported.Full paths
Pick the level of human involvement
Both paths start from shadcn Create, install Foundation Chat as the recommended starter demo, verify a local chat turn, and finish with deployment acceptance when Vercel is in scope.
Autopilot full path
Let the agent keep moving
Use this path when the goal is speed. The agent creates the project, installs the recommended starter demo, configures the default provider, verifies locally, then uses Vercel's CLI docs to deploy and report the result.
1. Create the shadcn Next.js app
Start from shadcn Create or the official installation docs. The created app should already have shadcn/ui configured before any registry item is added.
2. Install the recommended starter demo
Register the Agent Demos namespace, then add Foundation Chat from the registry. This copies the page route, API route, UI, provider env seam, and runtime helper into the new app.
pnpm dlx shadcn@latest registry add @agent-demos=https://agent-demos.hsawana9.com/r/{name}.json
pnpm dlx shadcn@latest add @agent-demos/foundation-chat3. Configure the default provider and verify locally
Default to AI Gateway authentication, add the env vars, run the app, and send one message on /demos/foundation-chat. If the user already supplied a provider preference before the run began, read AI SDK Providers before adapting the installed provider seam.
AI_GATEWAY_API_KEY=...
AI_GATEWAY_BASE_URL=https://ai-gateway.vercel.sh/v3/ai
AI_GATEWAY_CHAT_MODEL=openai/gpt-4.1-minipnpm dev
# open http://localhost:3000/demos/foundation-chat4. Deploy and report the working URLs
Use the Vercel CLI docs plus the link and deploy references. The acceptance result is a real deployment URL and the full Foundation Chat page URL at <deployment-url>/demos/foundation-chat.
Guided checkpoints full path
Keep the user in the loop
Use this path when the user wants to learn the stack or make account and provider choices directly. The agent should pause at each checkpoint before making the next setup decision.
1. shadcn Create checkpoint
Ask the user to open shadcn Create. The user chooses the style, color, radius, and project shape, then gives the generated command back to the agent. The agent can run that command and continue from the created project folder.
2. Registry starter checkpoint
After the shadcn project exists, install Foundation Chat as the recommended starter demo. This confirms the registry namespace, route placement, AI Elements UI, and runtime wiring before deeper project adaptation begins.
pnpm dlx shadcn@latest registry add @agent-demos=https://agent-demos.hsawana9.com/r/{name}.json
pnpm dlx shadcn@latest add @agent-demos/foundation-chat3. Provider and API key checkpoint
Once the code is installed, ask whether to continue with the default AI Gateway setup or use a provider key the user already has, such as Moonshot, DeepSeek, or MiniMax. If the provider changes, read AI SDK Providers first, install the documented provider package, then adapt the installed Foundation Chat provider seam and env contract.
4. Local completion checkpoint
Treat local setup as complete only after the selected provider key is configured, the dev server starts, and /demos/foundation-chat returns one visible assistant response.
5. Deployment checkpoint
Ask whether the user wants to deploy now. If yes, follow the Vercel CLI docs. Link or create the project, set the required production env vars, trigger a deployment, then report the deployment URL and <deployment-url>/demos/foundation-chat.
Repo setup
Add a small skill kit for future agent work
Once the new chat project is running, install these optional skills in the same repository. Four come from Matt Pocock's skills, and the docs memory skill comes from agent-docs-system-skill. Together they help an agent align on the plan, keep durable project docs, use focused tests, review architecture, and split larger work into handoff-ready slices.
Recommendation: treat this as a lightweight engineering setup. grill-with-docs and project-docs-system give the agent a DDD-style shared language and project memory; tdd and improve-codebase-architecture keep behavior changes testable while the code is refactored; to-issues is the workflow helper for splitting larger work into small vertical slices.
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture
npx skills add https://github.com/mattpocock/skills --skill tdd
npx skills add https://github.com/mattpocock/skills --skill to-issues
npx skills add https://github.com/multicul-silver-wolf/agent-docs-system-skill --skill project-docs-systemOther registry demos
Special setup notes
These demos are registry-backed today. After the namespace is registered, add the demo that matches your project and configure its service requirements from the setup note.