block

Block

Protect files from unwanted AI modifications in Claude Code and OpenCode.

Drop a .block file in any directory to control what AI agents can and cannot edit. Protect configs, lock files, migrations, or entire directories with simple pattern rules.

Why use this?

• Prevent accidents — Stop Claude from touching lock files, CI workflows, or database migrations
• Scope to features — Keep Claude focused on relevant directories, not unrelated code
• Guide Claude — Custom messages explain why files are protected and what to do instead
• Zero friction — Once set up, protection works automatically on every session

Requirements

• Python 3.8+ — Required for the protection hook

Installation

Claude Code

1. Register the marketplace:

/plugin marketplace add kodroi/block-marketplace

2. Install the plugin:

/plugin install block@block-marketplace

OpenCode

Add the plugin to your opencode.json config:

{
  "plugins": ["opencode-block"]
}

Or for local development, clone this repo and reference the plugin directly:

{
  "plugins": ["file:///path/to/block/opencode/index.ts"]
}

You can also set up the plugin manually by copying files into your project. The plugin expects hooks/protect_directories.py to be a sibling of the directory containing index.ts:

your-project/
├── .opencode/
│   └── plugin/
│       └── index.ts              # copied from opencode/index.ts
├── hooks/
│   └── protect_directories.py    # copied from hooks/protect_directories.py

Note: The tool.execute.before hook protects tools called by the primary agent. Tools invoked by subagents spawned via the task tool may not be intercepted.

Usage

Use the /block:create command to interactively create a .block file:

/block:create

Or create a .block file manually in any directory you want to protect.

.block Format

The .block file uses JSON format with three modes:

Block All (Default)

Empty file or {} blocks all modifications:

{}

Allowed List

Only allow specific patterns, block everything else:

{
  "allowed": ["*.test.ts", "tests/**/*", "docs/*.md"]
}

Blocked List

Block specific patterns, allow everything else:

{
  "blocked": ["*.lock", "package-lock.json", "migrations/**/*", ".github/**/*"]
}

Guide Messages

Add a message shown when Claude tries to modify protected files:

{
  "blocked": ["migrations/**/*"],
  "guide": "Database migrations are protected. Ask before modifying."
}

Pattern-Specific Guides

Different messages for different patterns:

{
  "blocked": [
    { "pattern": "*.lock", "guide": "Lock files are auto-generated. Run the package manager instead." },
    { "pattern": ".github/**/*", "guide": "CI workflows need manual review." }
  ],
  "guide": "This directory has protected files."
}

Scope to Feature

Keep Claude focused on specific directories during feature work:

{
  "allowed": ["src/features/auth/**/*", "src/components/auth/**/*", "tests/auth/**/*"],
  "guide": "Working on auth feature. Only touching auth-related files."
}

Agent-Specific Rules (Claude Code only)

Scope protection to specific subagent types. For example, block a code-review agent from modifying source files:

src/
└── .block      → {"agents": ["code-reviewer"]}

This blocks the code-reviewer subagent from writing to src/. Other subagents and the main agent are unaffected — the .block file is skipped for them.

Key	Type	Description
agents	string[]	Subagent types this .block file applies to (others are skipped). Main agent is always skipped.
disable_main_agent	bool	When true, the main agent is skipped (for use without agents)

Truth table:

"Skipped" means this .block file is skipped — other .block files may still block.

Config	Main agent	Listed subagents	Other subagents
No agent keys	Blocked	Blocked	Blocked
agents: ["TestCreator"]	Skipped	Blocked	Skipped
disable_main_agent: true	Skipped	Blocked	Blocked
Both keys set	Skipped	Blocked	Skipped
agents: []	Skipped	Skipped	Skipped

Pattern Syntax

Pattern	Description
*	Matches any characters except path separator
**	Matches any characters including path separator (recursive)
?	Matches single character

Examples

Pattern	Matches
*.ts	All TypeScript files in the directory
**/*.ts	All TypeScript files recursively
src/**/*	Everything under src/
*.test.*	Files with .test. in the name
config?.json	config1.json, configA.json, etc.

Local Configuration Files