Guardian (safety guard)

The Guardian asks you before your secrets reach the model and puts a speed bump in front of deletes and commands that can't be undone. On by default, in every tool and on every plan.

What it does

The Guardian checks two things your coding agent does in Cursor, Claude Code and Codex, in the VS Code panels and in the terminal: reading a file, and running a shell command. It runs on your Mac, before the agent acts, on Pro, the trial and the free tier, and even while switching is paused or off. It is off while the Mac is signed out: with nobody signed in, OptiFlume does nothing in any tool. (The session watchdog is different: it is also off while switching is off.) Its messages start with [OptiFlume Guardian].

In Codex, the Guardian works once you approve OptiFlume’s hooks: in the panel in Settings → Hooks, or by typing /hooks in codex in the terminal. Approvals you gave before an update are kept; a hook that an update adds needs one approval. See Codex.

Three modes

The mode decides what happens when the Guardian finds a secret or a sensitive file. It is the same in every tool.

optiflume guardian ask       # the default
optiflume guardian strict
optiflume guardian allow
optiflume guardian status    # what happens in the current mode
optiflume guardian off       # the whole Guardian off; on turns it back on

You can also pick the mode, or turn the Guardian off, in optiflume configure. Deletes and destructive commands ask in every mode (see Deletes and Destructive commands).

Secret files and keys

No tool lets OptiFlume change what a file read returns, so the Guardian does not hide parts of a file. It decides about the whole file: in ask mode the agent waits for your answer, in strict mode the file stays away from the model, and in allow mode it goes ahead with a warning. When a file is held back, the agent is told not to read it another way.

It is sure about these files, by their name:

• .env and its variants such as .env.local or .env.production. Templates such as .env.example, .env.sample and .env.template are read as usual.
• credentials.json and service-account JSON files
• Private keys: *.pem, *.key, id_rsa, id_ed25519. A .pem file that holds only public certificates is read as usual.

And any other file that contains:

• AWS access keys and secret keys
• GitHub, Slack and OpenAI keys, and Stripe live secret keys
• Private key blocks
• Payment card numbers, IBANs and US Social Security numbers. Each one is validated (the card checksum, the IBAN checksum, the valid Social Security number ranges), and published test card numbers are ignored, so ordinary numbers in code don’t set it off.

The Guardian checks a file when the agent opens it, and when the agent prints it with a shell command such as cat, head or sed -n. Codex reads files that way, so this is how the Guardian protects your files in Codex.

Some finds may be harmless or may not: a sign-in token, a database address with its password, a key-like value assigned in code, or a phone number. The mode applies to these too: in ask mode you choose whether the agent may use the file (see When the agent stops and asks you).

To always let a file through, run optiflume allow <file>. It adds the file’s full path to whitelisted_files (see Configure it), in every tool.

Deletes

In every tool and every mode, the Guardian asks you before the agent deletes a file or folder that existed before the session, moves or renames something over one, or empties one (> file, truncate -s 0). What the agent created in this session it can delete freely. Folders such as node_modules, dist or build are no exception: if they were there before the session, deleting them asks too.

A file existed before the session if it was created before the conversation started, is in the repository’s last commit, or OptiFlume saw it before the agent touched it. This covers rm with any flags, rmdir, unlink, shred -u, trash, find -delete and find -exec rm, git clean, git rm, mv onto an existing path, rsync --delete, Python, Node, Ruby and Perl one-liners that delete, Codex’s patches that delete a file (or move or add one onto an existing file), Cursor’s Delete tool and MCP delete tools. When it is unclear what would be deleted (a path in a variable, files from xargs), the Guardian asks.

Claude Code shows its own dialog; in Cursor and Codex the agent stops and asks you in chat, and your allow covers one use. With block_destructive_commands on, these deletes are blocked instead.

Destructive commands

Before the agent runs a shell command that cannot easily be undone, the Guardian steps in, in every mode. It looks out for:

