agentignore

RFC-0001: AgentIgnore

Status: Draft Author: Garo Karh Bet Version: 0.1

Abstract

This document proposes AgentIgnore, a vendor-neutral standard for excluding files and directories from AI coding agents.

AgentIgnore introduces a dedicated .agentignore file that allows developers to explicitly control which files and directories should be excluded from passive agent discovery, indexing, retrieval, embedding generation, context construction, and automated modification.

The goal is to provide a consistent mechanism across agentic coding tools while reducing token consumption, improving retrieval quality, reducing context pollution, and minimizing accidental exposure of sensitive information.

Motivation

AI coding tools currently implement file visibility controls inconsistently.

Some tools respect existing ignore mechanisms, some introduce proprietary solutions, and others provide no dedicated exclusion mechanism at all.

As a result:

• developers must learn tool-specific behaviors
• agents may process irrelevant files
• retrieval quality may degrade due to context pollution
• sensitive information may be unnecessarily exposed
• behavior varies across agent ecosystems

A dedicated standard enables interoperability and predictable behavior.

Goals

The AgentIgnore standard aims to:

• define a dedicated .agentignore file
• provide a vendor-neutral exclusion mechanism
• reduce unnecessary token consumption
• improve retrieval relevance
• reduce context pollution
• reduce accidental exposure of sensitive information
• support familiar ignore-file semantics
• remain simple to implement

Non-Goals

AgentIgnore does not attempt to:

• define agent instructions
• replace AGENTS.md
• replace CLAUDE.md
• replace tool-specific configuration
• provide security guarantees
• replace version control systems
• define agent workflows
• define model behavior
• require changes to large language models

Definitions

Agent

An agent is a software system that can analyze, retrieve, summarize, modify, or otherwise interact with project files on behalf of a user.

Agent Visibility

Agent visibility describes whether a file or directory may be discovered, indexed, retrieved, embedded, summarized, included in context, or modified by an AI coding agent.

Passive Access

Passive access occurs when an agent independently discovers, searches, indexes, retrieves, summarizes, or modifies files without the user explicitly naming or referencing a specific file or path.

Explicit User-Directed Access

Explicit user-directed access occurs when the user directly names, references, or requests a specific ignored file or directory.

Overview

AgentIgnore introduces a file named:

.agentignore

located at the root of a project.

The file contains patterns describing files and directories that should be excluded from passive agent visibility.

Example:

# .agentignore

# Dependencies and generated output
node_modules/
dist/
build/
coverage/

# Tool and cache directories
.cache/
.tmp/

# Noisy runtime artifacts
*.log

# Legacy or archived code not useful for normal agent context
legacy/
archive/

Pattern Semantics

AgentIgnore v0.1 uses .gitignore -style pattern syntax as its compatibility target.

The goal is familiarity and ease of implementation, not the invention of a new pattern language.

At minimum, implementations SHOULD support:

• blank lines
• comments beginning with #
• file patterns such as *.log
• directory patterns such as dist/
• root-relative patterns such as /build/
• negation patterns beginning with !

Example:

# Ignore generated logs
*.log

# But allow checked-in log fixtures
!fixtures/example.log

# Ignore build output
dist/
build/

Implementations SHOULD document any deviations from .gitignore behavior.

Precise edge-case behavior, including escaping rules, platform-specific path separators, and advanced glob behavior, SHOULD be defined by the formal specification.

Root-Level Behavior

AgentIgnore v0.1 standardizes only a root-level .agentignore file.

Implementations MUST recognize a .agentignore file located at the project root.

Nested .agentignore files are not part of this version of the standard.

Tools MAY experiment with nested behavior, but such behavior SHOULD be documented as tool-specific until standardized in a future version.

Expected Agent Behavior

When an agent encounters a .agentignore file, files and directories matching its patterns SHOULD be excluded from passive agent operations.

Passive agent operations include:

• automatic file discovery
• indexing
• retrieval
• embedding generation
• context construction
• automatic summarization
• automated modification

This means ignored files SHOULD NOT be selected, analyzed, summarized, embedded, included in context, or modified by the agent unless explicit user override behavior applies.

User Override Behavior

AgentIgnore distinguishes between passive access and explicit user-directed access.

Passive Access

