How it works

Cloakroom checks what goes to the AI and swaps real values for placeholders.

What it stops beyond hiding values: Security

In short

Every time the AI reads a file, runs a command or uses an add-on, Cloakroom checks what goes to the AI and swaps real values for placeholders. When the AI writes or runs something that holds a placeholder, Cloakroom puts the real value back on your machine. Commands that would send a secret off your machine, or move money, wait for your OK, and so does a hook or MCP server the agent adds to its own settings. The agent can’t approve a call Cloakroom held or switch Cloakroom off (what it stops).

Words used below: hooks are small checks the agent runs before and after each action (a “tool call”). MCP tools are add-ons that give the agent extra abilities, such as a browser. OCR reads text out of pictures. The vault is an encrypted file on your machine that holds the real values for one session.

  Claude Code reads a file or runs a tool
        |   "Nadia Petrov called about..."    sk_live_51Hx9Q...
        v
  +--------------------------------------------+
  | Cloakroom  (on your machine)               |
  |   rules + local model  ->  find the values |
  |   encrypted vault      ->  remember them   |
  +--------------------------------------------+
        |   "PII_PERSON_1 called about..."    PII_SECRET_1
        v
  the model works with placeholders only
        |   Write reply.md: "Hi PII_PERSON_1,"
        v
  Cloakroom puts the real value back, locally
        |
        v
  reply.md on your disk: "Hi Nadia Petrov,"

The two modes

Full (the default): Runs pattern rules and an AI model on your machine (PII-Tracer). It catches keys, passwords, card numbers, government IDs, and also names, addresses and other personal details written as plain text.
Rules: Runs the pattern rules only. It still catches keys with a known shape (AWS, GitHub, Stripe, Slack, OpenAI, Google, JWT login tokens, private keys), numbers with a built-in check digit (cards, IBANs, SSNs) and emails or names next to an obvious label, but it misses most personal data in ordinary sentences. Use it when you can’t install the model, or when you only care about secrets.

Set the mode for everything in ~/.cloakroom/config.json, or for one shell with CLOAKROOM_MODE=rules, or for one command with --mode rules.

{ "mode": "rules" }

Backends (full mode only)

CLOAKROOM_BACKEND picks how the model runs. The default, auto, uses PyTorch when there’s a GPU (Apple Silicon or an NVIDIA card with CUDA), otherwise the ONNX export if you’ve made one, otherwise PyTorch on the CPU. ONNX is a model format that runs fast on a plain CPU.

cloakroom export-onnx writes the CPU model under ~/.cloakroom/onnx/. It needs PyTorch once and takes a few minutes (about 4 on a 2-core cloud machine).
CLOAKROOM_ONNX=int8 uses a smaller, lower-precision export: a little faster, a few more false alarms.
CLOAKROOM_BACKEND=torch or onnx forces one.

cloakroom doctor prints the backend in use and how long one check takes.

Each step

Hide

A hook checks what goes into each tool and what comes back out. It runs pattern rules for secrets with known shapes, numbers with a check digit, rules that read the words around a value, and the PII-Tracer model for names, addresses and other personal data in sentences. A prompt with sensitive data is blocked instead, since a prompt can’t be rewritten. A value found once is masked everywhere it repeats.

Filter

A known-safe filter leaves harmless look-alikes alone, such as documented examples: published test cards and keys, IDs from test (sandbox) accounts, reserved domains like example.com, bot and role mailboxes (noreply@, support@), your own machine’s address (127.0.0.1), UUIDs and hashes, text that already hides a value ([REDACTED], ***), filler placeholders (AC000…, sk-...), standard numbers after RFC / ISO / ICAO / IEEE / PEP, and default dates (1970-01-01, 1900-01-01).

Pictures

PDFs become their text. Scans, pictures the agent opens and images in add-on tool results are read on your machine (OCR, the ocr extra), and only the masked text goes to the agent. Without the extra they are held back.

Put back (restore)

Values go into the vault. It is locked with AES-GCM, a standard encryption method, and its key sits in your system’s password store (Keychain on a Mac). When the agent writes a file or runs a command with a placeholder, the real value is put back locally. The AI never sees it.

Placeholders that can’t be guessed

Each placeholder ends in a short tag signed with a key from the vault, so it can’t be guessed. A value comes back only when the tag checks out and the placeholder is in this session’s vault. Anything else in placeholder shape stays as text. Three refused guesses in one session show you one line.

Files the agent wrote stay masked

When real values are put back into a file, the hook records, for each file, its path, a fingerprint of its contents (SHA-256), its size and time. For each value it records where in the file it sits, a fingerprint of the value, its kind and its placeholder. The log (~/.cloakroom/filelog.bin) is encrypted like the vault and holds no values: they are read back from the file when needed.

Holds the agent can’t lift

cloakroom allow, allow-host and uninstall refuse to run in an agent’s shell, and a shell command that runs them is denied. Removing Cloakroom is held. A hook or MCP server written into an agent’s config waits until you type cr: allow; the message names the file, the line and the command. Cloakroom reads the command’s text, so an agent that builds the name at run time is stopped only by its own sandbox, if it runs in one.

Encoded dumps and secrets

od, xxd, base64 and spaced-out output are turned back into text and checked; a hit holds the output back (it isn’t passed on). Each secret Cloakroom has already seen this session is also looked for in its encoded forms (base64, URL-encoded and JSON-escaped), and as an MD5, SHA-1 or SHA-256 hash, as hex, and reversed.

Other coding agents

Codex and Gemini CLI can’t swap a tool’s output for a masked copy, so Cloakroom blocks the original and the AI reads the masked text in the block message. Cursor can’t swap output either, so Cloakroom changes the input instead: a file read goes to a masked copy of the file, and a shell command runs inside Cloakroom, which prints only masked output.

Codex: cloakroom hook <event> --agent codex reads Codex’s hook input and turns the answer into Codex’s. Codex’s file edits (apply_patch) are restored and checked like Write. cloakroom install codex writes the four hooks into ~/.codex/hooks.json.
Gemini CLI: Gemini CLI uses its own tool names with Claude Code’s argument names, so --agent gemini first renames the tool. Gemini lets a call through when a hook times out, so with the model not loaded yet the hook doesn’t wait: it checks with the rules inside the hook itself. cloakroom install gemini writes these hooks as an extension of its own.
Cursor: Cursor’s agent sends its own tool names (Shell, Read, Write) with its own events, so --agent cursor first maps them. A read is redirected to a masked copy kept in Cloakroom’s home; a command is wrapped in cloakroom cursor-run, which runs it and masks what it prints; add-on (MCP) output is replaced with a masked copy. A write that carries a placeholder is refused, because Cursor ignores a hook’s rewritten input there, and the agent is told to write through the shell. Cursor’s Grep tool is refused when it would show file contents.

For tools that let you set their API address, such as Claude Code, Codex CLI and Gemini CLI, cloakroom proxy runs a small server on your own machine. Point the tool at it and every request is masked before it goes to the AI company; replies stream back unchanged. It is off until you start it, and works on Mac, Linux and Windows.

What it protects against, and what it doesn’t: Security. Every detail: docs-HOW-IT-WORKS.md.

Keep reading

Every command

What each cloakroom command does, when to run it and the release it first appeared in.

Writing

The write-up and what Cloakroom would and wouldn’t have done in October’s incidents.