AGENTS.md is a persistent instruction file for a scope in the thread tree. Use it for rules that should apply to new turns in a workspace area, such as project conventions, preferred tools, review rules, naming conventions, safety constraints, or recurring context.
Unlike an uploaded attachment, AGENTS.md is not a file you attach to one message. It is stored by the gateway as thread-tree metadata and applied automatically when Pioneer builds prompt context for a thread.
Where it lives
There can be one AGENTS.md at the thread tree root and one AGENTS.md in each folder.
To create or edit the root file, right-click an empty area of the thread sidebar and choose Create AGENTS.md or Edit AGENTS.md.
To create or edit a folder file, right-click the folder and choose Create AGENTS.md or Edit AGENTS.md.
When a file exists or is open, Pioneer shows it as an AGENTS.md row in the sidebar tree. Click that row to open the editor in the main area, next to the sidebar, like a normal IDE file.
Inheritance
Threads use the nearest active AGENTS.md in their folder ancestry.
For example:
If a folder does not have its own active file, Pioneer keeps walking up to the parent folder and then to the root. You do not need to create an empty file in a folder just to inherit the root file.
Drafts and empty files
Only non-empty saved files are active. An empty saved AGENTS.md is a draft.
A draft can appear in the sidebar and can be edited or deleted, but it is not injected into the prompt. If a folder only has a draft, threads in that folder still inherit the nearest active parent file.
To remove a file, right-click the AGENTS.md row or the owning folder and choose Delete AGENTS.md.
Editing
The editor autosaves as you type. The status in the editor header shows whether the buffer is clean, dirty, saving, saved, or in conflict.
If another client changes the same file while you are editing, Pioneer detects the version conflict. You can reload the remote version or overwrite it with your local buffer.
What to put in AGENTS.md
Write instructions that should remain stable for the folder scope:
Good AGENTS.md files are specific and operational. Avoid long background essays. Put one-off rules in the message instead.
Explicit instructions in your current message override AGENTS.md. Use the file for defaults, and use the prompt for one-off exceptions.
Remote gateways
AGENTS.md belongs to the gateway workspace. If your desktop is connected to a remote gateway, creating or editing the file changes the remote gateway state. Other clients connected to the same gateway see the same sidebar file and receive change notifications.
Related pages
