AI Friendliness

IC Reactor publishes guides written for AI coding assistants (Claude, ChatGPT, Copilot, Cursor, Codex and others). They list the APIs to reach for, the setup that fits each kind of app, and the mistakes agents tend to make, such as calling an update method through a query hook or doing token math with Number. This page shows where they are and how to make your agent read them.

Where the Guides Are

Guide	What it holds
node_modules/@ic-reactor/<package>/llms.txt	Each package’s own guide, installed with it: setup snippet, when to use what, and a list of what not to do, for the version you installed
/llms.txt	An index of these docs in the llms.txt format, with a link and a one-line note per page
/llms-full.txt	The complete guide in one file: install, setup choices, every core pattern with snippets, SSR, auth, errors, codegen, testing
A page’s Markdown	Every docs page is also served as Markdown: use Copy Markdown or Open in Claude at the top of the page, or the .md URL that /llms.txt lists for it
CHANGELOG.md	What changed in each package, with a migration hint for each behaviour change

Prefer the copy in node_modules: it ships with the package, so it describes the version your app has installed, and it opens with that version (Applies to `@ic-reactor/react` …). A package whose llms.txt is missing or has no such line predates these guides; use the copies on this site for it. The copies on this site are published from the main branch, so they can describe changes that no release carries yet; the changelog’s Unreleased section lists those.

Tell Your Agent About Them

Paste this into your app’s AGENTS.md, CLAUDE.md, .github/copilot-instructions.md or Cursor rules:

## IC Reactor

This app calls Internet Computer canisters with IC Reactor (`@ic-reactor/*`).

- Before writing or reviewing IC Reactor code, read
  `node_modules/@ic-reactor/react/llms.txt`, and the `llms.txt` of any other
  `@ic-reactor/*` package in `package.json`. They match the installed version.
- For what they do not cover, read https://ic-reactor.b3pay.net/llms-full.txt.
- Call update methods only through mutations, pass `skipToken` for query args
  that are not known yet, and invalidate with query objects, never
  hand-written query keys.
- Do not edit `index.generated.ts` or `index.factories.generated.ts`; change
  the `.did` file and run the generator again.

Keep the list of rules short: the package guides hold the rest, and they change with the version you install.

Tip

When you ask a chat assistant without file access, give it the Markdown URL of the page, such as https://ic-reactor.b3pay.net/v3/framework/mutations.md, or paste llms-full.txt. The .md path keeps the source file’s capitals (/v3/reference/ClientManager.md), so copy it from /llms.txt rather than guessing it from the page’s URL.

Give It Your Canister’s Types

An assistant infers method names, argument types and result types from the service type your declarations export (_SERVICE); the idlFactory only drives encoding at run time. When you ask for code against a specific canister, include the generated declarations (for example backend.did.d.ts) or the .did file, and keep the type argument on the reactor.

Display Types

A DisplayReactor takes and returns plain JavaScript values: strings for nat, int and Principal, hex strings for blobs, undefined for an empty opt. Generated code then reads like ordinary TypeScript, which is also what most models were trained on. defineDisplayReactor builds one together with its hooks:

import { defineDisplayReactor } from "@ic-reactor/react"
import { canisterId, idlFactory, type _SERVICE } from "./declarations/backend"

export const { reactor, useActorQuery, useActorMutation } =
  defineDisplayReactor<_SERVICE>({ name: "backend", idlFactory, canisterId })

Keep the <_SERVICE> type argument. Without it the reactor knows nothing about the Candid, and every display-side argument and result is typed unknown; see Types: with and without a service type. Use defineReactor instead when the code needs raw bigint and Principal values.

Agent Skills

The ic-reactor skill packs this guidance as an Agent Skill: which setup fits the app, the rules for queries, mutations, invalidation, server rendering, sign-in, errors, token amounts and tests, the mistakes to avoid, and type-checked examples the agent loads only when a task needs them. It starts by sending the agent to the llms.txt of the packages you installed, so it follows your version. Agents load it on their own when a task matches, or when you ask for it by name.

In Claude Code, add the IC Reactor repository as a plugin marketplace and install the plugin:

/plugin marketplace add B3Pay/ic-reactor
/plugin install ic-reactor@ic-reactor

The plugin’s version follows @ic-reactor/react, and an installed copy changes only when that version does. Turn on auto-update for the marketplace in /plugin (Marketplaces tab), or run claude plugin update ic-reactor@ic-reactor after upgrading the packages.

For Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode and other agents that read skill folders, install it from your app’s root with the skills CLI:

npx skills add B3Pay/ic-reactor --skill ic-reactor

It copies the skill into each agent’s skills folder, such as .agents/skills/ic-reactor/ or .claude/skills/ic-reactor/, where you can commit it with the app. Both installs take the skill from the repository’s main branch, which can describe changes that no release carries yet. The skill’s first step sends the agent to the llms.txt of your installed packages, and that guide wins where the two differ.

The repository’s other skills, ic-reactor-hooks and ic-reactor-packages, are written for work on IC Reactor itself, not for apps.

Prompting Examples

Setup

“Set up IC Reactor for the canister rrkah-fqaaa-aaaaa-aaaaq-cai whose declarations are in ./declarations/my_canister. Read node_modules/@ic-reactor/react/llms.txt first.”

Data Fetching

“Show a user’s balance from an ICRC-1 ledger with useActorQuery, formatted with formatTokenAmount, and wait with skipToken until the user has signed in.”

Mutations

“Write a component that transfers tokens with useActorMutation, reads the amount with parseTokenAmount, shows the ledger’s Err through onCanisterError, and refreshes the balance with invalidateQueries.”

Contributing to IC Reactor With an Agent

The files above are for apps that use IC Reactor. The repository has its own instructions for agents that work on IC Reactor itself: AGENTS.md (which source files own a task, and what to run for each kind of change), CLAUDE.md, .github/copilot-instructions.md, .cursorrules, and the skills in skill-packages/. See Contributing.