Clotr Guard

Clotr Guard

Clotr Guard checks prompts and file reads through hooks for supported AI coding assistants. You can also check a text file yourself or set up the Git pre-commit check. It uses the same on-device engine as Clotr's other apps. A clean prompt passes. Medium and high findings pause that prompt and show their kind. Low findings pass with one short line on stderr. The default lets email addresses, license plates, gamer tags and share links through. Send the same prompt again within two minutes to send it anyway. A new finding pauses it again.

Clotr Guard supports Claude Code, Cursor, Gemini CLI, Codex CLI, Windsurf Cascade and Cline hooks on macOS and Linux. Its checks run on your computer. Clotr Guard makes no network calls or sends text to a Clotr server. A prompt that the assistant is allowed to send still goes to that assistant's AI service as usual. Guard needs Node.js 20 or newer.

Runs locally

Guard, including clotr-mcp, runs as a local child process and talks to your AI client over stdio (standard input and output). Prompt hooks keep salted fingerprints of findings for two minutes so you can resend a paused prompt. They never store prompt text. The MCP server makes no network calls; in MCP, "server" means the process that offers tools.

Stable and preview

Stable features have tests that run on every change and keep working the way this page describes. Preview features are tested as well, but they may still change, and the reasons are under the table.

The shell check is a preview because it knows the usual ways to print a file or the environment, and a command it doesn't know can still print one. clotr-mcp runs only when the assistant decides to call it, and its tools may change as assistants use them. The skill is new, and each assistant looks for skills in its own folder.

Install

Install it globally:

npm install -g clotr-guard

Hook setup and clotr-mcp --print-config stop when run through npx, and tell you to install Guard globally first. The MCP server is the one part that runs straight from npx, as npx -y clotr-guard mcp.

Install from a clone

From the repository root, build the engine bundle first with node tools/engine-bundle.js --out apps/guard/dist/clotr-engine.js, then run npm link ./apps/guard to add the clotr-guard and clotr-mcp commands to your PATH. You can also run node apps/guard/bin/clotr-guard.js instead. The bundle is built from the checked-in engine files but isn't checked in itself, so until it's built every check answers that Clotr couldn't check the text. Build it again after the engine changes, since npm test fails on a stale copy.

Add Clotr MCP to an assistant

The MCP server ships in the Guard package and uses its engine and secret-file rules. It starts with clotr-mcp or clotr-guard mcp, which run the same server. After installing Guard, print the configuration snippet for the assistant you use:

clotr-mcp --print-config claude

clotr-mcp --print-config cursor clotr-mcp --print-config gemini clotr-mcp --print-config codex clotr-mcp --print-config windsurf clotr-mcp --print-config cline clotr-mcp --print-config vscode

Add the snippet to Claude Code's .mcp.json or its MCP settings, Cursor's project or user MCP settings, Gemini CLI's ~/.gemini/settings.json or project .gemini/settings.json, Windsurf's MCP settings, Cline's MCP Servers settings or ~/.cline/data/settings/cline_mcp_settings.json for the CLI, VS Code's .vscode/mcp.json under servers, or Codex CLI's ~/.codex/config.toml under [mcp_servers.clotr]. Gemini CLI's MCP guide describes its mcpServers settings.

To skip the global install, point the assistant at npx instead, and npm downloads Guard into its cache the first time the server starts:

{

"mcpServers": { "clotr": { "command": "npx", "args": ["-y", "clotr-guard", "mcp"] } } }

The server runs on this computer over standard input and output. It checks only when the assistant calls it and returns finding kinds and masked forms. include_personal_details adds personal details to check_text and clean_text; credentials stay checked either way.

Give your assistant the Clotr skill

The package carries a skill file for coding assistants, skills/clotr/SKILL.md. It tells the assistant that when Clotr stops something, it should tell you what was stopped and leave the choice to you instead of trying another way to get the same text. It also says how to call the MCP tools. Copy the skills/clotr folder to ~/.claude/skills/clotr for Claude Code, or to ~/.agents/skills/clotr for Codex CLI, Gemini CLI and Cursor. The installed copy sits in clotr-guard/skills/clotr under the folder that npm root -g prints.

Set up a hook

Run one command for each assistant you use:

clotr-guard setup claude

clotr-guard setup cursor clotr-guard setup gemini clotr-guard setup codex clotr-guard setup windsurf clotr-guard setup cline clotr-guard setup git

