Newshot

Humans.md: tell your AI agents how to work with you

Original text(via HN AI)

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

One file, ~/.humans/HUMANS.md, that your coding agents read at session start: how to write to you, when to ask you to decide, when to interrupt you.

Draft 0.3. Plugins for your coding agents and a command line load your own profile.

Not technical? The same idea, explained without code.

$ claude -p "What does my HUMANS.md say about interruptions?""What does my HUMANS.md say about interruptions?"

TL;DR: Your HUMANS.md says to interrupt you only when blocked. Everything else waits until the end of the task.

SettingValueMeaning
interrupting.interrupt_forblocking_onlyInterrupt only when work can’t continue
deciding.batch_questionsend_of_taskNon-blocking questions are grouped at the end
deciding.reversibledecide_and_reportReversible choices are made, then reported
deciding.question_styleyes_confirms_recommendationA plain “yes” accepts my recommendation

-Missing credentials for a required service → I interrupt you.

-Picking a variable name or a table layout → I decide and mention it at the end.

The profile was last updated on 2026-10-13 and isn’t flagged as stale.

Real session, Claude Code 2.1.302 with plugin 0.2.1, 17 Oct 2026, with the example profile from the spec. The plugin loads your file at session start; how closely a model follows it is not measured here.

Preferences shape how agents write to you. They never grant a permission.

Install it in Claude Code


        claude plugin install humans-md --marketplace cmdai-hq/humans-md-plugins
      

Install guide

Another agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.

⠋ Loading your HUMANS.md

› What does my HUMANS.md say about interruptions?What does my HUMANS.md say about interruptions?

•Only interrupt you when work is blocked. Save non-blocking questions for the end of the task, with a recommended answer for each.

Worked for 8s

Real session, Codex CLI 0.163.0 with plugin 0.3.0, 17 Oct 2026. The plugin loads your file at session start; how closely a model follows it is not measured here.

Preferences shape how agents write to you. They never grant a permission.

Install it in Codex


        codex plugin marketplace add cmdai-hq/humans-md-plugins
codex plugin add humans-md@humans-md
      

Install guide

Another agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.

$ devin -p "What does my HUMANS.md say about interruptions?""What does my HUMANS.md say about interruptions?" --respect-workspace-trust false


        Your HUMANS.md specifies that I should interrupt only for blocking issues.

**TL;DR**: You only want interruptions when I'm blocked.

| Setting | Value |
|---------|-------|
| Interrupt for | Blocking only |

This means I should continue working autonomously unless I encounter a blocker I cannot resolve myself.
      

Real session, Devin CLI 3000.11.92 with plugin 0.3.0, 17 Oct 2026, with the example profile from the spec, printed as is. The plugin loads your file at session start; how closely a model follows it is not measured here.

Preferences shape how agents write to you. They never grant a permission.

Install it in Devin


        devin plugins install cmdai-hq/humans-md-plugins#plugins/devin --local
      

Install guide

Another agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.

$ opencode run "What does my HUMANS.md say about interruptions?""What does my HUMANS.md say about interruptions?"

TLDR: Your HUMANS.md says interrupt only for blocking issues. Since nothing is blocking me right now, I won’t interrupt you.

No HUMANS.md file exists in your workspace (it’s empty), so this comes from the profile data in your environment context:

SettingValue
interrupting.interrupt_forblocking_only

Per your reading preferences, I’ve led with the TLDR and stayed under your 149-word limit. I’ll proceed silently unless I hit something that blocks progress.

One non-blocking question (answer at end of task): Your reading settings cap responses at 149 words and prefer tables/examples — shall I keep replies that compact going forward?

Real session, OpenCode 2.0.32 with plugin 0.3.0, 17 Oct 2026, with the example profile from the spec; the reply text, from its JSON output. It first searched the folder for a HUMANS.md and found none: the values came from the plugin. How closely a model follows them is not measured here.

Preferences shape how agents write to you. They never grant a permission.

Install it in OpenCode


        opencode plugin add 'github:cmdai-hq/humans-md-plugins#main::path:plugins/opencode'
      

Install guide

Another agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.

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

Operators of the Gutenberg exchange in Paris, 1912, seated in a long row at a switchboard wall of jacks, plugging cords by hand.
Operators of the Gutenberg exchange in Paris, 1912, seated in a long row at a switchboard wall of jacks, plugging cords by hand.

