Update

Update .claudeignore

Modify an existing .claudeignore file based on the user's request or a fresh analysis of the repository.

Step 1: Read the current file

Read .claudeignore from the project root.

If the file does not exist, tell the user:

"No .claudeignore found in this project. Use claudeignore:create to generate one from scratch."

Do not fall through to creation logic.

Step 2: Determine what changed

There are three update modes:

Mode A: Explicit request

The user asks to add or remove specific entries (e.g., "add data/", "remove debug/", "stop ignoring reports/").

• Parse the request into add/remove operations.
• Skip the scan — the user knows what they want.

Mode B: Drift check

The user asks to "review" or "refresh" the claudeignore, or simply invokes claudeignore:update without specifics.

1. Scan the repository (same as create Step 1).
2. Compare the scan results against the current .claudeignore:
   • Missing entries: directories that should be ignored but aren't. Apply the heuristic: large, generated, noisy, secret, or not useful for day-to-day coding decisions → should be ignored.
   • Missing secrets: check for .env, .env.*, *.pem, *.key, or credential files that aren't ignored yet.
   • Stale entries: directories in .claudeignore that no longer exist in the repo.
   • Questionable entries: source directories, manifests (pyproject.toml, package.json), or key docs (README.md, CLAUDE.md) that are being ignored — likely a mistake.
   • Over-ignored: files Claude needs to understand the project structure (core config, tooling config) that are currently ignored.
3. Present findings as a diff.

Mode C: From arguments

If arguments are provided, parse them as directives:

• Bare directory names → add them (e.g., update data/ logs/)
• Prefixed with - or ! → remove them (e.g., update -debug/ !reports/)
• --refresh or --check → trigger drift check (Mode B)

Step 3: Present the changes

Show the user what will change using a before/after or diff format:

Changes to .claudeignore:

+ data/              # add — 450 MB data files, not source code
+ logs/              # add — log output, not useful for context
- debug/             # remove — user wants debug scripts indexed
~ stubs/ → stubs/py  # modify — narrow the scope

Ask:

"Here are the proposed changes. Apply them? (yes / edit / no)"

Step 4: Apply changes

After confirmation:

1. Read the current .claudeignore content.
2. Apply the additions, removals, and modifications.
3. Maintain the category comment structure — add new entries under the appropriate category header, or create a new category if needed.
4. Remove empty category sections (header with no entries below it).
5. Write the updated file.

Step 5: Report

After writing, report:

• Summary of changes (N added, N removed, N modified)
• Any stale entries that were cleaned up
• Reminder about on-demand reading of ignored paths

Constraints

• Never remove entries without confirmation. Even stale entries might be intentional (anticipating future directories).
• Preserve existing comments and structure. Don't reformat the entire file just to add one entry.
• Warn on source directory ignores. If the user asks to ignore src/, lib/, tests/, or scripts/, flag it:

  "Warning: src/ contains source code. Ignoring it means I won't see your application code. Are you sure?"

• Warn on manifest/config ignores. If the user asks to ignore pyproject.toml, package.json, tsconfig.json, or similar, flag it:

  "Warning: this is a project manifest. Ignoring it means I won't understand your project's dependencies and tooling. Are you sure?"

• Always recommend secrets. During drift checks, if .env, .env.*, *.pem, *.key, or credential files exist and aren't ignored, flag them as recommended additions — defense in depth against sensitive content entering context.
• Validate entries exist. When adding directories, check that they actually exist. If they don't, warn the user but still add if they confirm — they may be anticipating future directories.
• Read-only on error. If the file can't be parsed or written, report the error and stop. Do not silently create a new file.

Argument handling

Arguments are parsed as directives (see Mode C above). If no arguments are provided and the user's message doesn't specify what to change, default to Mode B (drift check).