readignore

.gitignore for AI coding agents — declare files your AI agent must not read.

This is the npm wrapper package for readignore — a Go CLI that adapts a single .readignore (gitignore syntax) into each AI coding agent's strongest native defense mechanism.

The npm package bundles prebuilt Go binaries for all platforms (linux/darwin × x64/arm64 + windows-x64) — no postinstall download, no Go toolchain, works regardless of npm's allow-scripts setting.

Why

AI coding agents (Claude Code, Cursor, Codex, opencode, kilo code, …) can read any file in your repo at runtime — including secrets like .env, *.pem, id_rsa, credentials.json.

• .gitignore only stops git from committing; the agent still reads the file.
• Claude Code's permissions.deny: Read(.env) only blocks the Read tool — agents bypass it with Grep, Glob, or Bash (grep . .env works).

readignore closes that gap with one .readignore that gets adapted into each agent's native defense mechanism — at the strongest level that agent actually supports.

Install

npm i -g readignore        # global install
# or run once without installing:
npx readignore --version

Requires Node 18+ and one of: linux (x64/arm64), macOS (x64/arm64), Windows (x64).

Quickstart

cd your-repo
readignore init                      # generates .readignore with common secret patterns
readignore install claude-code       # single agent
readignore install --all             # every adapter detected in this repo
readignore check                     # validate .readignore + report install status

init refuses to overwrite an existing .readignore unless you pass --force.

Commands

readignore init [--force]                  # generate a .readignore template
readignore adapters                        # list adapters + strength + detection status
readignore generate <adapter>              # dry-run: print what an adapter would generate
readignore install <adapter> [--force]     # write an adapter's output to disk
readignore install --all                   # all adapters detected here
readignore check                           # validate syntax + report install status

If a target file already exists, install skips it (and tells you to merge manually) unless you pass --force.

Supported agents

readignore adapts .readignore into each agent's strongest real mechanism. Strength tiers are honest, not marketing:

| Agent | Strength | Mechanism | Status | |---|---|---|---| | Claude Code | hard | PreToolUse hook — blocks the tool call before it runs (Read, Grep, Glob, Bash). | ✅ shipped | | codex CLI | hard | .codex/hooks.json Claude-style PreToolUse hook (bash, calls readignore match). | ✅ shipped | | pi | hard | .pi/extensions/readignore.ts TS extension that overrides the built-in read tool. | ✅ shipped | | opencode | config | permission.read deny/allow globs in opencode.json. | ✅ shipped | | Cursor | soft | .cursor/rules natural-language advisory (model may comply). | 🗺 roadmap | | kilo code | — | mechanism TBD. | 🗺 roadmap |

.readignore syntax

100% gitignore-compatible. Zero learning curve:

# readignore — files this repo's AI agent must not read

# Secrets & keys
.env
.env.*
!.env.example            # ! un-ignores (negation): allow the template through
*.pem
*.key

# SSH / cloud credentials
**/id_rsa
.aws/
.gcp/

# Sensitive directories
secrets/
credentials.json

# Trailing / anchors to directories only
build/

Supported: *, **, ?, [abc] character classes, ! negation (last-match-wins), trailing / for directory anchoring, # comments.

Full documentation

For the capability matrix, per-adapter details, negation caveats, and design notes, see the full README on GitHub.

Wrapper package notes

• This npm package bundles all 5 platform binaries (linux/darwin × x64/arm64 + windows-x64, ~7MB). The right one is selected at runtime by bin.js based on your platform — no postinstall, no download, no allow-scripts dependency.
• To install without npm, see alternative install methods (go install, direct binary download, Homebrew, curl | sh).

License

MIT © 2026 0xByteBard404