Zn Gate

zn-gate

The local security layer for coding agents. zn-gate guards your secrets, your data and your systems while you use Claude Code, Codex CLI, Cursor, OpenCode, Antigravity or ZCode desktop app.

zn-gate is an open-source security layer that runs on your machine, between your agent and the tools and content it touches. It checks what the agent reads and calls for prompt injection, redacts secrets from tool output before the model sees it, and audits prompts, skills and configs. No account, no network by default, and no runtime dependencies except age-encryption (and its @noble/@scure dependencies) for the secret vault, bundled in the package at the versions pinned in package-lock.json.

For: developers using Claude Code, Codex CLI, Cursor, OpenCode, Antigravity, ZCode desktop app or any MCP client. Python SDK: zn-gate on PyPI.

Install

Everything runs on your machine; no account or API key is needed. Node.js 22 LTS is recommended (from nodejs.org). Node.js 18 or later works for the hooks and the CLI; the Claude Code plugin needs 20.19 or later. For security, use the latest patch of a supported Node.js line (22.23.4, 24.22.1, 26.12.1 or later): Node.js 18 and 20 are end-of-life and get no security fixes, even though zn-gate still runs on them. With a Node.js older than 18, the zn-gate and zn commands stop and say how to install it.

Getting started: four steps, one command each. Run them in your own terminal.

1. npx -y zn-gate reach shows what your coding agents can reach on this machine: secrets in your .env files (by name only), credential files and MCP servers. It is read only and sends nothing. Details in docs/reach.md.
2. npx -y zn-gate init sets up protection for the coding agents it finds, one step at a time, and asks before each change.
3. npx -y zn-gate check tests that protection with a fake secret in a temporary folder. init runs it at the end too.
4. npx -y zn-gate env shadow .env moves the real values of your .env into the local vault and leaves markers in the file. The first time, run npx -y zn-gate unlock to create the vault.

One command for the coding agents on your machine:

npx -y zn-gate init

init does this:

