AGENTS.md is for your codebase. HUMANS.md is for you.

A simple, open format that tells every agent how to work with you: what you read, what you decide, and when they may interrupt.

Think of it as a README about you, for agents.

30 → 3 interruptions in an hour

Scripted example below: 15 Claude Code sessions, one afternoon

Write yours Read the spec

~/.humans/me.mdthis is the whole idea

# what I read
reading:
  lead_with: tldr
  visual: [table, diagram]
# what I decide
deciding:
  reversible: decide_and_report
  batch_questions: end_of_task
# when you interrupt me
interrupting:
  interrupt_for: blocking_only

You write it in your own words; your agent turns it into these fields. Preferences, never a diagnosis.

Why HUMANS.md?

AGENTS.md tells agents how to work on your code. Nothing tells them how to work with you, so every agent guesses, and you correct it again, message after message, project after project.

One place for how you work. Write it once, every agent reads the same file.
Yours first, then your team’s. Your own agents use it today; a teammate’s agent can read it before it writes to you.
Safe to share. Closed fields checked by a schema: no free text reaches another agent, and no field can hold a diagnosis.

Your agents run in parallel. Your attention doesn’t.

30 times an agent stops and waits for you

a session is waiting for your input Scripted example: 15 Claude Code sessions, one hour.

How it works

You write, in your words
“I think in pictures. I make a lot of decisions every day, so keep the noise down. If it’s reversible, decide. Batch the rest, with your pick. Only stop me when you’re blocked.”
Your agent compiles, you approve
It turns your text into closed fields that a schema checks. Your free text stays on your laptop.
Every agent reads it
Your own agents first, then your teammates’ agents when they write to you. They get the fields and nothing else.

Your repository still wins

HUMANS.md can make an agent ask you less. It can never let an agent do more. If a repository’s AGENTS.md says “ask before you deploy”, the agent asks, whatever your profile says.

Preferences, never a diagnosis

Write “TL;DR first, one request per message”. Leave out why. The schema refuses health terms, and your profile says how to write to you, never who you are.

Works with the agents you already use

Agent	How it reads HUMANS.md	Status
Claude Code	Import line `@~/.humans/me.md` in `~/.claude/CLAUDE.md`	Works today
Codex	No import syntax yet: a `SessionStart` hook prints the file into the session	Works today
Any agent with an MCP client	A HUMANS.md MCP server returns the profile of the person you are writing to	In progress

All implementations and how to add yours

Write yours in five minutes

Say how you work, in plain words
Put it in ~/.humans/me.source.md. Any language. This file never leaves your machine.
Compile it into fields
Ask your agent to turn it into ~/.humans/me.md following the spec, or start from an example. Check the result, then keep it.
Point your agents at it
Claude Code: add @~/.humans/me.md to ~/.claude/CLAUDE.md. Codex and others: see implementations.

Some repositories use a file named HUMANS.md to credit contributors, or to brief people who work alongside agents. This one runs the other way: agents read it to learn how to work with you. How it fits next to AGENTS.md.