Skip to content
Nx IDEDocs

Customization4 min read

.nexgileignore & Protected Files

Control what the agent can see and touch

Two complementary mechanisms control what the agent can touch. .nexgileignore controls what Nexgile Code can see — files matching it are kept out of reads and context entirely. The protected-files list controls what it can silently change — its own configuration files always require your explicit approval to modify, no matter how permissive your auto-approve settings are.

.nexgileignore: hide files from the agent

Section titled “.nexgileignore: hide files from the agent”

Create a file named .nexgileignore at your workspace root. It uses exactly the same pattern syntax as .gitignore:

# Secrets — the agent must never read these
.env
.env.*
*.pem
*.key
secrets/
config/credentials.json


# Build artifacts and generated code — noise, not signal
dist/
build/
coverage/
*.min.js
src/generated/


# Large data that would waste context
*.csv
*.parquet
data/
fixtures/large/


# Dependency lockfiles (huge, rarely useful to the agent)
pnpm-lock.yaml
package-lock.json

Changes take effect the moment you save — the file is watched.

What ignoring actually blocks

Section titled “What ignoring actually blocks”
  • File reads fail. read_file and friends return an error for ignored paths instead of content, and @ file mentions come back with a note that the file is ignored (see Context Mentions).
  • Listings mark them. By default ignored files still appear in file listings, flagged with a 🔒 symbol, so the agent knows they exist but can’t open them. A settings toggle can hide them from listings entirely.
  • Terminal shortcuts are blocked too. Commands whose purpose is reading a file — cat, head, tail, grep, sed, awk, less, more, and the PowerShell equivalents (Get-Content, type, Select-String, …) — are refused when they target an ignored path, closing the obvious loophole.
  • Symlinks don’t help. Paths are resolved to their real location before checking.
  • The ignore file guards itself. .nexgileignore is always ignored, so the agent can never read your ignore list’s contents (it is told the patterns exist so it can explain refusals).

What belongs in it

Section titled “What belongs in it”
  1. Secrets first. .env files, key material, credential stores. The agent sends file contents to your AI provider as context — ignored files never leave your machine. Making sure secrets are covered is part of the pre-task checklist in the Human-in-the-Loop Playbook.
  2. Build output and generated code. It’s derived, bulky, and misleads searches.
  3. Large data files. A single big CSV can burn a request’s worth of context.

Ignoring junk also sharpens codebase indexing and file searches — less noise in, better answers out.

Protected files: edits that always prompt

Section titled “Protected files: edits that always prompt”

Independently of .nexgileignore, Nexgile Code write-protects the files that configure the agent itself. In file listings they carry a 🛡️ marker, and any attempt to create, edit, or overwrite them raises an approval prompt even when file writes are auto-approved. The protected patterns:

Pattern What it covers
.nexgileignore The ignore list itself
.nexgilerules* .nexgilerules and every mode-specific variant
.nexgilemodes Custom mode definitions
.nexgile/** Everything under .nexgile/ — rules, commands, agents, skills, MCP config
AGENTS.md, AGENT.md Agent-rules files
.vscode/** Editor workspace configuration
*.code-workspace Workspace definition files

The logic is simple: these files steer the agent’s future behavior, so an agent silently rewriting them is exactly the failure mode you want surfaced. A request to “just approve” changes to protected files is listed as a red flag in the playbook.

The escape hatch is the auto-approve toggle alwaysAllowWriteProtected (Settings → Auto-Approve, off by default), which extends auto-approved writes to protected files. Leave it off unless you’re intentionally running an unattended job that must maintain its own rules — and even then, prefer keeping it off. See Auto-Approving Actions.

Ignored vs. protected at a glance

Section titled “Ignored vs. protected at a glance”
.nexgileignore Protected files
Controls Reading / visibility Writing / modification
Defined by You, per workspace Fixed pattern list
Effect Reads error; contents never enter context Edits always raise an approval prompt
Marker in listings 🔒 🛡️
Override Remove the pattern Approve the prompt, or alwaysAllowWriteProtected

The two compose: .nexgilerules is protected (edits prompt) but not ignored (the agent reads it constantly — that’s its job). Your .env should be ignored, which makes editing it moot.

Section titled “Related”