AGENTS.md tells agents how to work on your repo. Nothing told mine how to work with me.
So I drafted HUMANS.md: one file, ~/.humans/HUMANS.md, that agents read before they spend your attention. How to write to you, what they may decide alone, when to interrupt.
Why: I run several Claude Code sessions in parallel. Each one stopped to ask me something, at its own pace, in its own format. My attention became the bottleneck.
How: you write a few plain sentences, your agent compiles them into closed fields you approve.
"TL;DR first" → lead_with: tldr
"batch your questions" → batch_questions: end_of_task
"interrupt me only if blocked" → interrupt_for: blocking_only
Agents read those fields as data, never as permissions. If your repo's AGENTS.md says "ask before you deploy", the agent still asks.
git status:
- draft 0.3, one person's open draft, not a standard
- spec, schemas, test vectors and a reference validator are open (CC BY 4.0 / Apache-2.0)
- Claude Code and Codex hooks: specified, shipping in progress.
humansmd.dev
What would you put in yours?
HUMANS.mdAGENTS.md is for your codebase. HUMANS.md is for you.A file for your agents, and your colleagues’ agents, to read before they spend your attention: how to write to you, when to ask you to decide, and when to interrupt you. An open format: AGENTS.md is for your codebase, HUMANS.md is read by agents and is about you.
commit a22e0f6