agentignore Reference

.agentignore Reference

The .agentignore file tells codebase-vis which files and directories to exclude from analysis. It uses .gitignore-style glob patterns via the ignore npm package.

Pattern Syntax

Pattern	Meaning	Example
node_modules/	Ignore directory anywhere	node_modules/ in any subfolder
/build	Only match in root	Only ./build, not ./src/build
*.log	Ignore all .log files	debug.log, error.log
dist/**	Ignore dist and everything inside	dist/, dist/bundle.js
!important.js	Negation — don't ignore this file	Overrides a previous ignore
# comment	Comment line	# Auto-generated patterns
temp?	Single-character wildcard	temp1, temp2

Default Generated File

When you run codebase-vis init, it creates a .agentignore file tailored to your detected tech stack:

# Auto-generated by codebase-vis init
# https://github.com/Arham-Qureshi/codebase-vis#readme

# ==========================================
# Non-code file patterns
# ==========================================
*.txt
*.md
*.json
*.yaml
*.yml
*.xml
*.csv
*.sql
*.env
*ignore
*.config.*
docker-compose.*
Dockerfile*
Makefile*
*.toml
*.lock
*.patch
*.diff

# Images
*.png
*.jpg
*.jpeg
*.gif
*.ico
*.svg
*.webp
*.avif
*.bmp

# Fonts
*.woff
*.woff2
*.ttf
*.eot
*.otf

# Audio / Video
*.mp3
*.mp4
*.wav
*.mov
*.avi

# Compressed / Archives
*.zip
*.tar
*.gz
*.rar
*.7z

# Config / Planning
.agents/
.opencode/
graphify-out/

# ==========================================
# Stack-specific patterns (varies by project)
# ==========================================
node_modules/
dist/
build/
.next/
*.pyc
__pycache__/
venv/
target/

# ==========================================
# User custom patterns
# ==========================================

Stack-Specific Defaults

When codebase-vis init detects your tech stack, it includes the appropriate ignore patterns:

Stack	Added Patterns
Node / JS / TS	node_modules/, dist/, build/, .next/, .nuxt/, out/, .cache/, coverage/, package-lock.json
Python	venv/, .venv/, __pycache__/, *.pyc, *.pyo, .pytest_cache/, *.egg-info/, .eggs/, dist/, build/, .tox/, htmlcov/
C / C++	build/, cmake-build-*/, *.o, *.obj, *.exe, .a, .so, .dylib
Rust	target/, Cargo.lock
Go	vendor/
Java	target/, *.class, *.jar, .gradle/, build/
PHP	vendor/, composer.lock
Ruby	vendor/bundle/, .bundle/, Gemfile.lock

CLI --ignore Flag

In addition to .agentignore, you can pass runtime ignore patterns:

codebase-vis generate --ignore tests,fixtures
codebase-vis generate --ignore "*.spec.js,*.test.js"

These patterns are combined with .agentignore patterns before file discovery.

Evaluation Order

During file traversal (discoverFiles()):

1. Every entry's relative path is checked with ig.ignores(relPath)
2. If a directory is ignored, it's never entered (prevents wasted traversal)
3. Ignored files are excluded from the results
4. The --ignore flag patterns are merged into the same ignore instance

Tips

• Be specific — build/ is better than bu* to avoid unintended matches
• Use negation — !keep-this-file.js to override a broader ignore
• Edit freely — the file is yours to modify after init
• Regenerate — delete .agentignore and re-run init to regenerate from scratch