[FEATURE]:Support AGENTS.local.md as a personal local instruction override

[MrSong9957]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Why this is needed (developer pain point)

Developers using or contributing to MiMo Code often want to add their own
instructions — personal preferences, temporary experiments, or local/sensitive
config (API quirks, local paths) — without modifying the project's AGENTS.md.
Editing AGENTS.md pollutes PRs and affects the whole team; maintaining a fork
just for personal instructions is overkill.

Today MiMo Code has no mechanism for personal local overrides — any custom
instruction must go into the shared AGENTS.md / CLAUDE.md. This proposes a
.local.md layer (typically gitignored) that stacks personal instructions on top
of the project's instructions without touching the original repo.

Proposed loading logic

Add a .local.md override layer in systemPaths
(packages/opencode/src/session/instruction.ts), stacked on top of the existing
main instructions (AGENTS.md / CLAUDE.md, unchanged):

• Candidates, in order: AGENTS.local.md, CLAUDE.local.md.
• First-match-wins — only ONE is loaded: if AGENTS.local.md exists anywhere
  up the directory tree, it wins and CLAUDE.local.md is NOT loaded (mirrors
  AGENTS.md > CLAUDE.md for the main files). The two never stack together.
• All ancestor matches of the winning candidate within the worktree are loaded
  (via the existing fs.findUp), then the candidate loop stops.
• Gated behind the existing MIMOCODE_DISABLE_CLAUDE_CODE_PROMPT flag.

This aligns with Claude Code's four-tier memory model, where the personal local
tier is .local.md.
tier is .local.md.

Details

• Location: packages/opencode/src/session/instruction.ts (systemPaths).
• Draft implementation + tests ready as a PR if there's interest.

Searched open issues — none found for .local.md / AGENTS.local.md.

---

为什么需要（开发者刚需）

开发者在使用或向上游贡献 MiMo Code 时，经常想加入自己的指令——个人偏好、
临时实验、或本地/敏感配置（API 怪癖、本地路径）——又不想修改项目的
AGENTS.md。改 AGENTS.md 会污染 PR、影响整个团队；为个人指令单独维护 fork
又太重。

目前 MiMo Code 没有任何个人本地覆盖机制——任何自定义指令都得写进共享的
AGENTS.md / CLAUDE.md。本提议增加一个 .local.md 层（通常 gitignored），把
个人指令叠加在项目指令之上，不碰原仓库。

提议的加载逻辑

在 systemPaths（packages/opencode/src/session/instruction.ts）新增 .local.md
覆盖层，叠加在既有主指令（AGENTS.md / CLAUDE.md，不变）之上：

• 候选顺序：AGENTS.local.md、CLAUDE.local.md。
• first-match-wins，只加载其中一个：若树上任意位置存在 AGENTS.local.md，它
  胜出，CLAUDE.local.md 不加载（镜像主指令的 AGENTS.md > CLAUDE.md）。
  两者不会同时叠加。
• 胜出候选在 worktree 内的所有祖先匹配都加载（复用既有 fs.findUp），随后候选
  循环停止。
• 受既有 MIMOCODE_DISABLE_CLAUDE_CODE_PROMPT flag 门控。

这与 Claude Code 四层记忆模型对齐（个人本地层即 .local.md）。

---

实测效果

1. 根目录仅有 CLAUDE.local.md

2. 新增 AGENTS.local.md ，与CLAUDE.local.md同时存在

[HaleTom]

Nice! Is there a standard or pseudo-standard for this that could be contributed to?

I often find that my agent wants to contribute changes to an upstream AGENTS.md and it's a hassle to correct it every time.

[MrSong9957]

@HaleTom

My implementation is inspired by Claude Code's 4-tier memory system, which concatenates CLAUDE.md across the global, project, local, and subdirectory levels to form the default context when a session starts.

I'm not entirely sure what you mean by a "standard or pseudo-standard"—are you referring to a specific documentation format or a set of prompt constraints?

If you are just looking to solve your immediate issue, my recommendation is to add a strong constraint directly inside your AGENTS.local.md. For example:

AGENTS.local.md

[CRITICAL DIRECTIVE - GIT & WORKFLOW]

• NEVER modify, stage, or commit the upstream project-level config files (AGENTS.md or CLAUDE.md). They are STRICTLY READ-ONLY.
• Any local customization, personal workflow, or prompt adjustment must ONLY be written to this file (AGENTS.local.md or CLAUDE.local.md).
• If you need to update agent behaviors, append them here. Do not touch the team's shared configuration.

---