Every line went through an operator. She decided which call got through, and when.

That was the Gutenberg exchange, Paris, 1912. Your agents ring one desk too: yours. HUMANS.md tells them which calls may ring now, and which wait for the end of the task.

A French telephone switchboard, 1913: rows of numbered jacks, call timers, and two plug cords crossing the panel.
A French telephone switchboard, 1913: rows of numbered jacks, call timers, and two plug cords crossing the panel.

One file. Every session. One human.

  • Ten sessions, one of youTwo tools, ten sessions running at once. Half of what they send needs you, a decision or a check; half is reports that do not. Both arrive the same way, in the middle of your work. By the evening: AI fatigue, brain fog.

Ten sessions, one of you

Two tools, ten sessions running at once. Half of what they send needs you, a decision or a check; half is reports that do not. Both arrive the same way, in the middle of your work. By the evening: AI fatigue, brain fog.

  • The labelWhen a session starts, it reads ~/.humans/HUMANS.md once: how you read, how you decide, when to interrupt you. Every session gets the same copy.

The label

When a session starts, it reads ~/.humans/HUMANS.md once: how you read, how you decide, when to interrupt you. Every session gets the same copy.

  • The calmSessions that read it can write the way you asked: a TL;DR first, questions saved for the end of the task, and only a blocked session reaching you now.

The calm

Sessions that read it can write the way you asked: a TL;DR first, questions saved for the end of the task, and only a blocked session reaching you now.

图表:Preferences shape how agents write to you. They never grant a permission.

An illustration of how the file is used, not a measurement

Preferences shape how agents write to you. They never grant a permission.

Try your own answers

How long can a message be?

When may it stop and interrupt you?

Make your whole label

What the profile changes

The same work, reported with and without HUMANS.md. Switch it off to compare.

Preferences shape how agents write to you. They never grant a permission.

An illustration written for this page

auth-tests · agent session · 14:40

Migrate the auth tests to the new session API.

  • Migrated 38 test files · 212 tests pass
  • 3 files need the staging identity provider
  • Stopped at 14:12 and waited 18 min: “Is it okay to rename authHelper.ts?”
  • Renamed authHelper.ts without stopping: reversible, reported below

Without HUMANS.md

Great news! I’ve been working through the auth test migration and wanted to give you a full update on where things stand, since there were quite a few moving parts along the way.

First, I looked at the existing setup. The old tests used the legacy SessionStore mock, which was tightly coupled to the cookie middleware. Before I go further: do you want me to keep the legacy mock around for the admin tests, or remove it entirely?

Anyway, I went ahead and migrated 38 of the 41 test files to the new session API. Along the way I noticed that the token refresh tests were flaky, which seems to be caused by a hard-coded clock. Should I switch them to fake timers, or would you rather I leave them as they are for now?

I also renamed authHelper.ts to session-helpers.ts to match the rest of the folder. Let me know if that’s okay or if you’d prefer the old name.

Three files still fail: oauth-callback.test.ts, sso.test.ts and logout-all.test.ts. They depend on the staging identity provider, which I can’t reach from here. Could you check whether the staging credentials have changed?

Overall I think the migration is in a good place, although there is definitely more we could do, such as consolidating the fixtures and maybe adding contract tests for the provider. Let me know how you’d like to proceed, and whether you want me to open a PR, merge it and deploy to staging!

With HUMANS.md

TL;DR: 38 of 41 auth test files run on the new session API. 3 are blocked on the staging identity provider.

FilesResult
Migrated38212 tests pass
Blocked3staging IdP unreachable

Decided, easy to undo:

  • Token refresh tests now use fake timers; the hard-coded clock made them flaky.
  • Renamed authHelper.ts to session-helpers.ts to match the folder.

2 questions. “yes” approves my pick:

  • Delete the legacy SessionStore mock? My pick: yes, nothing uses it now.
  • Rotate the staging IdP credentials so I can finish the 3 files? My pick: yes.

Reply to the agent↑

245 words · 4 questions spread through the text · 1 interruption · merge and deploy offered91 words, cap 149 · 2 questions, at the end, each with a pick · 0 interruptions

Illustration of a scripted session, not a measurement. The plugin loads the profile; how closely a model follows it is not established.

