module-gates plugin
Hooks for Claude Code and pi that block edits violating `MODULE.md` module contracts: readonly files and no new exports.
- 56 ★ on the repository
- Last commit
Extended access
Why this level
- Hooks run on every agent write and can block it, and the non-plugin install edits `.claude/settings.json`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/module-gatesDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks run on every agent write and can block it, and the non-plugin install edits `.claude/settings.json`.
This is third-party code. Review the repository files before installing.
What it does
module-gates curbs the codebase entropy that agents accumulate. Any directory can hold a `MODULE.md` descriptor listing protected files. The `readonly` label forbids editing a file, while `no-new-exports` allows changing the body but forbids adding new exports. The hook intercepts agent write and edit operations and blocks violations with a reason, which forces the agent to rethink the design. Importing internal module files from outside is also forbidden: imports are allowed only through `index.ts` or `mod.rs`. On session start the project is scanned and a hint is added to the system prompt. TypeScript and JavaScript, Rust, Java, Go, Kotlin and Scala are supported.
Who it is for. Teams where agents write a lot of code and module boundaries and public interfaces must be kept from accidental growth.
Good fit when
- An agent must not touch a generated or approved file, so it is marked `readonly`.
- A module public interface is pinned and new functions are allowed only inside bodies.
- External files may import only through `index.ts`, and bypasses are checked on every edit.
- Module discipline should hold the same way in Claude Code and pi.
Not a fit when
- The repository is small and the restrictions would only slow work.
- The main project language is outside the supported list.
- Import visibility checks are needed: the README marks them as not implemented yet.
Example request
Add a MODULE.md to the billing directory with readonly for legacy.ts and no-new-exports for api.ts, then try adding a new function to api.ts.Limitations
The hooks fire on agent write and edit operations and do not see edits made outside the agent. The descriptor file is named `MODULE.md` by default. Import checks by visibility scope are not implemented yet. For Claude Code the plugin installs dependencies into its own directory on first call, while the plain hooks variant needs the package in the project and writes `PreToolUse` and `SessionStart` into `.claude/settings.json`. Support for Cursor and other agents needs a separate bridge, and the language list is finite.
How to disable. Run `npx module-gates uninstall-claude` to remove the hooks, or delete the plugin with `/plugin uninstall module-gates@cuzfrog`.
FAQ
How do I install the plugin in Claude Code?
Run `/plugin marketplace add cuzfrog/module-gates`, then `/plugin install module-gates@cuzfrog`. No login is needed, the repository is public.
How do the labels in MODULE.md work?
`readonly` forbids any edit to a file. `no-new-exports` allows editing the body but blocks new exports.
What happens on a violation?
The hook blocks the write and names the reason. The agent sees the denial and must change approach.
Can I do without the plugin?
Yes: `npm install --save-dev @cuzfrog/module-gates`, then `npx module-gates install-claude`. The command writes hooks into `.claude/settings.json`.
Which agents are supported?
pi, Claude Code and Devin CLI. Others, such as qwen-code or Cursor, need a new bridge.
Discussion
No questions or reviews yet.
Related
PluginsTen Claude Code plugins: panes and bands above the prompt, secret handling, a vague-prompt filter and memory cleanup.
Shared Claude Code settings for a team: hooks against dangerous commands, a check before finishing and skills from spec to review
A Claude Code plugin that limits the agent with rules and hooks and hands independent code review to Codex CLI in a review loop.
Resolves which files import each other and what an edit will touch, and serves it to agents through hooks, MCP and a CLI
Plugins for git, Python and accessibility in one place: 400+ skills, subagents and hooks against dangerous agent commands.
A CLI and marketplace of hundreds of Claude Code plugins: lint and test hooks, language and framework skills, discipline agents
README in short
Module contracts are described by files in directories, and the hook checks every agent write. A denial example shows an attempt to add two public functions. Other agents are supported by adding a bridge.