Vacuum for coding agents

When a coding agent edits an API specification, the agent needs to check that the file follows the repository’s rules before returning the change. Vacuum is a command-line tool that checks API descriptions against rules and reports issues without changing the files. Its lint command handles OpenAPI and AsyncAPI files, and a separate schema command lints JSON Schema documents. For AsyncAPI, the lint documentation says Vacuum supports version 3 and rejects 2.x documents.

After editing a specification, an agent can run Vacuum on the local file and use its findings to decide what to fix. Vacuum supports rules that work with Spectral, a tool commonly used to check API descriptions. The commands below show how to check a local OpenAPI file and produce a JSON report. Vacuum does not require an account to check a local file.

Install Vacuum

Vacuum’s installation page documents several options. On macOS, the recommended way is the Homebrew cask, which installs the signed release:

brew install --cask daveshanley/vacuum/vacuum

On Linux, the page offers a shell installer, and npm works on both systems:

curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
# or
npm install -g @quobix/vacuum

Then check that the shell can find the executable:

vacuum version

Installation requires network access to fetch the tool. Linting a local specification runs on the machine, and Vacuum does not require an API key for this use. It can still make network requests. By default, it looks up $ref references in the specification, including remote ones over HTTP. The --remote=false flag turns those lookups off, also for references to other local files. When the output goes to a terminal, Vacuum also checks GitHub for a newer release, which --no-update-check turns off.

Lint a local specification

For a small test, create an OpenAPI file in the repository. The following example describes a single health-check endpoint:

cat > openapi.yaml <<'EOF'
openapi: 3.0.3
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        '200':
          description: Service is healthy
EOF

Run Vacuum against the file:

vacuum lint ./openapi.yaml

The lint command reads the specification and prints a summary of the issues it finds. For OpenAPI files it uses the recommended rule set unless you pass your own with --ruleset. Add -d to see the full details of each finding. The findings depend on the specification and the rules Vacuum applies; this example does not assume that the file passes or fails.

The lint command has no JSON output flag. To make the results easier for an agent or another program to parse, use the spectral-report command, which writes a JSON report in the same format as Spectral:

vacuum spectral-report ./openapi.yaml vacuum-report.json

The spectral-report documentation explains the command. The second argument is the output file. Without it, Vacuum writes vacuum-spectral-report.json. The -o flag sends the JSON to standard output instead, so an agent can read it directly:

vacuum spectral-report -o ./openapi.yaml

Vacuum reads the specification and does not change it. The exception is the lint --fix flag, which applies automatic fixes and overwrites the original file unless you name another file with --fix-file. Leave that flag out of an agent task that should only report.

Use findings to guide a code change

After editing an API specification, a coding agent can run Vacuum and review the report before making more changes. If a finding points to a missing description, the agent can find the named field, update the specification, and run the same command again. The agent should follow the API behavior the project intends, rather than adding text or changing a response only to silence a rule.

A practical prompt is:

Review the changes to openapi.yaml. Run vacuum spectral-report -o ./openapi.yaml, explain each finding, and make only specification changes supported by the existing API implementation. Run the command again and report the remaining findings. Do not change application code.

Vacuum checks the specification against lint rules, but it does not check whether the running service behaves as the specification says. When a finding concerns a response, the agent should compare the proposed fix with the relevant handler code, which handles the request, or with tests. Use the report to guide review; it does not prove that the API works.

When Vacuum fits

Use Vacuum when an agent edits an API description and the repository expects someone to check the lint findings before review. The command runs locally and reads the specification without changing it. A shell-enabled agent can run the check repeatedly without changing the service. For a pass or fail answer, vacuum lint --fail-severity warn returns exit code 1 when it finds errors or warnings. The exit code page says exit code 2 means a tool error, for example a file that could not be parsed.

Vacuum’s results depend on the rules it uses. If a repository has a custom set of rules, the agent needs to run Vacuum with those rules, using --ruleset, to check the project’s conventions. The official command documentation describes the available options. A default lint run alone does not show that a change meets every requirement specific to the organization.