> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstflow.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up with an AI agent

> Copy one prompt into Claude Code, Cursor, or any coding agent and have it wire FirstFlow into your app end-to-end.

If you use a coding agent (Claude Code, Cursor, Codex, …), you don't have to follow the [Quickstart](/self-hosting/quickstart) by hand. Copy the setup prompt below, paste it into your agent **from inside a clone of `firstflow-oss`**, answer the couple of questions it asks, and it wires everything up.

<Note>
  The agent can do the code install, build, provider, sample experience. It
  **cannot** create your Supabase project or run SQL, so it will pause and ask
  you to do those two things (and to paste your keys). That's expected.
</Note>

## How to use it

1. **Clone the repo** and open it in your agent: `git clone https://github.com/firstflowdev/firstflow-oss && cd firstflow-oss`.
2. Put (or scaffold) your app inside the workspace see [Quickstart](/self-hosting/quickstart).
3. **Copy the setup prompt** (expand below, hit the copy icon) and paste it into your agent.
4. When it pauses, create a Supabase project, run `schema.sql`, and paste your keys.

## The setup prompt

<Accordion title="Show & copy the setup prompt" icon="clipboard">
  ```text Setup prompt theme={null}
  You are integrating FirstFlow into this repository. FirstFlow is an open-source (MIT) SDK there is NO FirstFlow server, dashboard, or npm package. It runs client-side and persists to the developer's own Supabase. Follow this exactly and do not invent APIs or options.

  GROUND TRUTH do not deviate:
  - Packages: "@firstflow/runtime" (React widget), "@firstflow/runtime-server" (optional Node LLM observability), "@firstflow/config-schema" (types + Supabase migrations). They are NOT on npm they are consumed from this firstflow-oss monorepo via workspace:*, and the app lives inside this workspace.
  - FirstflowProvider accepts ONLY these props: user (optional), experiences, persistence (optional), onEvent (optional). There is NO apiUrl, agentId, publishableKey, conversationId, or realtime socket. Do not add them.
  - Experiences are authored as firstflow/experiences.json in the repo and imported at build time. There is no dashboard.
  - FirstFlow reads NO API key. If you wrap an LLM, the developer's own client supplies the key.
  - The link between front-end and back-end is user.id. A conversationId / sessionId is owned by the app's own chat code and passed only to the server SDK never to the provider.

  STEPS:
  1. Confirm this repo is firstflow-oss: it has packages/sdk-frontend, packages/sdk-backend, packages/config-schema. If not, STOP and tell the user to clone firstflow-oss and place their app inside its workspace.
  2. Detect the app's framework (Next.js vs Vite/React) from its package.json and config files. Find the app folder.
  3. Wire the workspace:
     - Ensure the app's folder is covered by a glob in pnpm-workspace.yaml (add "apps/*" or the app's path if missing).
     - Add to the app's package.json dependencies:
         "@firstflow/runtime": "workspace:*",
         "@supabase/supabase-js": "^2.45.0"
       (also "@firstflow/runtime-server": "workspace:*" if the app has a backend).
     - Run "pnpm install" then "pnpm build" from the repo root.
  4. Create firstflow/experiences.json in the app with this sample (skip if a file already exists):
     [
       {
         "id": "exp_welcome",
         "name": "Welcome",
         "type": "guide",
         "status": "active",
         "trigger": { "on": "page_load", "delay": 1 },
         "frequency": "once_per_user",
         "steps": [
           { "id": "hi", "type": "message", "title": "Hello", "content": "Welcome!", "cta": "Get started" },
           { "id": "done", "type": "thank_you", "title": "You're all set", "confetti": true }
         ]
       }
     ]
  5. Mount the provider in a client component, importing "@firstflow/runtime/styles.css". Read env with the framework's convention Next.js: process.env.NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY; Vite: import.meta.env.VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY. Build the Supabase client, then:
       import "@firstflow/runtime/styles.css";
       import { FirstflowProvider, FirstflowWidget } from "@firstflow/runtime";
       import { createSupabasePersistence } from "@firstflow/runtime/supabase";
       import experiences from "<path>/firstflow/experiences.json";
       // <FirstflowProvider experiences={experiences} persistence={createSupabasePersistence(supabase)}>
       //   {children}<FirstflowWidget/>
       // </FirstflowProvider>
     Pass user={{ id, traits }} from the app's existing auth if present; otherwise omit user (the runtime uses a stable anonymous id).
  6. (Only if the app makes LLM calls and wants observability) In a server route, build a service-role Supabase client (SUPABASE_SERVICE_ROLE_KEY, server-only) and wrap the LLM client:
       const ff = new Firstflow({ persistence: createSupabaseLLMPersistence(serviceClient) });
       const ai = ff.wrap(new Anthropic());   // or new OpenAI(); the key comes from YOUR client
     Tag calls with firstflow: { userId, sessionId }.
  7. HUMAN-ONLY you cannot do these. Print them clearly and PAUSE for the user:
     a. Create a Supabase project at supabase.com.
     b. Open the SQL editor and run packages/config-schema/supabase/schema.sql once (one file = the whole schema).
     c. Provide env values: the Supabase project URL + anon key under the framework's client prefix, and SUPABASE_SERVICE_ROLE_KEY (server-only) if step 6 was done. Add an AI provider key only if wrapping an LLM.
  8. Verify: start the app's dev server. The welcome experience should appear after ~1 second, and a row should appear in firstflow_flow_runs in Supabase.

  DO NOT:
  - run "pnpm add @firstflow/..." (the packages are not on npm use workspace:*).
  - add apiUrl, agentId, publishableKey, or conversationId to FirstflowProvider.
  - put SUPABASE_SERVICE_ROLE_KEY in client code or any NEXT_PUBLIC_/VITE_ variable.
  - expect FirstFlow to read an API key the LLM client you construct holds it.
  ```
</Accordion>

<Tip>
  For ongoing work, drop a line in your `CLAUDE.md` / `AGENTS.md` / `.cursorrules`
  pointing at this page so the agent re-reads the current rules before editing
  FirstFlow code.
</Tip>

## What the agent produces

When it finishes (and you've done the Supabase steps), you'll have: the packages linked via `workspace:*`, a `firstflow/experiences.json`, a mounted provider + widget, optional LLM wrapping in a server route, and a welcome experience that fires on load and records a `firstflow_flow_runs` row.

From there, author more experiences against [`SCHEMA.md`](https://github.com/firstflowdev/firstflow-oss/blob/main/packages/config-schema/SCHEMA.md), and explore the [Browser SDK](/react/overview) and [Server SDK](/server/overview) references.