Use Claimr docs with AI coding agents

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.

Add a rules file to your repository so the agent follows the integration rules on every task.
Point the agent at the Markdown docs so it can read the full guides.
Connect 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.

AGENTS.md

## 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.

Add the widget to a page

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.

Sign users in with your own accounts

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.

Complete a task from the app

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.

Reuse the dApp wallet

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.

Review an existing integration

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.

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.

claude mcp add --transport http claimr https://prod.claimr.io/mcp

For Cursor, VS Code, and other clients, see 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.

API Guide

Webhooks Guide

SDK Guide

Framework Integration

Guides

Use Claimr docs with AI coding agents

Add a Claimr rules file to your project

Point the agent at the docs

Example prompts

Configure campaigns with Claimr MCP

​Add a Claimr rules file to your project

​Point the agent at the docs

​Example prompts

​Configure campaigns with Claimr MCP

Add a Claimr rules file to your project

Point the agent at the docs

Example prompts

Configure campaigns with Claimr MCP