Sannr

An API client that remembers, for coding agents.

Status: public beta. Published to npm as @sannr/sannr; the source is open under Apache 2.0 at github.com/sannrhq/sannr. CHANGELOG.md says what shipped in each version, CONTRIBUTING.md says how to work on it, and SECURITY.md says how to report a vulnerability.

Tell your coding agent:

Install Sannr in this repository. From the repo root, run npx @sannr/sannr connect and follow what it prints. It adds the Sannr skills, registers its MCP server and adds a short pointer block to AGENTS.md / CLAUDE.md. Then run npx @sannr/sannr doctor and show me the result. doctor announces one GET to https://api.github.com/zen before sending it, so I can see the API client work (use --offline to skip it). API knowledge and request evidence stay on this machine and in this repo. No account, no telemetry. The only thing it sends us is feedback. If it asks for a restart, tell me; when I reopen the agent here I'll say "Finish sannr setup."

Or by hand:

npx @sannr/sannr connect
npx @sannr/sannr doctor

Sannr lets a coding agent read what is already known about an API before a call, make the request with explicit checks, see what actually came back, and record the lesson beside the code for the next session. People can read the same notes and API maps, and open them in a local Workbench.

Keep Postman or Bruno. Import the collection into Sannr as a runnable suite, then read its loss report for anything unsupported before you run it.

It runs locally, through MCP or the command line, with Claude Code, Codex or Cursor. Knowledge you commit travels with the repository; request evidence stays on the machine that recorded it. No account, no telemetry. The only thing it sends us is feedback, which is optional and asks first. You need Node 22 or newer on macOS, Linux or Windows; the Windows notes cover PowerShell and what is verified there. See privacy and limitations.

Five minutes to a first recorded request

The quickstart walks this path end to end with the output to expect. In short, from the root of a git repository:

1. npx @sannr/sannr connect installs the skills, registers the MCP server and writes the pointer block. If your repository has an OpenAPI contract, or calls exactly one public API, it also creates the first stack and says which; otherwise it says nothing is kept until a stack exists. npx @sannr/sannr doctor checks the result and sends one announced GET to https://api.github.com/zen. A 403 can indicate rate limiting; inspect the returned rate-limit metadata. Run npx @sannr/sannr doctor --offline to check setup without that probe. doctor --probe <url> picks another target, and context query --onboarding reads the saved observation back without a request.
2. npx @sannr/sannr stack add github --base-url https://api.github.com names the API this walkthrough uses (connect --base-url <url> does it during install). A stack is one API you talk to; a contract is optional.
3. Restart your coding agent so it loads the MCP server, then say "Finish sannr setup." The pointer block tells the agent how to confirm it.
4. Ask the agent to make a request and write down what it learned, or do it yourself: npx @sannr/sannr request GET /zen --stack github --expect-status 200, then follow the quickstart's note and readback commands after a successful response.
5. npx @sannr/sannr workbench in an interactive terminal opens the local Workbench. Pair the browser with the code the terminal asks for, then read the github stack's note and its trace on the Workbench view, or switch to the Map view to see which code defines which operation.
6. Commit .sannr/. The next session, on any machine, starts with that note.

Setup details, host notes, repair and removal are in install. When something does not match this page, see troubleshooting.

Use the API client directly

Try it before you set anything up. From any directory, with no connect, base URL, credentials or API contract:

npx @sannr/sannr request GET https://api.github.com/zen --expect-status 200

It prints the request, then sends one unauthenticated GET to the public GitHub endpoint doctor uses. The one assertion is status 200; the Zen text varies, so nothing checks it. A passing result includes these fields (other metadata left out):

{
  "status": 200,
  "ok": true,
  "mode": "assert",
  "assertions": { "passed": 1, "failed": 0, "failures": [] },
  "data": null
}

The full result also carries an evidence identifier, duration and returned rate-limit headers. When assertions pass, the result leaves out the response body; the Zen text is kept in local evidence. A transport error, rate limit or unexpected status is a failure to look into, not a demo that passed. This zero-setup path admits only that GitHub GET; other APIs need a stack. It verifies nothing about your repository's API and saves no note.

After setup, the same client is the api_request MCP tool.

Agent workflow

Read the repository's instructions and installed Sannr skills first. A stored note is context; it does not override the user or repository policy.

This is the beginning of the README. Read the rest at the original. Read the full README ↗