Work with AI agents

A coding agent edits an API description the way it edits code: quickly, and without the context a reviewer has. The checks that protect a repository from a hurried person protect it from an agent too, provided the agent can run them and read their answers. This guide puts apigenie lint, apigenie format and apigenie diff in an agent’s loop, tells the agent about them, and keeps the same checks in CI for the pull request the agent opens.

You need the CLI installed where the agent runs; the Quickstart shows how. The commands below work with OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files.

What an agent needs from a tool

  • An exit status that means one thing. The binaries share one table: 0 is success, 1 is findings (lint errors, breaking changes, files to reformat), 2 is a usage or input error. The 1.0 compatibility promise freezes it for apigenie, apigenie-generator and apigenie-server; apigenie-catalog and apigenie-mcp are experimental.
  • Output it can parse. Since 0.12.0 every command takes --json and then prints one JSON document: its report (lint, diff, format, test, apigenie-catalog list, …) or the status of the run, with the exit status and the messages (JSON output). Each has a formatVersion and a published schema.
  • Settings in a file it can check. apigenie.yaml is validated against its JSON Schema before any command reads it, so a wrong key is an error with a line, not a silently ignored setting.
  • Documentation it can read. Guides, reference pages and linter rules have Markdown copies, indexed in llms.txt and collected in llms-full.txt. So do the sites of your own APIs: the build of apigenie-generator docs writes a Markdown copy of each page with its own llms.txt, which an agent that calls your API can read.

Tell the agent about the commands

Most agents read an instructions file at the root of the repository: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules or the equivalent of your tool. apigenie init adds this section to it (AGENTS.md unless you name another with --agents-file) and writes apigenie.yaml with the rules of the descriptions it finds. Or add the section by hand. Either way, say in its first sentence where your descriptions are:

## API descriptions

This repository keeps its API descriptions (OpenAPI, Swagger 2.0, AsyncAPI, GraphQL, Protobuf)
under version control and checks them with the API Genie CLI (`apigenie`; install it with
`npm install -g @mykulyak/api-genie`). The project's rules are in `apigenie.yaml`. After changing a
description:

1. `apigenie lint --fix --json <file>`, then fix what is left by hand and lint again. The JSON
   lists every issue with its line, rule and message; the command exits with 1 while errors
   remain. Fix the issues your change introduced, not the ones that were there before.
2. `apigenie format <file>`.
3. Compare with the base branch: `git show origin/main:<file> > /tmp/base` and
   `apigenie diff --json /tmp/base <file>`. Exit status 1 means a breaking change: say so in the
   pull request and propose a compatible alternative. Do not remove the change, or weaken
   `apigenie.yaml` (turn a rule off, lower a severity), to make a check pass without asking.

Every command takes `--json` and then prints one JSON document: its report, or
`{"exitStatus", "messages", "output"}`. Exit statuses: 0 success, 1 findings, 2 a usage or input
error. `apigenie <command> --help` lists the options; generate code with
`apigenie-generator <client|server|docs> <target> --help`, mock with `apigenie-server <file>`.

The sentence about weakening the checks matters: an agent told only to make a check pass will make it pass.

The loop

Each step prints something the agent can act on, and exits with a status it can test.

apigenie lint apis/orders.yaml --fix --json > lint.json; echo $?
1

With --json, each remaining issue has its file, line, column, severity, rule and message, and each rule links its page under the linter rules, which says why the rule exists and what a fix looks like. --fix has already applied the safe fixes and kept the comments of the file.

apigenie format apis/orders.yaml

The formatter gives the same file for the same input, whoever ran it, so a formatted file is a small diff: only the lines the agent meant to change. The first formatting pass can change many lines; commit it on its own, before the API changes, so reviewers can tell the two apart.

git show main:apis/orders.yaml > /tmp/orders.main.yaml
apigenie diff /tmp/orders.main.yaml apis/orders.yaml --report status --json
{ "formatVersion": 1, "status": "non-breaking" }

--report status is the one-word answer; --report changelog lists every change with its rating, and --report detailed every property that changed, for the pull request’s description.

Keep the same checks in CI

The agent’s checks are advisory until CI runs them on the pull request. The GitHub Action lints the changed files and compares each with the base of the pull request, and shows the issues on the changed lines, where the reviewer and the agent both see them. Catch breaking changes in CI sets it up.

Serve the checks to the agent over MCP

Agents that reach tools through the Model Context Protocol can call the checks directly. These are desktop and IDE clients, or an agent whose every shell command needs an approval. apigenie-mcp (since 0.12.0), installed with the CLI, serves lint, check_breaking_changes, changelog, format, bundle and describe. lint and check_breaking_changes run apigenie with the repository’s apigenie.yaml. Their result starts with a sentence that says whether the check passed.

In Claude Code, add it with:

claude mcp add api-genie -- apigenie-mcp

Other clients take the command apigenie-mcp in their own MCP settings (Usage). apigenie-mcp writes nothing unless started with --allow-write (claude mcp add api-genie -- apigenie-mcp --allow-write), which lets lint fix, format rewrite and bundle write files. Without it, format returns the formatted text for the agent to apply. It is experimental.

Check the code the agent generates

When an agent writes the server too, put apigenie-server in front of it as a validating proxy: every response is checked against the contract, and the run fails on a violation:

apigenie-server apis/orders.yaml --proxy-to http://localhost:8080 --port 4010 \
  --report contract.json --fail-on errors &
API_URL=http://localhost:4010 npm test
curl -X POST http://localhost:4010/__apigenie/shutdown
wait $!

Mock and contract-test an API explains the report and the coverage gate.

Give an agent the API as tools

apigenie-generator server mcp writes an MCP server with a tool per operation of an OpenAPI document, so an agent can call the API through the Model Context Protocol instead of writing HTTP by hand. It is experimental: MCP and its SDK are still moving, and the tool names and result shapes can change with them.

apigenie-generator server mcp apis/orders.yaml -o orders-mcp

Next steps

Was this helpful?