Passive access occurs when an agent independently searches, indexes, retrieves, summarizes, or modifies files without the user explicitly naming them.

Files matched by .agentignore SHOULD be excluded from passive access.

Example:

User: Fix the login bug.

If legacy-auth/ is listed in .agentignore , the agent SHOULD NOT automatically inspect or modify files inside legacy-auth/ .

Explicit User-Directed Access

Explicit user-directed access occurs when the user directly names, references, or requests an ignored file or directory.

Example:

User: Open legacy-auth/session.ts and explain what it does.

In this case, tools MAY allow access to the ignored file because the user explicitly requested it.

However, tools SHOULD make this behavior visible to the user, for example by warning:

legacy-auth/session.ts is listed in .agentignore. Continue?

AgentIgnore v0.1 recommends that tools allow explicit user override, but does not require a specific user interface.

Modification Semantics

Ignored files SHOULD NOT be modified automatically.

If a file is matched by .agentignore , an agent SHOULD NOT edit, delete, rename, or generate changes for that file as part of an automatic task.

However, if the user explicitly requests modification of an ignored file, tools MAY allow the modification after making the ignored status clear.

Example:

User: Modify legacy/old-parser.ts.

If legacy/old-parser.ts is ignored, the tool MAY proceed only after treating the request as explicit user-directed access.

Relationship to .gitignore

AgentIgnore and Git serve different purposes.

Git determines what should be version-controlled.

AgentIgnore determines what should be visible to AI coding agents.

These concerns overlap, but they are not identical.

Some files should be committed to Git while excluded from agent context, such as internal documentation, compliance notes, or customer-specific configuration examples.

Other files may be ignored by Git but still useful for agents, such as generated schema files or local build artifacts needed to understand a project.

Therefore, .gitignore is not a reliable substitute for .agentignore .

Relationship to Tool-Specific Configuration

AgentIgnore is intended to complement tool-specific configuration, not replace it.

Tools may continue to provide their own configuration files, settings, or permission systems.

If a tool supports both .agentignore and tool-specific ignore rules, the tool SHOULD document precedence clearly.

A recommended default is:

1. hard security restrictions imposed by the tool
2. explicit, visible user permissions or denials for a specific ignored path
3. .agentignore
4. tool-specific convenience defaults

This ordering does not mean ordinary prompts bypass .agentignore . User override SHOULD apply only when the user directly names, references, or requests an ignored path and the tool makes the ignored status visible.

Exact precedence MAY vary between implementations.

Security Considerations

AgentIgnore is intended to reduce accidental exposure of files to AI agents.

However, AgentIgnore is not a security boundary.

It MUST NOT be relied upon as protection against malicious software, unauthorized users, compromised tools, or intentional data exfiltration.

Sensitive files SHOULD still be protected using proper access control, encryption, secret management, and repository hygiene.

Tools implementing AgentIgnore SHOULD avoid presenting ignored files to language models during passive operations.

Compatibility Requirements

A conforming AgentIgnore v0.1 implementation SHOULD:

• recognize a root-level .agentignore file
• support common .gitignore-style patterns
• exclude matching files from passive agent operations
• distinguish passive access from explicit user-directed access
• document unsupported pattern features
• document precedence with other ignore mechanisms

Implementations MAY use any internal mechanism to achieve compliance with this specification.

Future Work

Future versions may define:

• nested .agentignore behavior
• full .gitignore compatibility requirements
• relationship with .gitignore
• compliance test suites
• reference implementations
• language-specific parser libraries
• standard warning behavior for explicit access
• machine-readable capability declarations
• interoperability guidelines for major agentic coding tools

Visibility Levels

AgentIgnore v0.1 treats ignored files as excluded from passive agent operations while allowing implementations to support explicit user-directed access.

Future versions may define standardized visibility levels, including:

• hidden from discovery
• hidden from indexing
• hidden from retrieval
• hidden from embedding generation
• hidden from context construction
• hidden from automated modification
• hidden from all agent access

Such visibility levels could allow developers to express different intentions, ranging from context optimization to strict agent exclusion.

The syntax and semantics of visibility levels are intentionally left undefined in AgentIgnore v0.1 and may be addressed by future RFCs.

This site is open source. Improve this page.