agentaccess.txt ConventionStatus: Draft 00 — for community discussion
Home: https://github.com/agentaccesstxt/agentaccess.txt
Author: Peter Seprus
Date: 2026-08-12
This document proposes agentaccess.txt, a plain-text file convention that lets a directory declare which agentic AI tools may operate on its contents, and on which paths. It is modeled on robots.txt: a per-agent, allow/disallow grammar that conforming tools consult before reading anything else in the directory tree. Like robots.txt, it is a cooperative signal, not an enforcement mechanism.
The name complements the established AGENTS.md convention: AGENTS.md tells agents how to work in a project; agentaccess.txt tells them whether they may.
Developers increasingly run several agentic AI tools side by side, and not every tool is appropriate for every project. A contractor may be permitted to use one assistant on a client’s repository but not others; a company may allow AI tooling in most repositories but not in a sensitive one; an individual may simply want a personal-notes directory left alone.
Today this intent can only be expressed per tool, each with its own mechanism: .cursorignore, .aiexclude / .geminiignore, .aiignore, .codeiumignore, tool-specific permission settings, or server-side configuration. Two problems follow:
The problem is sharpest for IDE-embedded agents. A CLI agent is invoked deliberately, in a repository the user chose; an AI feature built into an editor activates simply by opening a folder, and may begin indexing before the user has expressed any intent at all. Editors do offer per-workspace controls (for example VS Code’s chat.disableAIFeatures setting, which users can set globally and re-enable per workspace), but these are again tool-specific, and the burden of remembering falls on every user, for every tool, on every machine. A committed workspace setting is in effect a directory-borne restriction marker for one editor — evidence of the need this convention generalizes.
A single well-known file, placed once in the restricted directory, lets the restriction follow the directory rather than the tool: declared by the directory’s owner, once, for every conforming agent on any machine.
Nor is the concern hypothetical. 2025–2026 produced a steady stream of documented attacks in which agentic tools were steered into reading, exfiltrating, or destroying files their users never intended to expose. Appendix A surveys these threat classes and states, for each, how much this convention would change.
This is not a security boundary. A tool that does not implement the convention, or a user who deletes the file, is unrestricted. agentaccess.txt occupies the same trust position as robots.txt: it works because reputable vendors have strong incentives to honor clearly declared intent, not because it can stop a determined actor. Environments that require enforcement should use tool-native managed policy, OS access controls, or sandboxing; those mechanisms are out of scope here and always take precedence in the restrictive direction.
This document also does not define instructions or context for agents (see AGENTS.md), nor within-repository content exclusion for tools that are otherwise permitted (see the emerging .agentignore effort, §8), nor web-origin capability declaration (see the separate web-scope agents.txt effort, §8).
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.
Agentic AI tool (agent): software that autonomously or semi-autonomously reads, indexes, modifies, or transmits files on behalf of an AI model — coding assistants, CLI agents, IDE integrations, background indexers.
The file is named agentaccess.txt (lowercase) and applies to the directory that contains it and, recursively, to everything beneath it. It is a visible file, not a dotfile: a restriction marker should be noticeable to humans browsing the directory, not only to the tools it addresses.
Before performing any covered operation (§7) under a directory, a conforming agent MUST look for agentaccess.txt in that directory and each ancestor directory. The nearest agentaccess.txt file governs; files in higher ancestors are not merged. If no file is found, the agent is unrestricted by this convention (status quo).
This check is a pre-flight requirement: the agent MUST evaluate the file before reading, indexing, or listing any other content in the governed tree. For IDE-embedded agents, opening a folder or workspace is itself a covered trigger — the check happens at open time, before any background indexing, not at the first user interaction with the AI feature. Reading agentaccess.txt itself is always permitted.
The grammar is deliberately that of robots.txt, so existing parsers transfer.
# begins a comment; comments and blank lines are ignored and carry no structural meaning — grouping comes from the directives alone.Agent: lines followed by zero or more rule lines, and applies to every agent it names. A group ends where the next begins: at the first Agent: line that follows a rule line. Blank lines do not separate groups, and consecutive Agent: lines with no rules between them head the same group — so a rule-less group (§6) is syntactically possible only as the last group in the file. To permit an agent everything unambiguously, write Allow: /.Allow: <pattern> or Disallow: <pattern>.agentaccess.txt, beginning with /. Matching follows robots.txt rules (RFC 9309): prefix match, with * matching any character sequence and $ anchoring the end. Matching operates on canonical paths — . and .. segments are resolved before comparison, as are symlinks (§9) — so a pattern containing .. can never match, and no rule can reach outside the governed tree (§4).# agentaccess.txt — this repository is restricted.
# Default: no agentic AI tools.
Agent: *
Disallow: /
# Claude Code may work in docs and public source, nothing else.
Agent: anthropic/claude-code
Allow: /docs/
Allow: /src/public/
Disallow: /
# Gemini CLI is fully permitted.
Agent: google/gemini-cli
Allow: /
The two-line minimal form covers the most common case:
Agent: *
Disallow: /
* group. If there is no * group either, the agent MUST treat the entire tree as disallowed — the file’s presence signals intent to restrict, so unmatched agents fail closed.Allow and a Disallow match with equal specificity, Allow wins. If no rule matches, the path is allowed.Agent: lines and no rules allows everything for the named agents. Per §5, such a group can exist only at the end of the file; prefer an explicit Allow: /.Identifiers are lowercase tokens of the form vendor/product, matched case-insensitively as whole tokens — never as executable names or paths, which are platform-specific. Examples: anthropic/claude-code, openai/codex, google/gemini-cli, cursor/cursor, jetbrains/junie.
Each agent has exactly one canonical identifier, published by its vendor and recorded in the public registry file maintained in this repository. An agent MUST match only its own identifier and *.
Authors MAY write the product part alone (Agent: claude-code); agents SHOULD match this against their product token when the vendor prefix is absent.
A conforming agent, having selected its rules per §6:
Disallow rule, because it authorizes the tool without naming the restriction and is therefore not the deliberate override defined below. When such a grant conflicts with this policy, the restriction prevails, and the agent SHOULD inform the user that its granted permission was narrowed by agentaccess.txt;agentaccess.txt restricted its access, without revealing disallowed content;Vendors SHOULD document their identifier and their support for this convention.
| Mechanism | Question it answers | Relationship |
|---|---|---|
.gitignore |
what is not part of the repository | unrelated; syntax inspiration only |
.agentignore, .aiignore, .cursorignore, .aiexclude, … |
which paths an otherwise-permitted tool must skip | complementary; applied after agentaccess.txt grants access |
AGENTS.md |
how permitted agents should behave | complementary; only consulted where access is allowed |
web-scope agents.txt (agents-txt.com) |
what agent protocols and capabilities a website announces at its origin | unrelated; different domain (web origin vs. local filesystem), different grammar |
| Tool-native managed policy, OS ACLs, sandboxes | enforcement | out of scope; always take precedence in the restrictive direction |
robots.txt / IETF AIPREF |
web crawling and AI-usage preferences for published content | same trust model, different domain (web vs. local filesystem) |
agentaccess.txt deliberately reuses the robots.txt grammar rather than the .gitignore grammar so that the per-agent group structure comes for free and the file cannot be confused with a path-exclusion list. The name is deliberately distinct from both AGENTS.md (a different role: onboarding document vs. access policy) and the web-scope agents.txt (a different domain: web origins vs. local filesystems) — a repository deployed as a static site would otherwise serve its local policy at the URL where web agents expect the other spec’s grammar.
Naming note.
agents.txtwas this proposal’s original working name, chosen for symmetry withrobots.txtandAGENTS.md. It was abandoned because the name is already in use and contested on the web — most visibly the agents-txt.com specification, which despite the shared name does nearly the opposite job: it is a discovery file through which a website advertises what agents can do at its origin (payment protocols, authorization schemes, integration endpoints such as MCP servers), whereas this convention is an access policy through which a directory owner declares what agents may do in a filesystem tree. Reusing the name would have created exactly the static-site collision described above and invited perpetual confusion between two files of opposite posture — one opens doors, the other closes them.agentaccess.txtsays what the file is at the cost of one extra word.
Compliance is voluntary (§2). Further notes:
robots.txt failure, where a disallow list doubles as a target list. The filesystem version is weaker than it first appears: unlike a public URL, this file is readable only by someone who already has access to the directory, and such a reader can already enumerate subdirectory names — the marginal disclosure is prioritization, not existence. Still, authors who want to name nothing at all SHOULD place the file inside the sensitive directory with a bare Disallow: /, rather than naming the subtree from a parent; nearest-file discovery (§4) makes the two equivalent in effect.agentaccess.txt are security-relevant and SHOULD receive the same review scrutiny as changes to CODEOWNERS or CI configuration — an attacker may loosen rules to expose restricted content, or tighten them to hide malicious code from AI-assisted review (§11).agentaccess.txt purely as access policy. Its contents are not instructions to the model, and MUST NOT be injected into model context as natural language, which would create a prompt-injection surface.A conforming agent SHOULD evaluate this file in deterministic tool code, outside the model: the harness parses the policy and rejects disallowed operations before their results can enter model context. Enforced this way, restrictions hold even when the model itself is manipulated — including prompt injection delivered through tool results or tool descriptions, and instructions fragmented across several such channels, which empirically defeat model-level refusals. A manipulated model can attempt a disallowed operation but cannot execute it. This robustness does not extend to compromised or non-conforming processes (a malicious local plugin or MCP server reading the filesystem directly); that boundary requires OS-level enforcement (§2). Denial messages returned to the model SHOULD be fixed strings that reveal neither content nor policy text, and paths SHOULD be canonicalized — symlinks resolved — before the policy check.
This convention governs what may enter model context, not what may leave it. It cannot prevent exfiltration of content the agent is permitted to read; egress control is a separate problem and out of scope.
Kept out of version 1 intentionally: operation classes (read-only vs. write vs. network), expiry dates, cryptographic attestation of compliance, and an include mechanism. The unknown-directive rule (§5) leaves room for these.
/.env matches /.env.local while gitignore readers expect it to name exactly one file, and Disallow: /notes silently covers /notes-public/. Gitignore-style component matching would fit developer muscle memory, but its native evaluation is order-dependent (last match wins), which conflicts with this draft’s order-independent longest-match rule — and a hybrid (robots.txt groups, gitignore patterns, longest-match precedence) must first define specificity for patterns that don’t compare by length./?AGENTS.md and this file?This appendix is motivational, not normative. It surveys documented classes of attack and overreach involving agentic AI tools and states, for each, how much a harness-enforced agentaccess.txt (§9) changes. All degrees assume a conforming, uncompromised agent; nothing here overrides §2.
Malicious instructions arrive inside material the agent legitimately processes — a README, an issue, a web page, a tool result — and steer it into reading and exfiltrating sensitive files. Documented examples: the Gemini CLI hijack (Tracebit, 2025), where instructions hidden in a README combined with an allow-list parsing flaw yielded silent data exfiltration; and GhostSplice (ASSET Research Group, 2026), where instructions fragmented across MCP tool descriptions and tool results raised model compliance from 42% to 82% across eleven tested models — no fragment looking malicious on its own.
Degree: strong, for restricted trees. Enforcement never consults the model’s judgment (§9), so it holds no matter how thoroughly the model is steered: disallowed content can be neither read nor exfiltrated, because it never enters context. Content the policy allows remains exfiltratable — egress control is out of scope (§9).
Instruction files the agent trusts are themselves the injection vector. Documented example: the Rules File Backdoor (Pillar Security, 2025) — malicious instructions hidden in Cursor and GitHub Copilot rules files behind zero-width and bidirectional Unicode characters, invisible in review; both vendors declined to treat it as a vulnerability, placing the burden on users.
Degree: partial, plus structural immunity. Once the agent is steered the situation reduces to A.1: restricted trees stay unreachable. Structurally, agentaccess.txt cannot join this attack class itself — it is parsed as policy and never enters model context as language (§9), so there is nothing to hide instructions in.
The tool channel itself is hostile: instructions ride in tool descriptions or results, or the agent is steered into configuration writes that escalate to code execution. Documented examples: CurXecute (CVE-2025-54135, Aim Security, 2025), where prompt injection made Cursor write .cursor/mcp.json and auto-execute the attacker’s server; MCPoison (CVE-2025-54136, Check Point, 2025), where an approved MCP configuration could be silently swapped afterward; and GhostSplice (A.1).
Degree: partial. Covered operations include writes, so a policy disallowing the configuration path would have blocked a conforming agent from the CurXecute write. Model-steering variants are covered as in A.1. A malicious local process reading or writing disk on its own authority is beyond any cooperative convention — that boundary requires OS-level enforcement (§2, §9).
No attacker at all: an IDE-embedded AI feature activates and begins indexing simply because a folder was opened, before the user expresses any intent (§1).
Degree: full, for conforming editors. The pre-flight check binds at open time, before any background indexing (§4). This is the convention’s home turf.
The agent itself ships hostile. Documented example: the Amazon Q Developer VS Code extension v1.84.0 (July 2025), where an attacker with an inappropriately scoped repository token committed a prompt instructing the agent to “clean a system to a near-factory state” — deleting home directories and cloud resources — into a release installed by nearly a million users. A syntax error prevented execution.
Degree: none to marginal. A compromised tool is non-conforming by definition; no cooperative signal restrains hostile code. (In the narrow variant where honest tool code executes a poisoned prompt, harness enforcement would still refuse restricted trees — but the general defense here is supply-chain hygiene and OS enforcement, §2.)
The tool intends confinement but implements it wrong. Documented example: the Claude Code path-restriction bypass (CVE-2025-54794, Cymulate, 2025), where prefix matching instead of canonical path comparison let /home/user/project-secrets pass as inside /home/user/project.
Degree: none directly. The convention inherits the implementation quality of the tools that honor it. This class is why §9 tells implementations to resolve symlinks and canonicalize paths before the policy check, and why a shared conformance test corpus is worth more to this convention than additional prose.
Read as a whole: the convention is at its strongest precisely where the model is the weak link (A.1–A.4) — because it removes the model from the enforcement path — and it is honestly worth nothing where the tool itself is hostile or broken (A.5–A.6). That is the same asymmetry robots.txt has lived with for thirty years.