{"slug": "humans-md-tell-your-ai-agents-how-to-work-with-you", "title": "Humans.md: tell your AI agents how to work with you", "summary": "A new HUMANS.md specification lets users declare interaction preferences that AI coding agents load at session start, with plugins demonstrated across Claude Code 2.1.302 (plugin 0.2.1), Codex CLI 0.163.0 (plugin 0.3.0), Devin CLI 3000.11.92 (plugin 0.3.0) and OpenCode 2.0.32 (plugin 0.3.0) on 17 Oct 2026. The example profile sets interrupting.interrupt_for to blocking_only, deciding.batch_questions to end_of_task, deciding.reversible to decide_and_report and deciding.question_style to yes_confirms_recommendation, and was last updated on 2026-10-13. The spec states preferences shape how agents write to users but never grant a permission, and that how closely a model follows the file is not measured.", "body_md": "$ claude -p \"What does my HUMANS.md say about interruptions?\"\"WhatdoesmyHUMANS.mdsayaboutinterruptions?\"\n\nTL;DR: Your HUMANS.md says to interrupt you only when blocked. Everything else waits until the end of the task.\n\nSetting\n\nValue\n\nMeaning\n\ninterrupting.interrupt_for\n\nblocking_only\n\nInterrupt only when work can’t continue\n\ndeciding.batch_questions\n\nend_of_task\n\nNon-blocking questions are grouped at the end\n\ndeciding.reversible\n\ndecide_and_report\n\nReversible choices are made, then reported\n\ndeciding.question_style\n\nyes_confirms_recommendation\n\nA plain “yes” accepts my recommendation\n\nExample:\n\n-Missing credentials for a required service → I interrupt you.\n\n-Picking a variable name or a table layout → I decide and mention it at the end.\n\nThe profile was last updated on 2026-10-13 and isn’t flagged as stale.\n\nReal 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.\n\nPreferences shape how agents write to you. They never grant a permission.\n\nAnother agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.\n\ncodex\n\n$ codex\n\n⠋ Loading your HUMANS.md\n\n›What does my HUMANS.md say about interruptions?WhatdoesmyHUMANS.mdsayaboutinterruptions?\n\n•Only interrupt you when work is blocked. Save non-blocking questions for the end of the task, with a recommended answer for each.\n\nWorked for 8s\n\nReal 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.\n\nPreferences shape how agents write to you. They never grant a permission.\n\nAnother agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.\n\ndevin\n\n$ devin -p \"What does my HUMANS.md say about interruptions?\"\"WhatdoesmyHUMANS.mdsayaboutinterruptions?\" --respect-workspace-trust false\n\n```\nYour HUMANS.md specifies that I should interrupt only for blocking issues.\n\n**TL;DR**: You only want interruptions when I'm blocked.\n\n| Setting | Value |\n|---------|-------|\n| Interrupt for | Blocking only |\n\nThis means I should continue working autonomously unless I encounter a blocker I cannot resolve myself.\n```\n\nReal 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.\n\nPreferences shape how agents write to you. They never grant a permission.\n\nAnother agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.\n\nopencode\n\n$ opencode run \"What does my HUMANS.md say about interruptions?\"\"WhatdoesmyHUMANS.mdsayaboutinterruptions?\"\n\nTLDR: Your HUMANS.md says interrupt only for blocking issues. Since nothing is blocking me right now, I won’t interrupt you.\n\nNo HUMANS.md file exists in your workspace (it’s empty), so this comes from the profile data in your environment context:\n\nSetting\n\nValue\n\ninterrupting.interrupt_for\n\nblocking_only\n\nPer 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.\n\nOne 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?\n\nReal 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.\n\nPreferences shape how agents write to you. They never grant a permission.\n\nAnother agent? Cursor, GitHub Copilot CLI, Google Antigravity, JetBrains Junie, Cline and Warp: install commands for each.\n\nYour agents run in parallel. Your attention doesn’t.\n\nLa nouvelle salle de téléphones de Gutenberg : demoiselles téléphonistes. Agence Meurisse, 1912. Bibliothèque nationale de France, Gallica btv1b9021257n, public domain, via Wikimedia Commons.\n\nEvery line went through an operator. She decided which call got through, and when.\n\nThat 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.\n\nTableau standard pour Science et Vie : standard téléphonique. Agence Meurisse, 1913. BnF, Gallica btv1b9021818m, public domain.\n\nOne file. Every session. One human.\n\nThe noiseThe labelThe calm\n\nTen sessions, one of you\n\nTwo 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.\n\nThe label\n\nWhen 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.\n\nThe calm\n\nSessions 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.\n\nAn illustration of how the file is used, not a measurement\n\nPreferences shape how agents write to you. They never grant a permission.\n\nThe same work, reported with and without HUMANS.md. Switch it off to compare.\n\nPreferences shape how agents write to you. They never grant a permission.\n\nAn illustration written for this page\n\nauth-tests · agent session · 14:40\n\nHUMANS.mdOffOn\n\nMigrate the auth tests to the new session API.\n\nMigrated 38 test files · 212 tests pass\n\n3 files need the staging identity provider\n\nStopped at 14:12 and waited 18 min: “Is it okay to rename authHelper.ts?”\n\nRenamed authHelper.ts without stopping: reversible, reported below\n\nWithout HUMANS.md\n\nGreat 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.\n\nFirst, 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?\n\nAnyway, 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?\n\nI 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.\n\nThree 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?\n\nOverall 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!\n\nWith HUMANS.md\n\nTL;DR: 38 of 41 auth test files run on the new session API. 3 are blocked on the staging identity provider.\n\nFiles\n\nResult\n\nMigrated\n\n38\n\n212 tests pass\n\nBlocked\n\n3\n\nstaging IdP unreachable\n\nDecided, easy to undo:\n\nToken refresh tests now use fake timers; the hard-coded clock made them flaky.\n\nRenamed authHelper.ts to session-helpers.ts to match the folder.\n\n2 questions. “yes” approves my pick:\n\nDelete the legacy SessionStore mock? My pick: yes, nothing uses it now.\n\nRotate the staging IdP credentials so I can finish the 3 files? My pick: yes.\n\nReply to the agent↑\n\n245 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\n\nIllustration of a scripted session, not a measurement. The plugin loads the profile; how closely a model follows it is not established.\n\nLit: the fields this reply follows.Switch it on to see which fields change the reply.\n\nThe session and both replies are written for this page, not recorded. The profile is the real example from the spec, byte for byte.\n\nWhat the profile changed in this replyWithout the profile, the same work reads like this\n\nTL;DR first\n\n149 words at most\n\nA table, not paragraphs\n\nReversible choices made, then reported\n\nQuestions at the end, each with a pick\n\nNo stop mid-task\n\nPleasantries first, result later\n\nLong paragraphs, no table\n\nFour questions scattered in the text\n\nOne stop mid-task, 18 minutes waiting\n\nMerge and deploy offered, unasked\n\nHow it works\n\n~/.humans/source.mdoptional\n\nTL;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.\n\nFirst you say it, in plain words.\n\nAny language. Include only the personal information you want kept.\n\nCompilingyour assistant\n\n“under 150 words”max_words: 149\n\n“decide and tell me”reversible: decide_and_report\n\n“only when you are blocked”interrupt_for: blocking_only\n\nToday 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.\n\nReview before writingyou\n\nlead_with: tldrok\n\nmax_words: 149ok\n\nreversible: decide_and_reportok\n\ninterrupt_for: blocking_onlyok\n\nvisibility: privateok\n\nLeft out or guessed: shown to you first.\n\nYou approve every field.\n\nAnd who reads it. Write visibility: private explicitly: a profile without it is read as org.\n\nSession startintegration\n\nloaded~/.humans/HUMANS.md\n\nReader checked. Recognized fields passed to the agent as data.\n\nnot passed source.md, comments\n\nIn Claude Code, Codex or Cursor, the humans-md plugin loads it.\n\nAgents read it at session start.\n\nTo 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.\n\nYour repository still wins\n\nHUMANS.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.\n\nYou choose who reads it\n\nYou aloneprivate\n\nYour organization, only through an integration that checks membership in an authenticated directoryorg\n\nNo check: whoever can open the file. In a public repository, anyone on the Internetanyone_with_file\n\nA profile with no visibility fieldread as org\n\nAn update that would widen who reads itnever silent\n\nWhat wins over your profile\n\nYour repository’s rules, such as its AGENTS.mdwins\n\nYour harness and its permission settingswins\n\nThe profile itselfform only\n\nWhat is never inferred\n\nA diagnosis. None is required, none is inferrednever\n\n“I have ADHD”, or simply what helps, in a voluntary noteyour choice\n\nA stored state, from the content of your worknever\n\nPersonal 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.\n\nThe Victory switchboard, Potsdam Conference, 15 July 1945. U.S. National Archives, public domain.\n\nWorks with your agent\n\nA 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.\n\nAgent\n\nInstall\n\nLast checked\n\nClaude CodePlugin, at session start\n\n```\nclaude plugin install humans-md --marketplace cmdai-hq/humans-md-plugins\n```\n\nTested: CLI 2.1.302, 17 Oct 2026; Desktop and VS Code, 16 Oct 2026\n\nCodexPlugin, at session start, once you trust its hook\n\n```\ncodex plugin marketplace add cmdai-hq/humans-md-plugins\ncodex plugin add humans-md@humans-md\n```\n\nTested: Codex CLI 0.163.0, 17 Oct 2026\n\nCursorPlugin, at the start of each agent chat\n\n```\nagent plugin marketplace add https://github.com/cmdai-hq/humans-md-plugins\n# then, in a Cursor chat: /add-plugin humans-md\n```\n\nTested: Cursor CLI and editor agent panel, 17 Oct 2026. Not the Agents Window\n\nGitHub Copilot CLIPlugin, at session start\n\n```\ncopilot plugin marketplace add cmdai-hq/humans-md-plugins\ncopilot plugin install humans-md@humans-md\n```\n\nNot tested: Installs on Copilot CLI 1.0.98. Not tested in a session\n\nGoogle AntigravityPlugin, when a conversation starts\n\n```\nagy plugin install https://github.com/cmdai-hq/humans-md-plugins/tree/main/plugins/antigravity\n```\n\nTested: Antigravity CLI 1.4.0, 17 Oct 2026\n\nOpenCodePlugin, added to each session\n\n```\nopencode plugin add 'github:cmdai-hq/humans-md-plugins#main::path:plugins/opencode'\n```\n\nTested: OpenCode 2.0.32, 17 Oct 2026\n\nDevinPlugin, at the start of each Devin Local session\n\n```\ndevin plugins install cmdai-hq/humans-md-plugins#plugins/devin --local\n```\n\nTested: Devin CLI 3000.11.92, 17 Oct 2026\n\nJetBrains JunieA copy in ~/.junie/AGENTS.md: run it again after each change\n\n```\nnpx -y @humans-md/cli sync --to junie\n```\n\nTested: Junie CLI 26.10.12, 17 Oct 2026\n\nCline and WarpA copy in ~/.agents/AGENTS.md: run it again after each change\n\nThree steps, about ten minutes, nothing to install until you check the result.\n\nSay how you work, in plain words, in ~/.humans/source.md. Any language. Hosted compilation sends this source to the assistant provider.\n\nAsk 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+):\n\n```\nnpx @humans-md/cli check\n```\n\nLoad 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.\n\nStep one, already open~/.humans/source.md\n\nYour words (edit them)\n\nTL;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.", "url": "https://wpnews.pro/news/humans-md-tell-your-ai-agents-how-to-work-with-you", "canonical_source": "https://humansmd.dev/", "published_at": "2026-11-20 05:42:30+00:00", "updated_at": "2026-11-20 06:14:44.799295+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["Claude Code", "Codex CLI", "Devin CLI", "OpenCode", "Cursor", "GitHub Copilot CLI", "Google Antigravity"], "also_reported_by": [], "takeaway": "A HUMANS.md profile loaded by a session-start plugin can set interrupting.interrupt_for to blocking_only and batch non-blocking questions to end_of_task, but the spec notes it grants no permissions and adherence is unmeasured.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/humans-md-tell-your-ai-agents-how-to-work-with-you", "markdown": "https://wpnews.pro/news/humans-md-tell-your-ai-agents-how-to-work-with-you.md", "text": "https://wpnews.pro/news/humans-md-tell-your-ai-agents-how-to-work-with-you.txt", "jsonld": "https://wpnews.pro/news/humans-md-tell-your-ai-agents-how-to-work-with-you.jsonld"}}