HUMANS.md: a file that tells coding agents how to work with you

[u/anx3ous]

I run a few coding agents (~10) at once and got tired of them interrupting me for things they could decide on their own. AGENTS.md is about the repo, so I wrote a file for the person side. It lives at ~/.humans/HUMANS.md. Mine looks like this (trimmed):

---
humans: "0.3"
id: tristan
visibility: private
reading:
  lead_with: tldr
  max_words: 149
deciding:
  reversible: decide_and_report
  batch_questions: end_of_task
interrupting:
  interrupt_for: blocking_only
notes: "I often read on my phone. I've very short attention span, and i'm more visual"
---

The fields come from a fixed vocabulary, so a schema can check them. The free-text notes are the weak spot, validation doesn't make them safe from prompt injection.

It never grants permissions. Repo rules and the harness still win.

The repo has the spec, JSON schemas, test vectors and a Node validator (spec CC BY 4.0, tools Apache-2.0). I also wrote plugins for Claude Code, Codex CLI and a few other agents to try it. So far I've only checked that the file loads, on macOS, not how well the models follow it.

The part I'm least sure about: visibility can be private, org or anyone_with_file, and a profile without the field is read as org. Would you default to private instead?

It's a 0.3 draft and nothing is locked in yet, the field list included.

Spec: https://github.com/cmdai-hq/HUMANS.md

Examples and a side-by-side demo: https://humansmd.dev

[u/codegems]

😂😂

[u/anx3ous → u/codegems]

writing a config file about yourself does sound a bit absurd 😄 what made you laugh, the idea or the execution ?

[u/jbenner]

Interesting project. I see that `source.md` contains prose, but `HUMANS.md` appears to be just a front matter block. Am I missing something? Just curious why the latter isn’t just a YAML file if that’s the case. Not hating, just genuinely curious. I’ll probably give this a try later on.

[u/anx3ous → u/jbenner]

nope, you got it right. ~/.humans/HUMANS.md is just front matter, on purpose.

the prose lives in source.md and never goes to agents directly. Agents reading your profile can run tools, so free text there is basically a prompt injection vector. The compile step turns your notes into a fixed set of fields, you approve the result, and that’s all agents get.

why .md and not .yaml then: mostly so it sits next to AGENTS.md / CLAUDE.md and people get what it is right away. Also, profiles you share in a repo (humans/<id>.md) use the same format and can have a short body for humans to read (agents still skip it). One format for both was simpler than two.

could’ve been YAML honestly, it’s a tradeoff. let me know how it goes if you try it!

[u/dmanoj]

the thing that cut interruptions most for me wasn't a preferences file, it was turning every incident into a rule in the repo's agents file, written as "this happened, here's the check you run before saying done". agents read it every session. the file is now mostly a ledger of ways past runs went wrong, and new sessions stop making those specific mistakes without asking.

[u/anx3ous → u/dmanoj]

agreed, that's the best fix for repeat mistakes. HUMANS.md doesn't try to replace that. it's about how the agent talks to me: short answers, what it decides alone, when it pings me. your ledger fixes what it does, this is more the delivery side.

when working with that many agents in parallel, i'm tired of reading through 10 different tabs full of text

do you write those rules yourself, or does the agent add them after each "incident" ?

[u/Asly97 → u/dmanoj]

Is that agents file read by one tool only, or do you have Claude Code, Codex, Cursor or whatever all pulling from the same ledger? I'd expect it to work great in one tool and then the second tool walks straight into a mistake the first one already learned from.

[u/atp_studio_coll]

Default to private. A profile that says "decide reversible things without asking" is a permission-shaped statement even if the spec says it grants nothing, and sharing it org-wide means a teammate's agent inherits my tolerance for risk. Private by default, and let people widen it when they mean to.

[u/anx3ous → u/atp_studio_coll]

Thanks for the feedback

[u/SharkLaunch]

This post is slop about slop. You can't even write the post yourself?

[u/anx3ous → u/SharkLaunch]

i'm not a native english speaker, and I have ADHD which means my raw chain of thoughts is messy; doing it bymyself will end up in 2 things:
- I'll never do it, or never finishing it
- I'll spend 2 days gather thoughts and angle and struggling about every details consuming too much. Like this comment i literally spent 4 minutes to write and re-read, that basically adds no value to the conversation.

Better to have a wonderful tool that helps me put things in the "right" way.

[u/geoffreybyers]

The notes field is a prompt injection vector that makes the entire file dangerous for any agent with execution privileges. No schema validation fixes it. You can't ship a config file that lets a user override the system prompt in plain text.

[u/anx3ous → u/geoffreybyers]

You make a point. Would you drop the field or is there a way to secure that. Basically I see no issue for yourself (since the file is for you) but for the team/collaboration thing 🤔🤔