// integration

Coding agents

SurrealGuard is built for coding agents. Point Claude Code, Cursor, or any agent at your project and let it wire everything up — then it gets structured, machine-readable diagnostics on every run, and compile-time errors it can read and fix.

Onboard in one paste

Drop this into your agent to set up SurrealGuard and start checking queries against your schema.

Set up SurrealGuard in this project. Run the CLI with `npx surrealguard init`, point surrealguard.toml at my .surql schema and query directories, then run `npx surrealguard check --json` and fix any reported findings. Where I write queries, use the Rust `query!` macro (surrealguard-rs) or the typed `@surrealguard/client` db.query so they're checked against my schema.

Why it works well for agents

Structured findings. surrealguard check --json emits code, severity, source, byte range, message, help, and related spans — an agent parses findings instead of scraping prose.
Byte-precise spans. Every finding carries an exact byte range, so an agent can make surgical inline edits — even inside a query embedded in a host file.
Compile-time errors. In Rust, a bad query fails cargo check with a message carrying the code and text ([E1002] unknown field …). In TypeScript, a wrong or missing param is a tsc error. Agents already read compiler output — no new channel to learn.
Deterministic exit code. check exits non-zero exactly when an error-severity finding survives policy, so an agent loop knows when it's done.

The check loop

The core loop for an agent is: run check --json, read the diagnostics array, edit at each range, repeat until the array is empty and the exit code is 0.

$ surrealguard check --json
{
  "summary": { "sources_checked": 3, "diagnostics": 1, "errors": 1 },
  "diagnostics": [
    {
      "code": "E1001",
      "severity": "error",
      "source": "queries/report.surql",
      "range": { "start": 14, "end": 19 },
      "message": "unknown table `usr`",
      "help": ["did you mean `user`?"],
      "related": []
    }
  ]
}

See the JSON output shape for every field.

LLM context files

Two Markdown files give an agent the full model without crawling the source. Point your agent's context or docs config at them.

File	Contents
/llms.txt	A short overview: what SurrealGuard is, the agent workflow, the diagnostic families, and links.
/llms-full.txt	The full reference: the contract model, every CLI command, the Rust and TypeScript APIs with signatures, the diagnostic families with example codes, and install commands.

Give the agent a checked surface

The biggest win is writing queries where the compiler checks them, so the agent's own edits are validated as it goes:

Rust — wrap queries in the query! macro. A wrong table or field is a cargo check error the agent reads and fixes; the result type is inferred, so downstream field access is checked too.
TypeScript — pass string literals to db.query (run surrealguard generate for the registry). Wrong or missing params are tsc errors.

In CI, run surrealguard check as a gate: the non-zero exit on any error-severity finding fails the build, so an agent's PR can't merge a query that violates the schema's contracts.