July 26, 2026

openstash - stop feeding your agents the whole OpenAPI spec

A small Go CLI that caches OpenAPI specs locally so you (or your agent) can look up endpoints without re-downloading and re-parsing a huge schema every time.

openstash caches OpenAPI specs locally so you and your agents can look up endpoints without re-downloading and re-parsing a huge OpenAPI spec every time.

It came out of a real annoyance. While building GitBoba against Gitea’s API, I kept reaching for the OpenAPI spec, and these things are big easily 1–2 MB of JSON. Handing that to an AI agent to answer “what’s the shape of GET /user/repos?” is wasteful: it burns context, buries the one operation you care about in noise, and you pay for it on every session. I found using tools like grep and jq to extract the relevant data often gave too much noise and was not reproducible.

So I wrote a tool that does handles the boring parts, and gives you a simple interface to look up endpoints.

How it works

Call openstash add to add a spec to your local cache. It’ll pull the spec from the location you provide and store it locally. It’ll index the spec and make it searchable. You can then pull relevant information at the level different levels of detail by calling openstash search, openstash show, or openstash gather.

openstash add gitea --from https://gitea.example/swagger.v1.json

openstash search gitea "user repos"              # discover - slim results
openstash show   gitea --path /user/repos --method GET   # one operation, full detail
openstash gather gitea "subscription" --expand 3 # search + expanded details
openstash refresh gitea --force # re-fetch the spec
openstash list gitea # list all specs

By default, openstash will use the info.version to label the spec. You can then refer to it by key@version or just key for the latest version. Each refresh will check if the version has changed and re-index the spec if it has.

Openstash also comes with a curl command that allows you to query the spec directly. This is useful for building tools that need to interact with the spec programmatically or your agents need to validate requests against the spec.

# query 
openstash curl gitea --operation issueListIssues \
--token {YOUR_API_TOKEN} \
--param owner={YOUR_USERNAME} \
--param repo={YOUR_REPO} \
--pretty-print

Why it’s nice for agents

  • Less noise - slim search results or one operation, never the entire spec in context
  • Stable references - the same key@version every time, so prompts stay reproducible.
  • Version history - you can diff versions to see what changed.
  • Stays current - refresh re-fetches the source and tells you if info.version changed, without clobbering what you’ve stored
  • Offline support - you can use openstash without an internet connection

Its a simple tool that makes a common, annoying task disappear.

← All posts