CI and Coding Agents

Checking for drift in CI: --check

If you commit the generated openapi/ directory, run the generator with --check in CI so a spec change can't be merged without regenerating:

openapi-rq -i ./openapi.yaml -o ./src/openapi --check

Use exactly the same options as your normal codegen script. Different options produce different output, and --check reports that as drift. A simple way is to reuse the script:

{
  "scripts": {
    "codegen": "openapi-rq -i ./openapi.yaml -o ./src/openapi --format biome",
    "codegen:check": "npm run codegen -- --check"
  }
}

--check:

• generates into a temporary directory inside <output>/queries (.openapi-rq-check-*) and deletes it afterwards. --format and --lint run on that copy with the same configuration files, and overrides or ignore rules that target the output directory by path (src/openapi/**, a folder named openapi) apply to it as well
• compares only the directories the generator owns: <output>/requests and <output>/queries
• never changes an existing file in the output directory
• exits with 0 when everything matches, and with 1 when files differ

A formatter or linter rule that names an exact file or depth from the project root, such as src/openapi/queries/*.ts, does not reach the temporary copy and makes --check report drift. Write it as src/openapi/queries/** instead.

Every file in queries/ starts with a header that includes the package version. After upgrading @7nohe/openapi-react-query-codegen, --check fails until you regenerate, so regenerate in the same change as the upgrade.

error [OUTPUT_OUT_OF_DATE]: Generated output is out of date (2 files differ). Re-run openapi-rq without --check to update it.
  modified src/openapi/queries/queries.ts
  added    src/openapi/requests/sdk.gen.ts

Status	Meaning
added	Generation produces this file, but it is missing from the output
modified	The file content differs
removed	The file exists in the output but is no longer generated

A GitHub Actions step looks like this:

- run: npm ci
- run: npm run codegen:check

Machine-readable errors: --json

With --json, a failure prints exactly one line of JSON to stderr, and stderr contains nothing else.

{"code":"INPUT_NOT_FOUND","message":"OpenAPI input could not be read: ./openapi.yaml","details":{"input":"./openapi.yaml","reason":"OpenAPI specification not found: ./openapi.yaml"}}

The shape is always { code, message, details }. code is stable and meant for branching; message is for humans and may change. details is an object whose fields depend on the code:

code	When	details
INVALID_ARGUMENT	Unknown option, invalid choice, missing -i	commanderCode
INPUT_NOT_FOUND	The input file does not exist or the URL request failed	input, reason
INPUT_PARSE_ERROR	The input is not valid YAML or JSON	input, reason
CLIENT_GENERATION_FAILED	The client could not be generated for another reason (an OpenAPI 2.0 document, an unresolvable $ref)	input, reason, name
GENERATION_FAILED	Generating the React Query hooks failed	name
OUTPUT_OUT_OF_DATE	--check found differences	files: [{ path, status }]

--json combines with --check. Drift is then reported as OUTPUT_OUT_OF_DATE with the list of files.

Exit codes

Exit code	Meaning
0	Success, or --check found no differences
1	--check found differences
2	Error

Exit codes are the same with and without --json.

Programmatic API

Both features are also available from Node.js:

import { check, CodegenError, generate } from "@7nohe/openapi-react-query-codegen";

const result = await check(
  {
    input: "./openapi.yaml",
    output: "./src/openapi",
    pageParam: "page",
    nextPageParam: "nextPage",
    initialPageParam: 1,
  },
  // Written into the header of every generated queries file. To match output
  // generated by the CLI, pass the installed package version.
  "4.0.0-beta.6",
);
if (!result.upToDate) {
  console.log(result.files); // [{ path, status }]
}

The second argument is the version string written into the header of every file in queries/. check() only reports a match for output generated with the same string, so pass the version of the installed package when the output was generated by the CLI.

Failures are thrown as CodegenError, which has the same code and details as the JSON output.

Coding agents: a guide in your AGENTS.md

The generated files can be very large: for the GitHub REST API, queries.ts alone is 1.5 MB. An agent does not need to read them. Add --agentsMd to your codegen script and the generator keeps a block in your project's AGENTS.md that tells it how the names are built and how to look one operation up with grep:

openapi-rq -i ./openapi.yaml -o ./src/openapi --agentsMd

• The block sits between <!-- openapi-rq:begin src/openapi --> and <!-- openapi-rq:end src/openapi -->. The rest of the file is yours; the block is replaced in place on every run.
• --agentsMd CLAUDE.md writes to another file. Claude Code reads AGENTS.md only in a project without a CLAUDE.md, so when you have both, either name CLAUDE.md here or add a line @AGENTS.md to it. The generator says so when it sees that case.
• --check reports a missing or outdated block as a file that differs.

The block goes into the instructions file at the root because that is what an agent has in its context from the start. In our runs (Claude Code, five tasks on the GitHub REST API client, ten runs per model, November 2026) the block cut the tokens the agent was sent by 25% with Sonnet 5.5 and by 35% with Haiku 5.5 (medians), and the turns it took from 8.5 to 6 and from 10 to 8.5. Every run produced code that type-checks, with the block or without. The same guide placed inside the output directory made no difference: an agent that searches with grep never loads it. The runs and the scripts are in benchmarks/agent.

Coding agents: AGENTS.md and llms.txt

• The npm package ships an AGENTS.md. After installing, it is at node_modules/@7nohe/openapi-react-query-codegen/AGENTS.md. It covers installation, every CLI flag, the generated file layout, naming conventions for the generated hooks, and the error codes above. You can point your project's own AGENTS.md or CLAUDE.md at it.
• This site serves an llms.txt with a short project summary and links to these docs.