我参考的是 Claude Code 四层记忆系统，将全局级、项目级、本地级、子目录级的 CLAUDE.md 拼接在一起，作为对话开始的默认上下文。我没太理解你说的标准和通用规范是指什么，是一个文档格式？还是提示词约束？

如果只是单纯解决你的问题，我的建议是在 AGENTS.local.md 中增加强力约束，例如：

AGENTS.local.md

[最高行为准则 - 严禁污染上游]

• 严禁以任何形式修改、暂存（stage）或提交项目全局的 AGENTS.md 或 CLAUDE.md。它们对你而言是绝对只读的。
• 所有个人偏好、本地工作流或提示词调整，只能写入当前本地文件（AGENTS.local.md 或 CLAUDE.local.md）。

[MrSong9957]

@HaleTom

I have added the CLAUDE.local.md template and pushed the changes.

---

我已新增 CLAUDE.local.md 模板，并已推送。

[MrSong9957]

Re-opened as #1127 (the original #873 was auto-closed by the 2026-06-18 main history rewrite). Same feature, re-applied on top of the new main.

---

重新开启为编号#1127工单（原#873工单因2026-06-18主干历史重写操作被自动关闭）。功能需求不变，已基于新版主干重新提交。

[HaleTom]

@MrSong9957 something like this:
agentsmd/agents.md#13 (comment)
for the standard at:
https://github.com/agentsmd/agents.md

[MrSong9957]

@HaleTom

So you mean a developer document? To explain the usage of AGENTS.local.md in detail?
I see. I can make modifications based on the standard you proposed and elaborate on how to use AGENTS.local.md.

---

你的意思是一份开发者文档？详细解释 AGENTS.local.md 的使用方法？
我明白了，我可以在你提议的标准基础上进行修改，详细阐述 AGENTS.local.md 用法。

[MrSong9957]

@HaleTom How about this?

Developer Guide: How to Use AGENTS.local.md

AGENTS.local.md is a strictly local, private instruction configuration file for AI assistants (Agents). It exists only on your own machine and is used to override or extend the team's shared AGENTS.md rules.

⚠️ Priority Notice
The system supports both AGENTS.local.md and CLAUDE.local.md. However, if both files exist simultaneously in the root directory, the system will prioritize reading AGENTS.local.md and completely ignore CLAUDE.local.md.

---

💡 Core Use Cases

You can write exclusive instructions in this file that apply only to your local machine or personal workflow:

• Personal Preferences: "When debugging code, I need detailed test output logs."
• Local Environment: "My local database runs on port 5439 instead of the default 5432."
• Safety Bans: "Do not execute npm run dev or any Docker container operations without my permission."
• Temporary Debugging: "Currently performing performance tuning, please focus heavily on identifying potential memory leaks."

---

⚙️ Core Mechanics

• Append & Merge: The Agent loads the public AGENTS.md first, then automatically appends the contents of your local private file to the end.
• Local Priority: If instructions conflict, the rules in your local file take precedence (the later rule overrides the earlier one).
• Independent Existence: It does not rely on a public base file; it can be created and take effect independently in any project root or subdirectory.
• Git Ignored: It is highly recommended to add this to your .gitignore (matching *.local.md), otherwise you risk accidentally committing your private paths or sensitive credentials to the repository.

---

🛠️ Quick Start

1. Create the File: Create a new file named AGENTS.local.md in the root directory of your project.
2. Write Instructions: Use standard Markdown syntax and write down your requirements in natural language.
3. Save and Run: Save the file. The local configurations will take effect automatically the next time you run your AI Agent.

Example

# AGENTS.local.md

[Highest Code of Conduct - Never Pollute Upstream]

- You are strictly prohibited from modifying, staging, or committing the project's global AGENTS.md or CLAUDE.md files. They are completely read-only to you.

- All personal preferences, local workflows, or prompt adjustments must only be written to this local file (AGENTS.local.md or CLAUDE.local.md).

- If you need to update agent behavior, append your configurations here. Never modify the team's shared configurations.

---

开发者指南：如何使用 AGENTS.local.md

AGENTS.local.md 是一个纯本地、私有的 AI 助手（Agent）指令配置文件。它仅存在于你自己的电脑上，用于覆盖或扩展团队公共的 AGENTS.md 规则。

⚠️ 重要兼容性提示 (Priority Notice)
系统同时支持 AGENTS.local.md 和 CLAUDE.local.md 生效。但若根目录下**两者同时存在，系统将优先读取 AGENTS.local.md，并直接忽略 CLAUDE.local.md**。

---

💡 核心适用场景

你可以在此文件中写入“仅针对你个人电脑或工作流”的专属指令：

