agentcurfew

One local, account-less security policy for the files that steer your AI coding agents: skills, MCP servers, hooks, context files and permissions.

Install Rules GitHub npm

On this page

A sibling of depcurfew: depcurfew guards the packages that people and agents install, agentcurfew guards the files that steer the agent.

AI coding agents (Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot in VS Code, Windsurf, Cline) read files from your repository and your machine that decide how they behave: SKILL.md files with bundled scripts, MCP server configs, hooks, context files such as AGENTS.md and CLAUDE.md, and permission settings. Whoever can change those files can steer the agent, so they are a supply chain of their own.

agentcurfew:

lists every such component in a project, for every agent it knows, including settings that run a command (statusLine, apiKeyHelper, headersHelper), settings that redirect the agent or bring code into it (env such as ANTHROPIC_BASE_URL, plugin marketplaces, Gemini CLI's context.fileName) and the scripts of the project that hooks run (scan --inventory);
checks them against 18 rules: hidden Unicode, unpinned npx MCP servers and hooks, plain-HTTP MCP endpoints, secrets in configs, dangerous hooks, auto-run on open, permission bypasses, API traffic sent to another host, plugin marketplaces, instructions fetched at run time, persistence instructions and more (scan);
locks them with checksums in agentcurfew.lock, the scripts hooks run included, so CI fails when one changes (lock, verify);
enforces a policy in agentcurfew.policy.json: allowed skill sources and MCP servers, pinned versions, exceptions with a reason and an end date (init, policy);
finds configuration that agents ignore or that does not work: misnamed files, wrong keys, settings that another file overrides (doctor);
guards the agent itself: an MCP server with read-only checks, and a Claude Code hook that stops dangerous writes to these files and to the scripts hooks run (MCP server and hook).

Every fact about an agent (paths, formats, precedence) comes from its official docs or source code, with the address and the date, in the knowledge base.

Rules of the scanner

It never runs what it reads: no MCP server is started, no hook, script or command is run.
It makes no network calls. Checks that need a registry stay with depcurfew.
It treats every file as hostile: size and depth limits, no links followed out of the project, secrets masked in every output.
One deterministic lockfile for every agent and every kind of component.

Install

npm install --save-dev agentcurfew
# or, without installing
npx agentcurfew@1 scan

It needs Node.js 20 or later. The command is agentcurfew.

In a project with a release-age delay (min-release-age in .npmrc, as depcurfew apply writes it), npx agentcurfew@<version> fails with ETARGET until that version is older than the delay, and min-release-age-exclude does not help, since npx and npm exec ignore it. Install agentcurfew as a dev dependency and run it from node_modules/.bin, or use the GitHub Action below, which installs it outside the project.

Use

agentcurfew scan                        # exit code 1 on a finding at level high or above, or a file it could not read
agentcurfew scan --fail-on medium --json
agentcurfew scan --sarif > agentcurfew.sarif   # for GitHub Code Scanning
agentcurfew lock                        # write agentcurfew.lock; commit it
agentcurfew verify                      # in CI: exit code 1 when anything changed since the lock
agentcurfew init                        # write agentcurfew.policy.json from what the project has now
agentcurfew doctor                      # find files and settings that agents ignore
agentcurfew explain hidden-unicode      # what a rule finds and how to fix it

Run agentcurfew for the common commands, and agentcurfew help <command> for the options and examples of one. --user also reads your home directory and machine settings. JSON and SARIF output are described in docs/cli-json.md.

A clean scan means that none of the rules' patterns was found, not that the configuration is safe: see what agentcurfew does not find.

MCP server and hook

agentcurfew mcp serves read-only tools to an agent over MCP (stdio): check_skill and check_mcp_config before something is installed, scan_project and explain_rule. It reads only its own folder, folders given with --root and the roots the client shares.

agentcurfew init --hook adds a PreToolUse hook to .claude/settings.json, next to depcurfew's hook if there is one. Writes to the files that steer agents ask first, and are denied when the new text has a finding at high or above or breaks the policy; npx skills add and claude mcp add are denied outside the policy. The hook never allows anything by itself. See docs/mcp.md.

With depcurfew

agentcurfew protects what configures the agent; depcurfew protects the packages the project and the agent install. Together:

When depcurfew 1.5.2 or a later 1.x is installed and the project has depcurfew.json, the rule mcp-package checks the package each MCP server starts through npx, uvx and the like with depcurfew's library, offline: sources the policy forbids and specs that are not specs. Checks that need the registry (release age, existence, install scripts, similar names, known malicious versions) stay with npx depcurfew check <package>, which unpinned-mcp-server points to.
agentcurfew doctor warns when the project has depcurfew.json but Claude Code has no depcurfew hook (depcurfew-hook-missing), and when that hook points at a depcurfew that is not installed (depcurfew-hook-broken, an error with onFailure: "block", since every command is then blocked).
agentcurfew init --hook adds its own hook next to depcurfew's, and never changes it.

depcurfew is an optional peer dependency: without it, everything else works the same.

GitHub Action

permissions:
  contents: read
steps:
  - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
    with:
      persist-credentials: false
  - uses: DevXord/agentcurfew@<full commit sha> # pin to a commit, not a tag
    with:
      command: scan          # or verify, or doctor (whose fail-on levels are error, warning, info)
      fail-on: high

Inputs: command, directory, fail-on, sarif-file, upload-sarif (needs security-events: write) and build-from-source (for tests of the action itself). Output: exit-code. A released commit runs the matching version of agentcurfew from npm, so pin the commit of a release tag: a later commit of main still runs the last released version. The action does not install depcurfew, so mcp-package does not run in it; scan then says so in a note. How releases are made: docs/RELEASING.md.

Development

npm ci --ignore-scripts
npm test
npm run typecheck
npm run check:pkg
npm run site        # the documentation site, into dist-site/

Security reports: SECURITY.md.

License

MIT.