What is HUMANS.md?
- HUMANS.md is an open file format that tells AI agents how to work with one person: what they read, what they decide, and when an agent may interrupt them. Your agents read it first; your teammates’ agents can read it before they write to you.
How is it different from AGENTS.md?
- AGENTS.md describes a codebase to agents: build steps, tests, conventions. HUMANS.md describes a person. Keep both. When they disagree, the repository wins on what an agent may do, and HUMANS.md wins on how the agent talks to you.
Why not just add a line to my CLAUDE.md?
- A line in CLAUDE.md reaches one tool on one machine. HUMANS.md is one file every agent can read, including other people’s agents, in closed fields that are safe to share and the same in every language.
Which agents read it today?
- Claude Code, through an @~/.humans/me.md import in your CLAUDE.md, and Codex, through a SessionStart hook. A skill and an MCP server for other agents are in progress.
Can a HUMANS.md give an agent a permission?
- No. A profile can make an agent ask you less, for example by deciding reversible things alone. It never lets an agent do something the repository or the tool does not already allow.
Can I write that I have ADHD, or another condition?
- No. HUMANS.md holds preferences, never diagnoses. Write what helps, such as “TL;DR first, one request per message”. The validator refuses health terms, and your profile says how to write to you, never why.
How is it different from the i-have-adhd skill?
- The i-have-adhd skill gives your own agent one fixed output style, the same for everyone, that you change by editing the skill. HUMANS.md is a profile you write about yourself, in closed fields, covering decisions and interruptions as well as format, and any agent can read it.
Does my free text leave my machine?
- No. You write in ~/.humans/me.source.md, in your own words and language. Your own agent compiles it into fields in ~/.humans/me.md, you check the result, and only those fields are ever shared.
Does it require a cmdAI product?
- No. The spec is under CC BY 4.0 and the tools under MIT. cmdAI makes HUMANS.md and also makes Humanload, which will be able to read your file; HUMANS.md works without it.