These commands add the prompt hook and, where supported, the file-read hook to your user settings. Run the command inside a project with --project to add them to that project's settings instead. Use --dry-run to preview the change. Run clotr-guard remove to remove Clotr's hooks, or add --project to remove its project hooks. Before a change is written, Clotr saves a copy of an existing settings file beside it with .clotr-guard.bak on the end, and a .bak of your own is left alone. setup git installs a local pre-commit hook in the current repository; remove git removes it or restores the hook that was there before.

Claude Code uses ~/.claude/settings.json and its UserPromptSubmit hook. Cursor uses ~/.cursor/hooks.json and beforeSubmitPrompt. Gemini CLI uses ~/.gemini/settings.json and BeforeAgent. Codex CLI uses ~/.codex/hooks.json and UserPromptSubmit. Windsurf Cascade uses ~/.codeium/windsurf/hooks.json, pre_user_prompt and pre_read_code; project setup uses .devin/hooks.json, or the existing .windsurf/hooks.json when it is the active legacy file. Cline uses extensionless executable hooks in ~/Documents/Cline/Hooks/ and its UserPromptSubmit and PreToolUse events; project setup uses .clinerules/hooks/. In Cline, turn on Enable Hooks in Feature Settings. Cline's hook guide lists its supported events and platforms. Cline hooks are supported on macOS and Linux only. Other project settings files are .claude/settings.json, .cursor/hooks.json, .gemini/settings.json and .codex/hooks.json in the current directory.

Prompt, file-read, shell, MCP tool and commit checks leave personal details out by default while credentials stay checked. Personal details are the kinds the engine groups as personal, such as names, email addresses, phone numbers, street addresses, national ID and passport numbers, and dates of birth. Card numbers, card security codes, gift-card codes and bank account numbers sit in that group too, but they're money, so Guard always checks them like a credential. Add --personal-details to Guard hook setup or commit-check to include the rest. An internal network address or host name counts as a personal detail here. With the option on, Guard names it in a short line but lets the prompt, read or commit through, since telling an assistant about your own server is ordinary work.

The prompt hook checks only the prompt field each tool sends to it. Claude Code also checks mcp__ tool arguments and Cursor checks MCP arguments and shell commands. Those checks stop credentials and medium or high findings, asking you to decide where the tool supports a question. The Bash and shell hooks look for credentials in commands, common environment dumps and file readers that could print secret files. They use the same secret-file rules as reads and commits. They do not scan ordinary command words. They read commands the way common shells write them, so an unusual command can still get past them. Each shell check has limits. For globs it lists at most 8,192 folder entries or spends 1 second listing folders, and it looks up at most 250,000 paths or spends 2 seconds on them; past either, it judges the remaining paths by their names alone. A folder a reader such as grep -r reads in full is walked, up to 131,072 entries in all, within the path check's 5 seconds; a folder too big or too slow for that stops the command. If the path check runs past 5 seconds, or the whole check past 10 seconds, Guard stops the command and its message says why. The check runs in a process of its own that Guard stops at the 10-second limit, so a slow drive or folder can't hold it past that. File-read hooks check Claude Code's Read, Cursor's Agent file reads, Gemini CLI's read_file, Windsurf Cascade's pre_read_code and Cline's PreToolUse. Binary files and folders pass without a message. Text saved as UTF-16, with or without a byte order mark, or in an older single-byte code page is checked like any other text. A larger text read checks the first 256 KiB and says the rest wasn't checked. The read hooks show only finding kinds. Secret files are denied in every tool with a reason for the assistant and no prompt to you. In Claude Code, ordinary files with credentials ask whether to allow the read. The other tools stop it, because a second read would come from the assistant rather than from you, so reading the same file again never lets it through. Claude Code also gets a Bash and PowerShell hook for plain commands that print secret files or dump the environment. Gemini CLI also loads .env files by default. After setup gemini, Clotr prints how to turn this off with advanced.ignoreLocalEnv in Gemini's settings.json; Clotr does not change that setting. Hook findings never include the full value in their message. On Windows, Clotr keeps its repeat record in %LOCALAPPDATA%\Clotr\guard; other systems use their per-user application data folder. The record is local plain state readable by the same computer account or its processes, and Guard does not sync it. It holds a random salt, salted fingerprints of the findings and the time of the first warning. Clotr does not save prompt text or file contents. If Clotr hits an internal error while checking a prompt, a file read or an MCP tool call, Guard lets it through with a visible note that says it went th