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

# Use Claimr docs with AI coding agents

> Give Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and other AI coding agents the rules and references they need to integrate Claimr into your app correctly.

AI coding agents can integrate Claimr for you, as long as they know how the widget loader behaves. Without that context, agents tend to make the same mistakes: injecting the script from the component that shows the widget, using the wrong script ID, or calling `destroy()` on unmount. This page gives you three ways to prevent that.

1. [Add a rules file](#add-a-claimr-rules-file-to-your-project) to your repository so the agent follows the integration rules on every task.
2. [Point the agent at the Markdown docs](#point-the-agent-at-the-docs) so it can read the full guides.
3. [Connect Claimr MCP](#configure-campaigns-with-claimr-mcp) if you also want the agent to create or edit campaigns.

## Add a Claimr rules file to your project

Copy the block below into the instructions file your agent reads, fill in the **Project values** section, and commit it.

| Agent | File |
| - | - |
| Claude Code | `CLAUDE.md` in the project root. If you already keep rules in `AGENTS.md`, add the line `@AGENTS.md` to `CLAUDE.md` instead. |
| OpenAI Codex | `AGENTS.md` in the project root. |
| Cursor | `AGENTS.md`, or a rule file such as `.cursor/rules/claimr.mdc`. |
| GitHub Copilot | `.github/copilot-instructions.md`, or `AGENTS.md`. |
| Other agents | `AGENTS.md` is read by most coding agents. |

```markdown AGENTS.md expandable theme={"dark"}
## Claimr widget integration

Claimr is embedded with one script, `https://widgets.claimr.io/claimr.min.js`. The script renders the
campaign in an iframe inside a container element and exposes an SDK at `window.claimr`.
There is no npm package.

### Project values

- Organization ID: <your-organization-id>
- Campaign ID: <your-campaign-id>
- Container ID: claimr-widget
- Sign-in model: <widget sign-in | user token | wallet (platform "dapp") | telegram>
- Framework: <React + Vite | Next.js App Router | Next.js Pages Router | Vue 3 + Vite | Nuxt>

### Reference docs (Markdown, read before writing code)

- Rules and shared loader module: https://docs.claimr.io/frameworks/overview.md
- React: https://docs.claimr.io/frameworks/react.md
- Next.js: https://docs.claimr.io/frameworks/nextjs.md
- Vue and Nuxt: https://docs.claimr.io/frameworks/vue-and-nuxt.md
- SDK methods and callbacks: https://docs.claimr.io/sdk-guide.md
- Script attributes: https://docs.claimr.io/widget/widget-attributes.md
- User tokens: https://docs.claimr.io/api-guide/user-token.md
- Full index: https://docs.claimr.io/llms.txt

### Rules

1. Use the shared loader module (`lib/claimr.ts`) from the overview page. Do not write a new loader.
2. Load the script exactly once per page session, from the app root: root provider (React), root layout
   (Next.js App Router), `_app` (Pages Router), app plugin (Vue), or `plugins/*.client.ts` (Nuxt).
   Never load it from the component that displays the widget.
3. The script element must have `id="claimr-script"`. There must be only one on the page.
4. Configure the widget with `data-*` attributes on the script: `data-organization`, `data-campaign`,
   `data-container`, `data-autoresize="true"`. They are read once at load. For runtime changes use SDK
   methods (`set_language`, `set_theme`, `set_user_token`), or `reloadClaimr(config)` to switch campaigns.
5. Show the widget by rendering an empty element whose `id` equals `data-container`. The loader attaches
   the iframe when that element appears and removes it when it disappears. Never render children inside
   it and never bind an inline `height` to it.
6. Never call `window.claimr.destroy()` when a component unmounts.
7. Read `window.claimr` at call time. Never store it in state, context, or a module variable.
8. Assign SDK callbacks (`on_user_info`, `on_campaign_info`, `on_logout`, `on_wallet_request`, and so on)
   in exactly one place, the `setup` function passed to `loadClaimr`, and share the data through app state.
9. `set_language`, `set_theme`, `complete_task`, `select_wallet`, `open_profile_popup` and `platform_login`
   need a loaded widget: wrap them in `withWidget(...)`. `set_user_token`, `connect_wallet`, `open_quest`
   and `login` are safe to call earlier.
10. Run Claimr code in the browser only. Next.js: `'use client'` and `useEffect`. Nuxt: `.client` plugin
    and `onNuxtReady`. Rendering the empty container on the server is fine.
11. The Claimr API token is a server secret. Never expose it with `VITE_`, `NEXT_PUBLIC_`, or
    `NUXT_PUBLIC_`. Generate user tokens on the server:
    `GET https://prod.claimr.io/api/v1/token?account=<user id>&platform=<platform name, not "claimr">`
    with `Authorization: Bearer <API token>`. The response is `{ "success": true, "data": { "token": "..." } }`.
    Pass the token to the browser, then to `set_user_token`. Call `window.claimr.logout()` on sign-out.
12. When the widget component unmounts, reset `document.body.style.overflow = ''`.
13. To disable autoresize, omit `data-autoresize`. The value `"false"` still enables it.
14. Only use SDK methods, callbacks, and attributes listed in the SDK guide and widget attributes pages.
    If something is not documented, ask instead of guessing.

### Definition of done

- The widget renders on the target page and `window.claimr.is_claimr_ready` is `true`.
- Navigating away and back re-attaches the widget, and `document.querySelectorAll('#claimr-script').length === 1`.
- No server-side rendering errors and no hydration warnings.
- The API token does not appear anywhere in the client bundle.
```

## Point the agent at the docs

Every page on this site is also available as plain Markdown, which agents read more reliably than HTML:

| Resource | URL |
| - | - |
| Index of all pages | `https://docs.claimr.io/llms.txt` |
| All pages in one file | `https://docs.claimr.io/llms-full.txt` |
| Any single page | Add `.md` to the page URL, for example `https://docs.claimr.io/frameworks/react.md` |

Agents with web access, such as Claude Code, can fetch these URLs on their own when the rules file lists them. If your agent runs without network access, open the page you need here, use the page menu at the top to copy it as Markdown, and paste it into the conversation.

## Example prompts

Use prompts like these after adding the rules file. Name the framework, the page, and the sign-in model so the agent does not have to guess.

<AccordionGroup>
  <Accordion title="Add the widget to a page">
    ```text theme={"dark"}
    Add the Claimr widget to the /quests page of this Next.js App Router app.
    Follow the Claimr rules in AGENTS.md and https://docs.claimr.io/frameworks/nextjs.md.
    Use NEXT_PUBLIC_CLAIMR_ORGANIZATION and NEXT_PUBLIC_CLAIMR_CAMPAIGN for the IDs.
    Users sign in inside the widget, so skip user tokens.
    When you are done, list the files you changed and how to verify the integration.
    ```
  </Accordion>

  <Accordion title="Sign users in with your own accounts">
    ```text theme={"dark"}
    Our users already sign in with our own auth. Connect them to Claimr with user tokens:
    add a server route that generates the token with CLAIMR_API_TOKEN, pass it to the
    Claimr provider, and call logout on sign-out. Follow the "Sign users in with your own
    accounts" section of https://docs.claimr.io/frameworks/react.md.
    Never expose CLAIMR_API_TOKEN to the browser.
    ```
  </Accordion>

  <Accordion title="Complete a task from the app">
    ```text theme={"dark"}
    When a user finishes the onboarding checklist in src/features/onboarding, mark the
    Claimr front-end task "<task id>" as complete using completeTask from useClaimr.
    The widget may not be mounted at that moment, so rely on withWidget.
    ```
  </Accordion>

  <Accordion title="Reuse the dApp wallet">
    ```text theme={"dark"}
    This dApp uses wagmi and RainbowKit. Make the Claimr widget use the connected wallet
    instead of asking the user to connect again: set platform "dapp" and implement
    on_wallet_request as in https://docs.claimr.io/frameworks/react.md#connect-the-users-wallet-dapps.
    ```
  </Accordion>

  <Accordion title="Review an existing integration">
    ```text theme={"dark"}
    Review our Claimr integration against the rules in AGENTS.md. For each rule, say whether
    the code follows it and point to the file and line. Fix any violation you find.
    ```
  </Accordion>
</AccordionGroup>

## Configure campaigns with Claimr MCP

The rules file teaches an agent how to **embed** a campaign in your code. To let the same agent **build or edit** the campaign itself (quests, tasks, rewards, widget layout, translations), connect it to Claimr MCP.

```bash theme={"dark"}
claude mcp add --transport http claimr https://prod.claimr.io/mcp
```

For Cursor, VS Code, and other clients, see [Connect an AI assistant](/mcp/connect-an-ai-assistant). With both in place, a single request such as "create a three-quest onboarding campaign and add it to the /quests page" can cover the campaign setup and the code.