• It finds Claude Code, Codex CLI, Cursor, OpenCode, Antigravity and ZCode desktop app on your machine.
• For each one that is not protected yet, it shows the setup: the zn-gate plugin for Claude Code (or zn's hooks when your Node.js is older than 20.19), and zn's hooks for the others.
• It runs each step only after you confirm it.
• It ends with zn-gate check.

Run it yourself, in your own terminal. When an AI agent or a script runs it, it only prints the steps.

Windows PowerShell: npm and npx can fail with "running scripts is disabled on this system", because the default execution policy blocks npm.ps1. Use npm.cmd, npx.cmd and zn.cmd instead (for example npm.cmd install -g zn-gate), run the commands from Command Prompt, or allow local scripts for your account with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

If something fails:

• npx: command not found, or a message about the Node.js version: install the LTS version of Node.js, open a new terminal and run the command again.
• "running scripts is disabled on this system" on Windows: see the PowerShell note above.
• init only prints steps and changes nothing: an AI agent or a script ran it. Run it yourself in your own terminal.
• check shows NOT protected: that line says why and what to run. What the output means.
• You want to remove zn-gate: npx -y zn-gate uninstall shows what it will remove (the Claude Code plugin, zn's hooks, wrapped MCP servers) and asks first. init --revert only puts back MCP configs saved before wrapping.

Then keep your `.env` values in the vault. With the plugin or the hooks, the agent cannot read .env files with real values; move them into zn-gate's encrypted vault, and the file keeps markers such as __ZN_STRIPE_KEY__:

npx -y zn-gate unlock            # creates the vault the first time

npx -y zn-gate env shadow .env

After this, your own app also reads the markers in .env: start it with zn-gate's run command once you allow it (docs/secrets.md). env shadow tells you how to undo it.

Five-minute walkthrough: docs/secrets.md. Limits: docs/threat-model.md. Words you do not know: glossary. Every command and exit code: command line reference.

Other ways to install : one agent at a time, other editors, Python, MCP server only

One agent at a time (the same steps init runs):

Claude Code: the plugin. You also need Git and Claude Code 2.1.295 or later. The plugin needs Node.js 20.19 or later. With an older Node.js, npx -y zn-gate init skips the plugin and sets up zn's hooks for Claude Code instead (zn-gate check says so if the plugin is installed); update Node.js to use the plugin.

claude plugin marketplace add usezn/zn

claude plugin install zn-gate@usezn

Already ran zn hooks install claude-code before? Run zn hooks uninstall claude-code first, otherwise both sets of hooks run.

Start a new Claude Code session. Claude Code is then blocked from reading .env files with real values and credential files, secrets in what its tools return are replaced with markers or redacted before the model sees them, a secret pasted into a prompt is blocked. The plugin adds no MCP server since version 1.14.0: for the secrets server, run zn hooks install claude-code instead of the plugin. Not covered: Claude Code sessions in the cloud, Cowork and chat. Details: plugins/zn-gate.

Codex CLI, Cursor or OpenCode: the hooks.

npm install -g zn-gate

zn hooks install codex # or: cursor, opencode

In Codex, approve the new hooks with /hooks. In Cursor, shell output and file contents are not scrubbed. What each agent supports: docs/compat.md.

Other editors (VS Code, Windsurf, Cline, Zed, JetBrains, Continue): zn-gate works there as an MCP server only. Setup for each one: usezn.com/docs/integrations/editors.

Antigravity. zn hooks install antigravity (or npx -y zn-gate init) adds a hook that runs before each tool call. It blocks reads and writes of secret files and shell commands that handle secrets, and the agent cannot edit the hook files. It cannot remove secrets from what a tool returns, Antigravity's MCP configuration files are not protected, and Antigravity does not document what happens when a hook fails (in our tests the call is blocked), so treat it as a first layer. The MCP server works there too. Details: Antigravity page.

ZCode desktop app. zn hooks install zcode (or npx -y zn-gate init) adds hooks that run before each tool call and before each prompt. It blocks reads and writes of secret files, shell commands that handle secrets, MCP calls that would send a secret, and a prompt that contains a secret, and the agent cannot edit ZCode's own config file. It cannot remove secrets from what a tool returns (zn adds a notice when an output holds one), ZCode ignores the hooks of a project, and zn's launcher blocks the call when its Node.js is gone, so treat it as a first layer. ZCode's documentation does not say what happens when a hook fails; in our tests with the ZCode desktop app 3.16.3 on Linux, a hook that failed (an exit code other than 2, a crash or a timeout) let the call run, and only exit code 2 or a deny answer blocked it. Tested end to end on the ZCode desktop app 3.16.3 on Linux x64 and Windows x64 (Windows Server 2022, through the agent the app ships; the Windows app window was not driven); macOS is not tested. Details: ZCode page.

Copilot CLI (experimental). zn hooks install copilot adds hooks that run before and after each tool call. They block reads and writes of secret files and shell commands that handle secrets, and replace secret values in the results of read-type and shell tools. They cannot block a typed prompt, Copilot lets a call through when a hook times out, so zn, which sets a 15-second timeout on its hooks, blocks the call itself at 11 seconds, it has not been tested on Windows, and Copilot's own session log keeps the original output, so treat it as a first layer. Details: Copilot CLI notes.

Gemini CLI (experimental). zn hooks install gemini adds a hook that runs before each tool call. It blocks reads and writes of secret files and shell commands that handle secrets, and the agent cannot edit Gemini CLI's settings files. It does not change what a tool returns, Gemini CLI hooks cannot ask you for confirmation, and Gemini CLI lets a call run when a hook crashes or times out, so zn blocks it instead (a hook that fails is answered with a block, and zn sets a 15-second timeout on its hook and answers a check still running after 11 seconds with a block), so treat it as a first layer. Google replaced Gemini CLI with Antigravity CLI for free and Google One accounts on 18 June 2026; Gemini CLI keeps working with zn-gate. Details: Gemini CLI notes.

Python: for agents you build yourself (rules engine and secret redaction for LangChain, CrewAI, LlamaIndex or plain tool calling). It does not protect Claude Code, Codex, Cursor or other coding agents. Install it in a virtual environment; many recent Linux systems, and Homebrew's Python on macOS, refuse pip install outside one ("externally-managed-environment"):

python3 -m venv .venv

.venv/bin/pip install zn-gate # Windows: .venv\Scripts\pip install zn-gate

zn-gate as an MCP server only (the agent calls it when it decides to; not automatic protection):

claude mcp add zn-gate -- npx -y zn-gate mcp     # Claude Code

codex mcp add zn-gate -- npx -y zn-gate mcp # Codex CLI

Cursor (~/.cursor/mcp.json) and other editors: { "mcpServers": { "zn-gate": { "command": "npx", "args": ["-y", "zn-gate", "mcp"] } } }. OpenCode (~/.config/opencode/opencode.json): { "mcp": { "zn-gate": { "type": "local", "command": ["npx", "-y", "zn-gate", "mcp"], "enabled": true } } }.

Wrap the MCP servers you already use

init finds MCP servers in your agent config files, writes a backup, and wraps each local (stdio) server with zn-gate shield:

npx -y zn-gate init --dry-run   # preview, changes nothing

npx -y zn-gate init --wrap-mcp # wrap (a .bak. copy is written first) npx -y zn-gate init --shadow # log detections without blocking npx -y zn-gate init -