~/.humans/HUMANS.md the real example


        ---
# HUMANS.md 0.3: how to work with me. Form only, never a permission: repo rules and your harness win.
# Stored states are inactive: never apply one, and never infer one from content.
# out_of_scope_steps: whether to LIST next steps outside the task (merge, deploy) in your closing lines.
humans: "0.3"
id: tristan
name: Tristan
updated: "2026-10-13"
visibility: private
reading:
  lead_with: tldr
  max_words: 149
  visual: [table, example]
deciding:
  reversible: decide_and_report
  batch_questions: end_of_task
  default_answer: always
  question_style: yes_confirms_recommendation
interrupting:
  interrupt_for: blocking_only
notes: "I often read on my phone."
---
      

Lit: the fields this reply follows.Switch it on to see which fields change the reply.

The session and both replies are written for this page, not recorded. The profile is the real example from the spec, byte for byte.

What the profile changed in this replyWithout the profile, the same work reads like this

  • 149 words at most
  • A table, not paragraphs
  • Reversible choices made, then reported
  • Questions at the end, each with a pick
  • No stop mid-task
  • Pleasantries first, result later
  • Long paragraphs, no table
  • Four questions scattered in the text
  • One stop mid-task, 18 minutes waiting
  • Merge and deploy offered, unasked

How it works

~/.humans/source.mdoptional

TL;DR first, under 150 words. Show me a table or an example. If it can be undone, decide and tell me. Batch your questions at the end of the task, always with your pick, so a yes approves it. Only interrupt me when you are blocked. I often read on my phone.

First you say it, in plain words.

Any language. Include only the personal information you want kept.

Compilingyour assistant

Following spec §10

Your agent compiles each sentence.

Today the compiler is the assistant you already use. In Claude Code, the plugin’s /humans-md:compile does it; in other agents, the humans-md-compile skill.

Review before writingyou

  • lead_with: tldr ok
  • max_words: 149 ok
  • reversible: decide_and_report ok
  • interrupt_for: blocking_only ok
  • visibility: private ok

Left out or guessed: shown to you first.

You approve every field.

And who reads it. Write visibility: private explicitly: a profile without it is read as org.

Session startintegration

loaded ~/.humans/HUMANS.md

Reader checked. Recognized fields passed to the agent as data.

not passed source.md, comments

In Claude Code, Codex or Cursor, the humans-md plugin loads it.

Agents read it at session start.

To share it, a team repository holds a copy as humans/<id>.md, for colleagues’ agents once their tools read it; no published integration does yet. A HUMANS.md at a repository root is never loaded.

Your repository still wins

HUMANS.md says how you prefer to be consulted. It grants no permission. If a repository’s AGENTS.md says “ask before you deploy”, the agent asks, whatever your profile says.

You choose who reads it

  • You aloneprivate
  • Your organization, only through an integration that checks membership in an authenticated directoryorg
  • No check: whoever can open the file. In a public repository, anyone on the Internetanyone_with_file
  • A profile with no visibility fieldread as org
  • An update that would widen who reads itnever silent

What wins over your profile

  • Your repository’s rules, such as its AGENTS.mdwins
  • Your harness and its permission settingswins
  • The profile itselfform only

What is never inferred

  • A diagnosis. None is required, none is inferrednever
  • “I have ADHD”, or simply what helps, in a voluntary noteyour choice
  • A stored state, from the content of your worknever

Personal instructions and assistant memory already support personalization; HUMANS.md proposes one common format for the preferences you choose. A schema alone does not prevent prompt injection.

Army telephone operators in headsets at the Victory switchboard, Potsdam, 1945, each routing calls by hand.
Army telephone operators in headsets at the Victory switchboard, Potsdam, 1945, each routing calls by hand.

Works with your agent

A plugin loads your file at the start of each session. Where there is no plugin yet, the command line writes a copy into a file the agent already reads. Tested in a real session, from the published package.