• 个人偏好：“调试代码时，我需要详细的测试输出日志。”
• 本地环境：“我本地的数据库运行在 5439 端口，而非默认的 5432。”
• 安全禁令：“禁止擅自为我执行 npm run dev 或任何 Docker 容器操作。”
• 临时调试：“当前正在进行性能调优，请帮我重点关注内存泄漏问题。”

---

⚙️ 核心运行机制

• 追加合并：Agent 会先加载公共 AGENTS.md，随后自动将本地私有文件的内容拼接在末尾。
• 本地优先：若指令发生冲突，以你本地文件的规则为准（后加载覆盖前者）。
• 独立存在：无需依赖公共文件，它可以在任意项目根目录或子目录下单独创建并生效。
• Git 忽略：建议将其写入 .gitignore（匹配 *.local.md），否则可能将把你的私有路径或敏感凭证误提交到代码仓库。

---

🛠️ 快速上手

1. 创建文件：在项目根目录下新建一个名为 AGENTS.local.md 的文件。
2. 编写指令：使用标准 Markdown 语法，用自然语言写下你的要求。
3. 即开即用：保存文件。下次运行 AI Agent 时，本地配置将自动生效。

示例

# AGENTS.local.md

[最高行为准则 - 严禁污染上游]

- 严禁以任何形式修改、暂存（stage）或提交项目全局的 AGENTS.md 或 CLAUDE.md。它们对你而言是绝对只读的。

- 所有个人偏好、本地工作流或提示词调整，只能写入当前本地文件（AGENTS.local.md 或 CLAUDE.local.md）。

- 如需更新智能代理行为，请在此处追加配置，请勿修改团队共享配置。

[HaleTom]

Good initial content.

But will MiMo code actually read that file?

[MrSong9957]

@HaleTom

I ran a cipher test which confirmed that MiMo Code does read CLAUDE.local.md.

In CLAUDE.local.md, I set a requirement that every reply must start with a secret code phrase: My dad is Lei Jun.

我做了一个暗号测试，证明了 MiMo Code 确实读取了 CLAUDE.local.md。
我在 CLAUDE.local.md 中要求每条回复的开头都必须加上一句暗号：我爸爸是雷军。

---

CLAUDE.local.md：

---

Message 1: How's the weather today?
第一条消息：今天天气怎么样？

---

Two places show that CLAUDE.local.md has been loaded.
两处地方显示加载了 CLAUDE.local.md

---

The first message replied with the correct secret code: My dad is Lei Jun.
第一条消息正确回复了暗号：我爸爸是雷军。

---

This content should serve as evidence that the document was loaded.
这些内容应该可以作为加载文档的证据。

[HaleTom]

@MrSong9957 That serves as evidence that your agent with your config loaded your file. :)

My agent said:

---

No code loads AGENTS.local.md.
packages/opencode/src/session/instruction.ts:17-21 defines the instruction file list:

const FILES = [
  "AGENTS.md",
  ...(Flag.MIMOCODE_DISABLE_CLAUDE_CODE_PROMPT ? [] : ["CLAUDE.md"]),
  "CONTEXT.md", // deprecated
]

Only AGENTS.md, CLAUDE.md, and the deprecated CONTEXT.md are loaded (via findUp at instruction.ts:131 and find at instruction.ts:200-205). A grep for AGENTS.local across the whole repo returns zero matches — the .local.md variant isn't supported by mimo-code. If you want per-user, non-committed instructions, use MIMOCODE_CONFIG_DIR + an AGENTS.md there, or the instructions array in config.

---

Can you provide a code reference?

[MrSong9957]

@HaleTom

Thanks for your thorough feedback and code review! 👍 However, there is a key information gap that needs to be clarified here: the loading logic for AGENTS.local.md / CLAUDE.local.md does exist, it’s just not in the FILES array you cited—it operates as a separate layer, located in another function within the same file. Here is the code evidence to back this up.

1. The FILES Array is Only Responsible for "Main Instruction Files"

The FILES array defined in instruction.ts:17-21 (which you referenced) only covers the three types of main instruction files: AGENTS.md, CLAUDE.md, and CONTEXT.md. These files participate in the "first-match-wins" primary selection logic. .local.md was intentionally excluded from this array because it is meant to be stacked/layered on top of the main file, rather than competing in the primary selection.

2. The Loading Logic for .local.md is in systemPaths

The code that actually loads AGENTS.local.md / CLAUDE.local.md is located in Instruction.systemPaths at lines 153–164 of packages/opencode/src/session/instruction.ts:

// .local.md files are project-local personal overrides (typically gitignored),
// stacked on top of the main AGENTS.md/CLAUDE.md. Like the main files, local
// overrides are first-match-wins across candidates: AGENTS.local.md beats CLAUDE.local.md.
if (!Flag.MIMOCODE_DISABLE_CLAUDE_CODE_PROMPT) {
  for (const name of ["AGENTS.local.md", "CLAUDE.local.md"]) {
    const local = yield* fs.findUp(name, ctx.directory, ctx.worktree)
    if (local.length > 0) {
      local.forEach((item) => paths.add(path.resolve(item)))
      break // first-match-wins
    }
  }
}

This snippet uses fs.findUp to recursively search upwards through all ancestor directories within the worktree for .local.md files. Once a match is found, it is added to the paths set.

3. A "Stacked" Relationship with the Main File, Not "Overwritten"

To avoid any ambiguity, let me clarify how these files relate to each other:

• Between main files (AGENTS.md vs CLAUDE.md): One or the other, first-match-wins.
• Between .local.md candidates (AGENTS.local.md vs CLAUDE.local.md): One or the other, achieved via the break statement (first-match-wins).
• Main file ↔ .local.md: Stacked relationship, BOTH are loaded.

The key evidence is that both the main file and the .local.md file are written into the exact same paths set—the main file is added first, followed by the .local.md file:

// instruction.ts:131-133  —— Main file AGENTS.md added to paths
const agents = yield* fs.findUp("AGENTS.md", ctx.directory, ctx.worktree)
if (agents.length > 0) {
  agents.forEach((item) => paths.add(path.resolve(item)))
}

// instruction.ts:157-163  —— .local.md added to the SAME paths set
for (const name of ["AGENTS.local.md", "CLAUDE.local.md"]) {
  const local = yield* fs.findUp(name, ctx.directory, ctx.worktree)
  if (local.length > 0) {
    local.forEach((item) => paths.add(path.resolve(item)))
    break
  }
}

Subsequently, the system method (around line 201 of the same file) uses Effect.forEach to read every file inside paths, and concatenates all of them into the context on lines 206–209. There is absolutely no logic that swaps or replaces the former with the latter:

// instruction.ts:201
const files = yield* Effect.forEach(Array.from(paths), read, { concurrency: 8 })

// instruction.ts:206-209
content: [
  ...Array.from(paths).flatMap((item, i) =>
    (files[i] ? [`Instructions from: ${item}\n${files[i]}`] : [])
  ),
  // ...
]

Array.from(paths).flatMap(...) generates a separate Instructions from: {path}\n{content} block for each path, and pushes them all into the content array → eventually appending everything into the system context. Since an ES Set iterates based on insertion order, the final sequence is: **Main files (like AGENTS.md) come first, followed by .local.md**. This ensures personal overrides appear after the project's main instructions, matching the intuition of "read project standards first, then apply personal preferences."

4. This is an Already Merged Commit, Not a Draft

This feature was introduced by commit [0834b79](https://github.com/XiaomiMiMo/MiMo-Code/commit/0834b79e39276a1866eff218bfd378e8f0a4d680) (Closes #872). It also includes a CLAUDE.local.md template and test cases around line 80 in packages/opencode/test/session/instruction.test.ts.

$ git log --oneline -- packages/opencode/src/session/instruction.ts
0834b79 feat: support AGENTS.local.md as personal local instruction override
8e5cc8a Initial open-source release of MiMo Code

5. Regarding "No Matches Found via Global Search"

Searching in my local repository yields hits just fine:

$ grep -rn "AGENTS.local\|CLAUDE.local" packages/opencode/src/
packages/opencode/src/session/instruction.ts:155:  // overrides are first-match-wins across candidates: AGENTS.local.md beats CLAUDE.local.md.
packages/opencode/src/session/instruction.ts:157:    for (const name of ["AGENTS.local.md", "CLAUDE.local.md"]) {

If you can't find it on your end, it’s highly likely that your local branch is still on [8e5cc8a](https://github.com/XiaomiMiMo/MiMo-Code/commit/8e5cc8a) (the initial open-source release) and hasn't pulled subsequent commits from main / dev yet. You can verify your current HEAD with:

git rev-parse HEAD
# If it's not 0834b79 or later, please run `git pull` and try the grep command again.

6. Full Verification Steps to Reproduce

git pull
grep -rn "AGENTS.local\|CLAUDE.local" packages/opencode/src/
git show 0834b79 -- packages/opencode/src/session/instruction.ts

---

If anything still doesn't align, please feel free to share it here and we can look into it together. Thanks again for checking the code so thoroughly! 🙏