surrealdb/ai-claude-plugin/surql-formatter

SurQL Formatter

Primary instruction: after editing or writing any .surql file, run `@surrealdb/surql-fmt` on it:

npx -y --package=@surrealdb/surql-fmt surqlfmt --write path/to/file.surql

First run downloads the npm package and may take a few seconds. Formatter errors are non-fatal — if the formatter fails, leave the file as the user edited it and continue.

Host behavior

• Claude Code / Cowork: a PostToolUse hook in `plugins/surrealdb/settings.json` already runs surqlfmt --write on every .surql file after Edit, Write, or MultiEdit. The model does not need to invoke the formatter — it happens automatically.
• Claude Desktop: no hook system. The model must invoke surqlfmt via Bash after each .surql edit, per the primary instruction above.

When unsure which host you are running in, just run the formatter — re-running it on already-formatted output is a no-op.

Manual usage

Format a file in place:

npx -y --package=@surrealdb/surql-fmt surqlfmt --write path/to/file.surql

Check formatting without writing (CI use — exits 1 on diff):

npx -y --package=@surrealdb/surql-fmt surqlfmt --check path/to/file.surql

Format from stdin:

echo 'SELECT * FROM user;' | npx -y --package=@surrealdb/surql-fmt surqlfmt --stdin

Common flags: --indent <n>, --indent-char space|tab, --max-line-length <n>.

Limitations

• .surql files only. SurQL strings embedded in JS/TS/Python/Rust sources are not touched — there is no language-server or tagged-template walker. To format an embedded query, copy it into a .surql scratch file, format it, and paste back.
• Parse errors leave the file unchanged. If a file stops formatting, run surqlfmt --check manually to see the error.

Disabling

• Claude Code / Cowork: remove the PostToolUse block from `plugins/surrealdb/settings.json`, or delete the file.
• Claude Desktop: remove this skill, or instruct the model not to run the formatter.

Manual surqlfmt invocations continue to work either way.