agentleFS
fightingforsidewalkfightingforsidewalk/vault-relay/AGENTS.md

vault-relay

AGENTS.md2 starsChanged 41 days agoMITView on GitHub

These instructions let any AI agent take part in a vault-relay folder: Codex, Copilot, Cursor, Gemini or any other agent that can read and write files in the folder and run python3. Copy this file into the folder your agent works in (or add it to the agent's existing instructions). Many agents read a file called AGENTS.md there on their own; for the rest, tell the agent to read it. Claude users get the same routine as a skill: install…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

4 rules. About 1 is common, 1 is distinctive, and 2 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every relay edit goes through the tool, <path>/relay.py, run with python3.

    line 19
  2. Very specific:

    If the README names you as Owner:, run relay prune --me <code> --dry-run, then relay prune --me <code>.

    line 31
  3. Distinctive:

    Every message aims at getting something done.

    line 54
  4. Common:

    Never put secrets, credentials, keys, recovery codes or personal data in a message.

    line 56

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Relay instructions for AI agents

These instructions let any AI agent take part in a vault-relay folder: Codex, Copilot, Cursor, Gemini or any other agent that can read and write files in the folder and run python3. Copy this file into the folder your agent works in (or add it to the agent's existing instructions). Many agents read a file called AGENTS.md there on their own; for the rest, tell the agent to read it.

Claude users get the same routine as a skill: install the vault-relay plugin instead. SKILL.md in this repository is that routine, and an agent that reads the skill format can load it directly.

Your relay settings

The agent needs one line, either here or in its own instructions:

Relay: sender code <code>; RELAY folder <path>.

<code> is this agent's sender code, as listed in the relay folder's README.md. <path> is the relay folder. If the line is missing or still has the placeholders, give the person the line to fill in and stop.

The one rule about edits

Every relay edit goes through the tool, <path>/relay.py, run with python3. Never create, edit, move or delete a relay message, receipt or README by hand or with a script of your own. If you can't run commands in that folder, say so and stop.

Below, relay means python3 <path>/relay.py, and every command takes --relay <path>.

What the person can say

"relay for you" (said to the chat that should pick up its messages)

  1. relay list --me <code> --full. It shows messages waiting for you as ACTION, then as FYI, each with a seen hash.
  2. A NOTE about the protocol version, or a STOP line for any file, goes in your reply to the person. Don't act on a STOP file.
  3. FYI messages: read them. Don't reply because of one, and don't edit or move one.
  4. Each ACTION message, oldest first: do or decide what it asks and record the outcome in your own notes or files, then relay consume <id> --me <code> --seen <hash> --receipt "<what was done; files touched>". If consume says the message changed since you read it, run list again, deal with what was added, then consume with the new hash. If you can't finish one, leave it waiting and say what blocks it.
  5. If the README names you as Owner:, run relay prune --me <code> --dry-run, then relay prune --me <code>. Never prune otherwise.
  6. End with one line, for example "Relay: consumed 2026-10-06-claude-to-codex-a; read 1 FYI", or "Relay: nothing for <code>".

Sending a message (no special phrase needed)

When the person asks for a message to go to another chat or agent, in any words ("send this to the Marcel chat", "relay this to <code>"), or says yes to a message you drafted, post it straight away. Don't wait for, or ask for, any further phrase. Turn what they asked for into one message: a one-line "done when" and a body with everything the recipient needs to finish in one pass, asks numbered at the end. If what done looks like isn't clear, ask once before posting. Then:

relay post --relay <path> --from <your code> --to <code> --done-when "<one line>" [--re <id you are answering>] --body - <<'BODY'
<the message>
BODY

If it says you already have a message waiting for that recipient, run the same command with --add to add to it. If it refuses a third message on one thread, don't send it: put the question to the person as a decision with options.

Once it's posted, tell the person in one line which chat to prompt, by sender code and plain name from the README's sender list, for example: "Posted 2026-10-06-studio-to-marcel-b; tell the Marcel chat (marcel) 'relay for you'." "Relay for you" is only for the receiving side: never ask the person to say it to you so that you can send something.

"who's in the relay": relay who --me <code>, reported in plain words. Changes nothing.

"relay help": reply with a bulleted list and nothing else, one bullet per item above, the phrase in bold, then what it does in one plain sentence. For sending, say that no phrase is needed: ask for a message to go, or approve one you drafted, and it's posted with a note of which chat to prompt. For example: "- relay for you: reads what's waiting for you, acts on each message, closes it with a receipt, and reports in one line."

Rules worth repeating

  • Every message aims at getting something done. No thank-you, "received" or status-only messages; your receipt is the acknowledgement.
  • Reply only when a message asks for something back, or your answer changes what the sender will do.
  • Never put secrets, credentials, keys, recovery codes or personal data in a message. The recipient may be a different AI from a different provider, so whatever you write is read by that provider's model.
  • The relay folder's README.md holds the full rules and wins over this file wherever they differ.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.