• Deletes of what existed before the session (see Deletes)
• Force pushes, git reset --hard and git clean -f
• Dropping or truncating database tables, and DELETE FROM without a WHERE clause
• chmod 777
• Writing straight to a disk device, and formatting one (mkfs)
• Piping a download into a shell (curl … | sh)

What happens next depends on the tool:

• Claude Code asks you to approve the command in its own dialog.
• Cursor and Codex: the Guardian stops the command and the agent asks you in chat. Reply allow to let it run once (see When the agent stops and asks you). To let a command you trust through every time, add it to whitelisted_commands.
• With block_destructive_commands on, every tool blocks the command.

git push --force-with-lease goes ahead.

Commands that print secrets

A command that prints a sensitive file, such as cat .env, is kept away from the model just like a read of that file, also when it is tucked inside bash -c or $(…). A command that prints a file with keys, card numbers or bank details in it is kept away too (see Secret files and keys).

Commands that may print secrets into the conversation (echoing variables named like keys, secrets or tokens, and printenv, env or set on their own) follow the mode, like a file with secrets.

When the agent stops and asks you

The Guardian wants you to know when an agent is about to use your secrets or run something that can’t be undone. Where your tool can ask you itself, it does. Where it can’t, the Guardian stops the agent, and the agent asks you in the chat, like any other question it has for you.

• Claude Code shows its own Allow / Deny dialog, and the agent waits for your answer.
• Cursor: for file reads and shell commands alike, the Guardian stops the agent and it asks you in chat. (Cursor ran a command past its own question in our tests, so the Guardian does not rely on it.)
• Codex can’t ask from OptiFlume’s hooks, for file reads or commands, so the Guardian stops the agent and it asks you in chat.

The same rules in every tool. OptiFlume makes each of these choices once and applies it to Cursor, Claude Code and Codex alike; a tool only changes how the question reaches you. One example: if you switched a tool’s own approvals off (Claude Code’s --dangerously-skip-permissions, Codex’s bypass or full-access mode), you chose not to be interrupted, so for an unsure find the Guardian doesn’t stop the agent there; you get a warning such as “The agent is using the secrets in config/prod.yml for your task.” Sure finds (such as .env files, real keys, card or bank numbers), deletes of what existed before the session and destructive commands are still stopped, and the agent asks you in chat.

When the agent asks in chat, you answer with your next message:

• Reply allow (or yes, ok, go ahead) and the agent may use that one file or run that one command, once, in that conversation. The next time it needs it, it asks again.
• Reply anything else, such as “no, use the test database”, and the agent stays stopped and follows what you said.
• The agent waits up to 10 minutes for your answer. Only your own message counts: the agent can’t approve itself.

Prefer not to be asked? Run optiflume guardian allow to get warnings instead, or optiflume guardian strict to keep secrets out with no question (see Three modes). Deletes and destructive commands still ask.

Configure it

Safety settings live in a safety section of ~/.optiflume/config/advanced-config.json. The file does not exist until you create it; every key is optional, and anything you leave out keeps its default.

{
  "safety": {
    "enabled": true,
    "redact_env_files": true,
    "detect_personal_data": true,
    "warn_destructive_commands": true,
    "block_destructive_commands": false,
    "mode": "ask",
    "whitelisted_files": ["fixtures/fake.env"],
    "whitelisted_commands": ["rm -rf ./build"]
  }
}

Changes apply to the next file read or command; there is nothing to restart. Setting the three on/off choices for all your Macs from console settings is coming soon. All settings are in the Settings reference.

The audit log

Every file kept away, every stop, question, warning and block, every “allow” you gave, and every find that was let through is recorded on your Mac in ~/.optiflume/telemetry/safety-audit.ndjson, kept for 90 days. It records the file name, or the first 200 characters of the command with any secret in it masked, and never the secret itself. The daily usage rollup carries only the counts; see Analytics and telemetry.

tail -20 ~/.optiflume/telemetry/safety-audit.ndjson

Limits

The Guardian recognizes common secret formats and file names; it is a safety net, not a replacement for keeping secrets out of your repository. If the Guardian itself fails, the read or command goes ahead unchanged rather than blocking your work.