claudeignore

CI CodeQL OpenSSF Scorecard

Sync gitignore rules to Claude Code sandbox, blocking file access via all tools (Read, Bash, Grep, etc.).

Alpha software — This project is under active development. Features may change, break, or behave unexpectedly. Always verify that your sensitive files are actually blocked after setup (claudeignore status, sync --dry-run). You are responsible for checking that protection works correctly in your environment before relying on it.

Why?

Claude Code has no built-in way to block access to gitignored files (.env, secrets, etc.). This tool fills that gap by blocking all access paths:

Modes

Gitignore mode (default)

Derives the deny list from your .gitignore, with overrides:

\[\text{denyList} = \text{.gitignore} - \text{.claude.unignore} + \text{.claude.ignore}\]
File Role Example
.gitignore Base deny list (from git) .env, node_modules, vendor
.claude.unignore Subtract: Claude CAN read these vendor, node_modules
.claude.ignore Add: extra deny beyond gitignore config/dev.secrets.php

Manual mode

Uses .claude.ignore only — no .gitignore dependency for the deny list:

\[\text{denyList} = \text{.claude.ignore}\]

Choose the mode during claudeignore init.

Both .claude.ignore and .claude.unignore use gitignore pattern syntax (*, **, !, etc.).

Install

macOS (Homebrew)

brew tap claudeous/tools
brew install claudeignore

macOS / Linux (curl)

curl -fsSL https://raw.githubusercontent.com/Claudeous/claudeignore/main/install.sh | sh

Installs to /usr/local/bin (may prompt for sudo).

Windows (Scoop)

scoop bucket add claudeous https://github.com/Claudeous/scoop-tools
scoop install claudeignore

Windows (manual)

Download the latest .zip from Releases, extract claudeignore.exe, and add its folder to your PATH.

All platforms (Go)

go install github.com/Claudeous/claudeignore@latest

Requires Go 1.21+. The binary is placed in $GOPATH/bin (must be in your PATH).

Getting started

⚠️ Prerequisite — Claude Code’s sandbox mode must be enabled. The OS-level protection layer (denyRead) is enforced by Claude Code’s sandbox. Without it, Bash access is not blocked (cat .env succeeds) — only the guard hook protects built-in tools (Read, Grep, etc.).

1. Enable the sandbox in ~/.claude/settings.json (or .claude/settings.json for the project):

{
  "sandbox": {
    "enabled": true
  }
}

2. Set up the project:

claudeignore init     # Choose mode, configure, hooks auto-installed
# Restart Claude Code

That’s it — init runs sync and install-hook automatically.

3. Verify the protection:

claudeignore status   # Should show synced state + hooks installed

Then ask Claude Code to cat a denied file (e.g. .env) — it should fail with permission denied. If it succeeds, the sandbox is not active: check sandbox.enabled and restart Claude Code.

Commands

Command Description
claudeignore Interactive menu with status
claudeignore init Choose mode + configure + install hooks
claudeignore sync Apply rules to sandbox
claudeignore sync --dry-run Preview deny list without writing
claudeignore check Check for changes (used by hook)
claudeignore guard Block tool access (used by hook)
claudeignore install-hook Install hooks (user + project scope)
claudeignore status Show current state

How it works

  1. init lets you choose a mode (gitignore or manual), then configures rules and installs hooks.
  2. sync computes the deny list based on the chosen mode, writes to settings.local.json as sandbox denyRead rules — enforced only if Claude Code’s sandbox mode is enabled (see Getting started).
  3. guard hook intercepts Read/Write/Edit/Grep/Glob and blocks access to denied paths.
  4. check hook alerts on every prompt if rules are out of sync or restart is needed.
  5. install-hook installs hooks in two scopes: user (~/.claude/settings.json, direct commands) and project (.claude/settings.json, safe wrapper with which check for teammates without the binary).

Change detection

The check hook detects two situations:

Restart detection works by comparing the sync timestamp with the Claude Code process start time (via PPID walk).

FAQ

Why does each dev need to run sync locally?

The source rules (.gitignore, .claude.ignore, .claude.unignore) are committed and shared via git. But the generated deny list in settings.local.json depends on what files actually exist on disk, which varies per machine. Each dev runs claudeignore sync to resolve rules against their local state — similar to how node_modules is local but package-lock.json is shared.

What happens for teammates who don’t have claudeignore?

The project hook (.claude/settings.json) runs a check script that detects if the binary is missing and shows an install reminder. No protection is enforced without the binary — the hook is advisory only.

Why is a restart required after sync?

The sandbox denyRead list is loaded once when Claude Code starts. After sync updates it, Bash-level protection only takes effect after restart. The guard hook protects Read/Write/Edit/Grep/Glob immediately — only Bash access requires the restart.

Does the guard block every access attempt?

The guard fails open by design: if it can’t determine the repo root, read settings, or parse input, it allows the request. This prevents the tool from ever locking a user out due to a bug or misconfiguration.

How do I know if I’m protected?

Run claudeignore status. It shows the current mode, sync state, number of denied entries, and whether hooks are installed. If everything says “up to date” and hooks show “user + project”, you’re fully protected.

Docker Sandboxes (sbx)

claudeignore works inside Docker sandboxes (sbx), but the sandbox configuration must be set correctly to ensure all protection layers are active.

Protection layers

Layer What it blocks Works without OS sandbox?
Sandbox denyRead All filesystem access (Bash, cat, scripts) No — requires sandbox.enabled: true
Guard hook Read, Write, Edit, Grep, NotebookEdit Yes — runs as long as hooks are invoked
Check hook Nothing (advisory) Yes

Without the OS sandbox, the guard hook is the only protection. It covers built-in tools but not Bash — meaning cat .env would bypass it.

Setup in sandbox

claudeignore install-hook generates a ready-to-use init script at .claude/claudeignore/init-sbx.sh. Run it once after creating the sandbox:

cd /path/to/your/workspace
sbx exec -u root <sandbox-name> bash $(pwd)/.claude/claudeignore/init-sbx.sh

The script installs claudeignore, syncs rules, installs hooks, and configures the Claude Code sandbox settings.

Enabling the OS sandbox

sbx launches Claude Code using ~/.claude/settings.json — not CLI flags. To get both bypass permissions (auto-approve tools) and filesystem protection (denyRead enforced), configure both in settings:

// ~/.claude/settings.json (inside the sandbox)
{
  "defaultMode": "bypassPermissions",
  "skipDangerousModePermissionPrompt": true,
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  },
  "hooks": { /* ... installed by claudeignore install-hook ... */ }
}

The key settings:

Without sandbox.enabled, denyRead entries are ignored and only the guard hook protects file access.

Verify inside the sandbox

claudeignore status
# Check: Sandbox denyRead ✔, Hooks ✔

# Test that Bash-level blocking works
cat project/.env          # Should fail with permission denied

If cat succeeds, the OS sandbox is not active — check that sandbox.enabled is true in ~/.claude/settings.json.

Support

claudeignore is free and open source, built and maintained by Claudeous — an independent developer creating tools for the Claude Code ecosystem, making AI-assisted development safer, one tool at a time.

If this tool is useful to you, consider supporting development:

Your sponsorship helps maintain claudeignore, respond to issues, and build more tools that make AI-assisted development safer and smoother.

Requirements

This site is open source. Improve this page.