Claude Code .claudeignore: exclude files and directories from AI context

When you run Claude Code on a large project, it reads your codebase to understand context. But not everything in your repo needs to go into that context — and some things really shouldn't.

That's where .claudeignore comes in.

What is .claudeignore?

.claudeignore works exactly like .gitignore — it tells Claude Code which files and directories to skip when building its context window.

Create the file at your project root:

touch .claudeignore

Syntax

Same as .gitignore:

# Ignore node_modules
node_modules/

# Ignore build output
dist/
build/
.next/

# Ignore large data files
*.csv
*.parquet
data/

# Ignore secrets (belt + suspenders)
.env
.env.*
secrets/

# Ignore generated files
coverage/
*.log

# Ignore vendor dependencies
vendor/
__pycache__/
*.pyc

Why this matters

1. Protect your context window

Claude's context window is finite. If your project includes node_modules/ (150,000+ files in some projects), Claude wastes tokens reading package internals instead of your actual code.

Before .claudeignore: Claude reads 200MB of vendor code
After .claudeignore: Claude reads your 50 source files

2. Keep secrets out

You shouldn't paste .env files into any AI tool. .claudeignore adds a layer of protection:

.env
.env.local
.env.production
config/secrets.yml
*.pem
*.key

This doesn't replace secret scanning tools — but it reduces accident surface area.

3. Improve response quality

When Claude can't see irrelevant files, it focuses on what matters. Less noise = better answers.

Common noise sources to exclude:

• *.min.js — minified bundles
• *.map — source maps
• fixtures/ — large test fixtures
• migrations/ — unless you're working on DB schema
• __mocks__/ — unless you're debugging tests

The include override: !pattern

Just like .gitignore, you can use ! to re-include something:

# Ignore all markdown
*.md

# But keep the README
!README.md

Useful when you want Claude to see your README.md and CLAUDE.md but not a /docs folder with 200 pages.

Combining .claudeignore with CLAUDE.md

.claudeignore controls what Claude cannot see. CLAUDE.md controls what Claude knows. Use both:

# CLAUDE.md tells Claude:
- This is a Node.js monorepo
- packages/api is the main service
- packages/web is Next.js
- Don't touch packages/legacy

# .claudeignore excludes:
packages/legacy/
node_modules/
dist/

Result: Claude understands your architecture without reading thousands of irrelevant files.

Project-specific example: monorepo

# Root .claudeignore for a monorepo
node_modules/
**/node_modules/
dist/
**/dist/
.next/
**/.next/

# Ignore packages you're not working on today
packages/mobile/
packages/admin/

# Generated
*.generated.ts
*.generated.graphql

# Data files
imports/
exports/
uploads/

When you're working on the API package only, having Claude ignore packages/mobile/ keeps the session tight.

Rate limits and context size

Here's a practical benefit that surprises people: smaller context = fewer tokens = fewer rate limit hits.

If you're using Claude Code heavily and hitting the built-in rate limits, optimizing your .claudeignore is a free way to stretch your allowance further.

But if you're hitting limits frequently, a better solution is pointing ANTHROPIC_BASE_URL at a proxy like SimplyLouie that doesn't have the same per-session ceiling. The .claudeignore optimization still helps — less context means faster, cheaper sessions either way.

Quick setup checklist

# Create the file
touch .claudeignore

# Start with the basics
cat > .claudeignore << 'EOF'
node_modules/
dist/
build/
.env
.env.*
coverage/
*.log
EOF

# Test it — start Claude Code and check what it reads
claude --print 'What files can you see in this project?'

Iterate from there. Add patterns as you find Claude reading things it doesn't need.

Summary

• .claudeignore uses .gitignore syntax
• Exclude node_modules/, dist/, secrets, large data files by default
• Combine with CLAUDE.md for full context control
• Smaller context = fewer rate limit hits + better response quality
• Use !pattern overrides to re-include specific files

Your .claudeignore is worth 5 minutes to set up. The improvement to session quality is immediate.