How Sannr works.

01Three things, one folder

Sannr is three things that share one committed folder.

A map

Point it at a repository and it inventories the APIs it finds: the services, the routes it recognizes, who calls whom, and where a contract and the running server disagree. The map is generated from your files, offline, without calling anything.

sannr map . walks the tree and writes the map as one self-contained HTML file that works offline. sannr start produces the same static inventory during setup. Neither makes an API request; the setup guide's --no-execute form is the explicit way to say so.

A knowledge file

.sannr/stacks/sannr.json records what agents observe about each operation: response shapes, the enum values a contract declares, the gotchas the documentation omits, and the decisions no traffic ever reveals, such as why an integration was rejected. It is committed with the code, so whoever clones the repository inherits it.

sannr learn fills it from read-only requests. sannr note adds an authored lesson to one operation. sannr view writes an offline HTML snapshot of everything the file holds, with verification dates, confidence and each note's provenance, so a person can read it without a server.

A client

A request client your agent calls through MCP or the command line. It sends the request, applies your credentials from environment references, returns a bounded result with the assertions you asked for, and records what it observed. The client is the sensor; the folder is the product.

In Claude Code or Codex the client is the api_request tool that sannr start registers for the project. From a terminal, sannr request GET /health uses the same client and returns the same envelope: status, whether the call was ok, the assertions and their results, the bounded data, and a pointer to the local evidence.

02Import. Verify. Deliver. Keep it true.

Import what you already have

Sannr reads Postman, Insomnia and Bruno collections and Kong configuration, and seeds operations from an OpenAPI contract. Every import comes with a loss report that names what it could not carry over. A test script it cannot translate faithfully is quarantined and reported, never silently dropped or silently faked.

sannr import accepts Postman v2.1 and v3, Insomnia v4 and v5, Bruno files and directories, and Kong configuration. It writes a request suite for the steps whose assertions it could translate or infer, and an adjacent to-do file naming every gap. Scripts are never executed during an import. An OpenAPI contract is not imported; sannr start seeds the knowledge file from it as unverified operations when the environment names one.

Verify against the running service

Read-only checks record what is actually true about each operation: the status codes seen, the field names and types, the drift between the contract and the server. Field values are never recorded unless the contract itself declares them; request and response bodies, headers and credentials never are.

sannr learn sends only GET and HEAD requests. sannr learn --dry-run previews exactly what would be written and writes nothing. Whatever it learns about a production environment is reported, not promoted into the committed file.

Deliver it where the agent already reads

The verified facts and the authored lessons are projected into the instruction files your agent loads at the start of a session, so it starts from what the team knows without being told to go and look.

sannr start writes a short block into AGENTS.md and CLAUDE.md that names the knowledge file, lists the recorded gotchas, and installs the sannr-request, sannr-write and sannr-feedback skills for the host. Rerunning it preserves unrelated configuration and reports conflicts instead of overwriting them.

Keep it true

A CI workflow runs Sannr's audit on every push and on a weekly schedule and reports, in the job summary, where your code, your contract and the saved knowledge disagree. It makes no API requests, and it never rewrites your contract or your notes.

sannr connect --ci adds a GitHub Actions workflow that runs on pushes, pull requests and a weekly schedule. It reports where the checked-in contract and the code disagree, in report-only mode and without API traffic, and it does not rewrite the contract or the knowledge file. sannr verify --ci runs the saved suites as read-only probes and exits non-zero on drift.

03A recorded lesson

Automatic capture keeps bounded status and structure. It cannot know why a behavior matters. When an agent or a developer learns one reusable fact the contract does not state, the write convention asks for one present-tense sentence on the operation, recorded at once:

./node_modules/.bin/sannr note "POST /orders/{id}/confirm" "returns 200 while status remains draft unless payment_status is settled"

The note lands in the knowledge file under that operation, with who recorded it and when. Every note passes a secret guard: a token, a key or an email address is refused, because the file is committed forever.

"POST /orders/{id}/confirm": {
  "notes": [
    "returns 200 while status remains draft unless payment_status is settled"
  ],
  "notes_provenance": [{ "by": "agent", "at": "2026-09-15" }]
}

The next session that touches that operation, on any clone, is told this before it sends the request. A decision not to use an API is recorded the same way with sannr verdict, with its reason and scope, so the rejection leaves an artifact instead of a memory.

04What stays on your machine

Sannr has no account to create and sends nothing to us. Credentials are referenced by environment variable name; the configuration stores the name, never the value. Recorded knowledge holds field names and types, and only the values a contract declares. Request evidence stays in a local folder that Sannr's own .gitignore keeps out of the repository. The knowledge file is the only thing meant to be shared, and it is designed to be safe to commit.

The environment configuration names a base URL, a contract path and an authentication reference such as bearer:LOCAL_API_TOKEN. The token itself lives in an environment variable or a local file outside the repository. The alpha's feedback report is written to a local file for a person to read and send; the product never sends it.

05The .sannr folder

Setup writes a README.md into the folder that explains each path. This is its layout at the alpha:

Commit the knowledge, the configuration, the generated guide and the skill sources. The evidence directory is excluded by the folder's own .gitignore.

06The words we use

API context

Everything an agent needs to use an API correctly that the specification does not say: prerequisites, quirks, rate limits, the reason a decision was made, and how recently each fact was checked.

Tribal knowledge

The working knowledge of a system that lives in the heads of the people who have been around longest and is not written anywhere a newcomer, or an agent, would find it.

The rediscovery tax

The cost of an agent re-deriving, in a fresh session, something a previous session already learned about the same API.

Authored lesson

A short note recorded on an operation by a developer or an agent, with its evidence, describing behavior the contract does not say. Sannr delivers lessons to later sessions.

Loss report

The part of an import that names what could not be carried over faithfully, so a green import never means more than it should.

Drift

A difference between what the contract or the saved knowledge says and what the running service does now.

Repository-level context

Knowledge committed with the code, so every clone, every host and every person who touches the repository inherits it. Your agent's host may keep memory for you on your machine; the repository is what everyone else pulls.

Ready to try it with an alpha ZIP? Set up Sannr. Want one? Request an invite on the home page.