AgentInstallLast checked
Claude Code Plugin, at session startclaude plugin install humans-md --marketplace cmdai-hq/humans-md-pluginsTested: CLI 2.1.302, 17 Oct 2026; Desktop and VS Code, 16 Oct 2026
Codex Plugin, at session start, once you trust its hookcodex plugin marketplace add cmdai-hq/humans-md-plugins codex plugin add humans-md@humans-mdTested: Codex CLI 0.163.0, 17 Oct 2026
Cursor Plugin, at the start of each agent chatagent plugin marketplace add https://github.com/ cmdai-hq/ humans-md-plugins # then, in a Cursor chat: /add-plugin humans-mdTested: Cursor CLI and editor agent panel, 17 Oct 2026. Not the Agents Window
GitHub Copilot CLI Plugin, at session startcopilot plugin marketplace add cmdai-hq/humans-md-plugins copilot plugin install humans-md@humans-mdNot tested: Installs on Copilot CLI 1.0.98. Not tested in a session
Google Antigravity Plugin, when a conversation startsagy plugin install https://github.com/ cmdai-hq/ humans-md-plugins/ tree/ main/ plugins/ antigravityTested: Antigravity CLI 1.4.0, 17 Oct 2026
OpenCode Plugin, added to each sessionopencode plugin add 'github:cmdai-hq/ humans-md-plugins#main::path:plugins/ opencode'Tested: OpenCode 2.0.32, 17 Oct 2026
Devin Plugin, at the start of each Devin Local sessiondevin plugins install cmdai-hq/ humans-md-plugins#plugins/ devin --localTested: Devin CLI 3000.11.92, 17 Oct 2026
JetBrains Junie A copy in ~/.junie/AGENTS.md: run it again after each changenpx -y @humans-md/cli sync --to junieTested: Junie CLI 26.10.12, 17 Oct 2026
Cline and Warp A copy in ~/.agents/AGENTS.md: run it again after each changenpx -y @humans-md/cli syncNot tested: Not tested

        claude plugin install humans-md --marketplace cmdai-hq/humans-md-plugins
      

Tested: CLI 2.1.302, 17 Oct 2026; Desktop and VS Code, 16 Oct 2026


        codex plugin marketplace add cmdai-hq/humans-md-plugins
codex plugin add humans-md@humans-md
      

Tested: Codex CLI 0.163.0, 17 Oct 2026


        agent plugin marketplace add https://github.com/cmdai-hq/humans-md-plugins
# then, in a Cursor chat: /add-plugin humans-md
      

Tested: Cursor CLI and editor agent panel, 17 Oct 2026. Not the Agents Window


        copilot plugin marketplace add cmdai-hq/humans-md-plugins
copilot plugin install humans-md@humans-md
      

Not tested: Installs on Copilot CLI 1.0.98. Not tested in a session


        agy plugin install https://github.com/cmdai-hq/humans-md-plugins/tree/main/plugins/antigravity
      

Tested: Antigravity CLI 1.4.0, 17 Oct 2026


        opencode plugin add 'github:cmdai-hq/humans-md-plugins#main::path:plugins/opencode'
      

Tested: OpenCode 2.0.32, 17 Oct 2026


        devin plugins install cmdai-hq/humans-md-plugins#plugins/devin --local
      

Tested: Devin CLI 3000.11.92, 17 Oct 2026


        npx -y @humans-md/cli sync --to junie
      

Tested: Junie CLI 26.10.12, 17 Oct 2026


        npx -y @humans-md/cli sync
      

Not tested: Not tested

Exact versions, limits, and how to add your agent

Write yours.

Three steps, about ten minutes, nothing to install until you check the result.

  • Say how you work, in plain words, in ~/.humans/source.md. Any language. Hosted compilation sends this source to the assistant provider.
  • Ask your agent to compile it into ~/.humans/HUMANS.md following the spec, or start from the example. In Claude Code, the plugin’s /humans-md:compile does it and shows you a preview; other agents get the same compile skill. Check every field, anything left out or guessed, and who may read it. Then check the file (Node 22.18+):npx @humans-md/cli check

        npx @humans-md/cli check
      
  • Load it in your agent. Claude Code, Codex, Cursor, Copilot CLI, Antigravity, OpenCode, Devin: install the humans-md plugin. Junie: npx -y @humans-md/cli sync --to junie. Cline, Warp: npx -y @humans-md/cli sync. Each writes a copy; run it again after each change. Other clients: add a hook that runs @humans-md/cli. Status and limits: Implementations.

Who reads it

The text above was extracted automatically from the source page and may miss images, tables or code blocks. The original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