.aiignore¶

.aiignore files let you prevent specific files from ever being read or forwarded to an LLM by any aifred-tk tool. They follow the same gitignore pattern syntax, so existing knowledge of .gitignore transfers directly.

How it works¶

Before any tool reads a file it checks for .aiignore files starting from the target file's directory and walking up to the filesystem root — the same lookup strategy used by Git for .gitignore. Patterns from all .aiignore files found along that chain are evaluated, with deeper files taking precedence (consistent with gitignore semantics).

If the path matches any active pattern the tool returns an error immediately and the file contents are never read or sent to the LLM.

Caching¶

Parsed pattern specs are cached by file path and modification time. Changes to any .aiignore are picked up on the very next tool call without restarting the MCP server or CLI process.

Pattern syntax¶

Patterns follow the gitignore specification:

Pattern	Matches
`*.key`	Any file with the `.key` extension in any directory
`secrets/`	The `secrets/` directory and all its contents
`config/prod.yml`	That specific file relative to the `.aiignore` location
`!keep.log`	Negates a previous match — this file is not ignored
`**/private/`	Any `private/` directory at any depth

Example¶

# .aiignore
*.key
*.pem
*.env
secrets/
!secrets/example.env

Place this file in your project root (or any ancestor directory of the files you want to protect). Any tool that attempts to read id.key, prod.pem, secrets/db.env, etc. will be refused; secrets/example.env will still be accessible.

Scope¶

.aiignore applies to all plugins that perform file reads. The core toolkit provides built-in utilities that make it easy for any plugin to honour these rules.

Built-in tools that use this include:

File Analysis (analyze_file)
Data Query (query_json_data_file)
Markdown Frontmatter (get_markdown_frontmatter)

Custom plugins should use the aifred_tk.core.paths utilities to ensure they respect .aiignore consistently. See Safe File Access in the plugin development guide for details.

Error response¶

When a file is blocked by .aiignore the tool returns a standard error result:

{"status": "error", "message": "File is ignored by .aiignore: secrets/db.env"}