The renderer writes one file per AI. This page says where each AI reads it, and what to do when you change an answer. Product menus move; the file names and the mechanism do not. Where a menu path is given it is as of this writing; if it has moved, search the product's settings for "custom instructions" or "project instructions".
| Rendered file | Who reads it | How it is read |
|---|---|---|
CLAUDE.md | Claude Code | Automatically, from the project, or ~/.claude/CLAUDE.md for every project with --global. Nothing to paste. |
AGENT_ONBOARDING.md | any AI | Named as the second thing to read in CLAUDE.md, AGENTS.md and GEMINI.md. Paste or upload it where the AI does not read your local folder directly (below). |
AGENTS.md | Codex CLI, Cursor, Hermes Agent, and other agents that adopted the AGENTS.md convention | Automatically, from the repository root; --global writes ~/.codex/AGENTS.md (or $CODEX_HOME/AGENTS.md when CODEX_HOME is set) for all projects. Nothing to paste. |
GEMINI.md | Gemini CLI and Google Antigravity | Automatically, from the folder; --global writes ~/.gemini/GEMINI.md for all projects (also read by Google Antigravity alongside ~/.gemini/config/GEMINI.md). Nothing to paste. |
SOUL.md | Hermes Agent | --global --ai hermes appends a marked block to ~/.hermes/SOUL.md. In a project, use --ai agents for AGENTS.md. A different HERMES_HOME changes where Hermes reads the global file. |
chatgpt-box1.txt, chatgpt-box2.txt and chatgpt-custom-instructions.md | ChatGPT | Profile and response text to paste, with a preview and counts. |
system-prompt.md | anything with a system-prompt field, shared bots, API calls | Paste as the system prompt. Universal rules only, no profile, safe to share. |
Use npx agent-personalizer --global --ai claude,agents,gemini,hermes --yes for one profile across projects. Its source lives in ~/.agent-personalizer/; re-run with --global after editing it and start a new client session. Global mode accepts these four targets and level 1, excludes --dir, preserves text outside its markers and supports --global --uninstall. See global installation.
Claude Code
- Run the installer in the project folder.
CLAUDE.mdandAGENT_ONBOARDING.mdland there and Claude Code readsCLAUDE.mdon every session. - For rules that must win at the moment of decision, register the session-start hook: see
hooks/README.md. It prints the inject-marked rules and your onboarding block into context before your first message. - For your output style specifically, Claude Code has a custom output-style slot that lives in the system prompt every turn (
/output-style). Put the "How to talk" and "Output shape" lines fromAGENT_ONBOARDING.mdthere; a style in the system prompt is re-sent every turn, so it does not fade the way a file read once does. Tier 1 in tiers.md.
claude.ai (web and desktop apps), Claude Projects
The apps do not read files from your disk. Paste:
- The body of
USER.mdinto the Project's instructions field (Projects → your project → Set project instructions), followed by the body ofAGENT_ONBOARDING.md. - For a chat outside any Project, the account-level custom instructions field (Settings → Profile) takes the same text.
Re-paste after every re-render. --check verifies the files on disk; it cannot see the pasted copy.
ChatGPT
Open Settings → Personalization (or Settings → Customize ChatGPT on iOS and Android) and enable customization. Copy the exported profile and response instructions into the fields your current interface provides, checking its displayed limits.
- Profile:
chatgpt-box1.txtis the plain profile text. An edited or pre-existingUSER.mdis its source too. Confirmed entries fromLEARNED.mdreach the ChatGPT exports. - Response instructions:
chatgpt-box2.txtis the plain onboarding and selected rule text. - Preview:
chatgpt-custom-instructions.mdcarries both exports inside fences with their character counts.
The configured baseline budget is 1,500 characters per export in render/targets.json: ChatGPT Free and Go accounts cap Custom Instructions at 1,500 characters, while Plus, Pro, Business, Enterprise and Edu accounts allow up to 5,000 characters under Settings → Personalization (More about you and Custom instructions; Customize ChatGPT on mobile). With onboarding answers, box 1 compacts the generated profile while its structure still parses, and preserves custom profile text in full when it does not. Box 2 places the onboarding block (always-ask, off-limits, write policy, then style) before the selected session rules. Confirmed entries and declined "Never ask again" entries are both appended in full; nothing is truncated silently. Proposed entries are omitted. The preview reports each count; over-budget text is written in full and flagged OVER BUDGET, while --strict refuses the write. Review the text against your account's displayed limits. Account-level Custom Instructions do not read your local project folder directly, whereas file access in ChatGPT depends on the surface, uploads and enabled tools; for the full onboarding, entries and rule source in a ChatGPT Project, upload AGENT_ONBOARDING.md, LEARNED.md and rules/ as project files (or add Project instructions under Project settings).
Codex CLI
Run the installer at the repo root, then start Codex in that project. Codex builds its instruction chain once per run:
- Global guidance: the first non-empty
AGENTS.override.mdorAGENTS.mdin the Codex home directory (~/.codex, or$CODEX_HOMEwhen set).--global --ai agentswrites to that effective Codex home and warns without modifyingAGENTS.override.mdwhen a non-empty override shadowsAGENTS.md. - Project guidance: files from the repository root down to the working directory are merged in that order. Deeper files take precedence over earlier guidance. With no project root, discovery checks the working directory.
- Per directory:
AGENTS.override.mdis tried beforeAGENTS.md, followed by configured fallback filenames. At most one file is selected per directory; project installs warn if a non-emptyAGENTS.override.mdin the target folder shadowsAGENTS.md. - Size cap: the combined guidance has a default limit of 32 KiB, configurable with
project_doc_max_bytes. - Verify in a fresh session: run
codex --ask-for-approval never "Summarize the current instructions."(or"List the instruction sources you loaded.") from your repository root, checkecho $CODEX_HOMEif global guidance is missing, or inspectcodex -c log_dir=./.codex-log(./.codex-log/codex-tui.log) to confirm which instruction files loaded.
Verified against OpenAI's Codex AGENTS.md documentation on 2026-11-18. Restart Codex after an update so it rebuilds the instruction chain.
Cursor
Reads AGENTS.md at the project root. Older setups use .cursor/rules/; if yours does, point one rule file at AGENTS.md rather than copying its text, so there is one owner.
Gemini CLI and Google Antigravity
Gemini CLI reads GEMINI.md from the folder (and parent folders), plus ~/.gemini/GEMINI.md when installed with --global --ai gemini. Project installs also add .gemini/commands/personalize.toml for /personalize, and level-3 installs provide hooks/gemini-cli/session-start.sh for .gemini/settings.json (see hooks/README.md).
Google Antigravity also reads project GEMINI.md files (from the workspace root up to the current folder) and ~/.gemini/GEMINI.md for compatibility; its primary global instruction file is ~/.gemini/config/GEMINI.md, which enforces a 24,000-byte per-file limit after includes. Use --compact if a custom rule set approaches the 20,000-character warning budget.
Anything else
Use system-prompt.md. It carries only the universal blocks: no profile, no personal blocks, no off-limits names. That is deliberate: a system prompt is often shared, logged, or sent to a vendor, and the profile is not for that.
When you change an answer
- Re-run the installer with new answers through
--answers. It asks no questions on an existing install, regeneratesAGENT_ONBOARDING.mdand updates every rendered block.USER.mdis regenerated only if you never edited it; otherwise it is kept and the installer names the changed answers for you to carry over by hand (or deleteUSER.mdand re-run). EditingUSER.md,LEARNED.mdor a rule by hand:node render/render.cjs --dir .at level 3. - Files that are read automatically (
CLAUDE.md,AGENTS.md,GEMINI.md) are done. - Files that were pasted (claude.ai, ChatGPT, any system prompt) must be pasted again. Nothing can detect a stale paste for you; put "re-paste after re-render" in your own checklist.
Keep it working
- Edit the source: change
USER.md,LEARNED.md,rules/, or your answers, then re-render. The next render replaces the generated block. - Share the universal rules: use
system-prompt.mdfor a shared bot. KeepAGENT_ONBOARDING.mdin your own setup because it names your off-limits topics and working habits. - Keep one rule owner: link other files to the owning rule, or generate and check their copies. See tiers.md, tier 4.
Read the source: docs/companions.md
This repo tells an AI how to behave with you. Two optional companions govern operations routed through them. Properly configured, they enforce folder ACLs, approval gates or context receipts on calls through that companion; they do not block direct filesystem tools, shell commands or other connectors unless your host's own tool permissions or OS sandbox restrict those paths.
| Your saved setting | Without a companion | Through a configured companion |
|---|---|---|
| Always ask before delete / publish / send / spend | the AI remembering | obsidian-tc: destructive tools fail closed until a human confirms |
| Off limits folders | the AI remembering | obsidian-tc: folder ACL deny, per caller |
| Write policy (freely / logs and inbox only / ask first) | the AI remembering | obsidian-tc: per-folder read / write / delete scopes; Context Layer: memory writes stay proposals until approved |
| Evidence inline | the AI citing what it read | Context Layer: every disclosure and action leaves a receipt |
obsidian-tc (for Obsidian vaults)
What it is. A governed MCP server over Obsidian vaults: https://github.com/The-40-Thieves/obsidian-tc (AGPL-3.0). Its own README states the problem it exists for: an agent with raw filesystem access to a vault "can do real damage", and most Obsidian MCP servers hand that access over with an API key between the agent and everything you have written.
What it adds (its words, condensed):
- Governed writes: every call runs through auth → scopes → folder ACL → read-only kill switch → idempotency → throttle → human-in-the-loop confirmation → audit log. You decide which folders an agent may read, write or delete, per vault and per caller; destructive operations fail closed until a human approves.
- Fused retrieval: BM25 + vector + graph, fused and reranked, so "where did I say X" works across a large vault.
- Memory that lives in the vault: episodes, activation decay, explicit forgetting, under the same ACL as every other write.
- Three meta-tools by default (
find_capability,describe_capability,call_capability) in front of ~163 capabilities, so the agent's context stays small.
Try it:
npx obsidian-tc /path/to/vault
Lexical search and every note tool work immediately; semantic and graph retrieval need an embeddings backend (Ollama by default). Also ships as a Docker image, an .mcpb bundle, and standalone binaries.
How it pairs with this repo. Answer notes_tool: obsidian and obsidian_tc: yes and the rendered AGENT_ONBOARDING.md tells the AI to reach the vault through obsidian-tc rather than the filesystem; your off-limits and always-ask answers map to the folder ACL and human-in-the-loop list you configure in obsidian-tc. Calls routed through obsidian-tc enforce those rules; disable or sandbox raw filesystem and shell access in your AI host if you want the agent confined to that door. Answer obsidian_tc: no (the default) and the AI works on the vault folder directly, with the onboarding file naming what obsidian-tc would add.
The Context Layer (Sierra Catalina)
What it is. A specification and starter for purpose-bound context between you, your vault, and any agent: https://sierracatalina.com/context-layer. It is an architecture you adopt, with tested v0.2 contracts and a local proof profile you can run, not a package you install once.
The shape (from the page, condensed). Six stages: capture (record source, time, identity and a payload digest before interpretation) → normalize (derive structured claims with provenance and confidence) → vault (encrypted originals and policy state stay inside user-controlled authority; raw data never enters a bundle or a receipt) → decide (allow, reduce, approve or deny, by purpose, recipient, selectors, actions and expiry) → bundle (recipient-bound, expiring, single-use context with restrictions and provenance) → act (verify capabilities, execute the permitted action, append a minimized receipt; memory writes remain proposals). The receipt rail: request → decision → disclosure → action → writeback.
Read in this order: the essay (the argument in plain language) → architecture → specification → implementation → code (v0.2 contracts, encrypted local vault, four-state policy, scoped bundles, anchored receipts, a files adapter, a local-agent consumer) → demo. Its stated boundary: it does not claim production key custody or a portable signing suite.
How it pairs with this repo. Three saved settings are Context Layer decisions in miniature:
- Write policy "logs and inbox only" or "ask before every write" is the Layer's rule that memory writes remain proposals until approved.
- Off limits is the Layer's vault stage: originals that never enter a bundle.
- Always ask before is the Layer's decide stage: allow, reduce, approve or deny by action and recipient.
Running several agents is where it earns its keep (the hand-off layer, which this repo does not install): each delegation carries a purpose-bound bundle and returns a receipt, so you can answer "who saw what, and why" after the fact. The repo's AGENT_ONBOARDING.md is the human-readable policy; the Context Layer enforces and records it for context bundles and actions mediated by the Layer, alongside whatever host permissions or sandboxing govern direct local tools.
Reaching the other note tools
notes_tool answer | How an AI reaches it | Write posture rendered into the onboarding file |
|---|---|---|
obsidian | obsidian-tc (above) when obsidian_tc: yes, else the vault folder on disk | your write policy; enforced on obsidian-tc calls when its ACL is configured (host permissions still govern direct disk tools) |
logseq / folder | the folder on disk | your write policy, under each folder's README |
notion | Notion's own MCP connector | writes only into the pages or databases you name; the AI proposes new top-level pages, never creates them unasked |
google-docs | the Google Drive / Docs connector | the AI drafts into a doc named for the topic and never edits a shared doc's existing text without being asked |
apple-notes | a separately installed local Apple Notes MCP (no AI app ships one built in) | read, and create new notes; never edit or delete existing notes |
onenote / evernote | no first-class agent door today | treated as a read-only source; the AI writes to a local fallback folder (notes/) and tells you what to paste back |
other | you name the tool and the location | the AI asks before its first write there and uses the local fallback folder (notes/) until then |
None of these connectors ship in this repo. The onboarding file names the door; you connect it in your AI's own settings, where the app offers one. For cloud tools the onboarding file also says, explicitly, that none of these notes are local files, so the AI does not invent a folder named after your workspace.