Skip to content

fix(core): fall back to CLAUDE.md where no AGENTS.md exists - #64474

Merged
neriousy merged 2 commits into
devfrom
fix/claude-md-fallback
Nov 17, 2026
Merged

neriousy merged 2 commits into
devfrom
fix/claude-md-fallback

Conversation

@opencode-agent

@opencode-agent opencode-agent Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Issue for this PR

Closes #53402

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

V1 read CLAUDE.md when a directory had no AGENTS.md, and ~/.claude/CLAUDE.md when ~/.config/opencode/AGENTS.md was missing. V2 discovery never ported that, so this restores it:

  • Initial instructions (config/plugin/instruction.ts): the ancestor walk looks for both names and keeps CLAUDE.md only in directories without an AGENTS.md. The global source falls back to ~/.claude/CLAUDE.md. Both are watched, so creating either one triggers a rescan (except a brand-new ~/.claude/ folder: the watcher can't watch a file whose folder doesn't exist yet, an existing limitation).
  • Read-time discovery (tool/plugin/read.ts): nested discovery uses the same per-directory rule.
  • Off switches: InstructionDiscovery gets claude (per-directory fallback) and claudeGlobal (~/.claude/CLAUDE.md) options, passed through as server instructions.claude / instructions.claudeGlobal. Matching V1, the CLI turns both off with OPENCODE_DISABLE_CLAUDE_CODE and only the global one with OPENCODE_DISABLE_CLAUDE_CODE_PROMPT. The skills flag (config.claude) is left as it was.

There's one intentional difference from V1. V1 stopped at the first file name found anywhere up the tree, so a root AGENTS.md hid every CLAUDE.md. V2 loads every ancestor, so this PR picks per directory instead. A CLAUDE.md → AGENTS.md symlink (or the reverse) loads once.

Docs: instructions.mdx and migrate-v1.mdx no longer say V2 skips CLAUDE.md.

How did you verify your code works?

  • New tests: global and per-directory fallback, AGENTS.md precedence, claudeGlobal: false keeping project CLAUDE.md, and both switches off (instruction-discovery.test.ts), plus read-time fallback (session-instructions.test.ts). The existing watch and fs.up expectations are updated.
  • bun test for instruction-discovery, session-instructions and tool-read: 61 pass. In the full core suite, the only failures are existing sandbox ones (git/project, GitLab OAuth, flock, real shell), which fail the same way on dev.
  • bun turbo typecheck passes for core, server and cli; oxlint is clean on the changed files.

Screenshots / recordings

n/a

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Requested by: @rekram1-node (Aiden Cline via Slack)


Added by the opencode bot (AI-generated).

Related: #36990

Public API: adds server options instructions.claude / instructions.claudeGlobal and matching InstructionDiscovery options; CLAUDE.md fallback is on by default, gated by OPENCODE_DISABLE_CLAUDE_CODE / OPENCODE_DISABLE_CLAUDE_CODE_PROMPT (additive)

V1 read CLAUDE.md when a directory had no AGENTS.md, and ~/.claude/CLAUDE.md
when the global AGENTS.md was missing. V2 discovery never ported it. Restore
it for initial and read-time discovery, choosing per directory, and honor
OPENCODE_DISABLE_CLAUDE_CODE and OPENCODE_DISABLE_CLAUDE_CODE_PROMPT.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The project CLAUDE.md fallback works. With the #53402 repro and a simulated model, the project codeword is missing from the model request on the base and present with this PR. Instruction-discovery, session-instructions and tool-read tests pass (61), and core type-checks.

I couldn't confirm the ~/.claude/CLAUDE.md fallback end to end. The repro creates ~/.claude/ after the server starts, and the watcher does nothing when a watched file's folder doesn't exist yet. So "creating either one triggers a rescan" doesn't hold for a brand-new ~/.claude/. That's an existing watcher limitation, not something this PR has to fix. The unit test covers the case where the file already exists.

Public API: this adds the server option instructions.claude (optional boolean, default on) and InstructionDiscovery.Options.claude. It also changes behaviour: CLAUDE.md / ~/.claude/CLAUDE.md are now loaded by default, and OPENCODE_DISABLE_CLAUDE_CODE / OPENCODE_DISABLE_CLAUDE_CODE_PROMPT now gate them. Everything is additive and existing configs keep working, but users who have a CLAUDE.md and no AGENTS.md will start getting it in their prompts.

Main concern (inline): OPENCODE_DISABLE_CLAUDE_CODE_PROMPT now turns off project CLAUDE.md files too. In V1 it only disabled ~/.claude/CLAUDE.md (see services/site/src/docs/v1/content/rules.mdx: "Disable only ~/.claude/CLAUDE.md"). So this doesn't match V1 yet, even though the description and docs say it does.

Related: #36990

file: process.env.OPENCODE_CONFIG,
content: process.env.OPENCODE_CONFIG_CONTENT,
},
instructions: {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In V1, OPENCODE_DISABLE_CLAUDE_CODE_PROMPT only disabled ~/.claude/CLAUDE.md; project CLAUDE.md files stayed on unless OPENCODE_DISABLE_CLAUDE_CODE was set (V1 rules.mdx: "Disable only ~/.claude/CLAUDE.md"). Here both variables go into the same claude flag, so _PROMPT=1 also drops project CLAUDE.md files. To match V1, the global fallback needs its own switch: e.g. instructions.claude set from DISABLE_CLAUDE_CODE only, plus something like instructions.claudeGlobal set from DISABLE_CLAUDE_CODE || DISABLE_CLAUDE_CODE_PROMPT, used only for claudeGlobalFile in instruction.ts. The new instructions.mdx paragraph would need the same update.

…UDE.md

As in V1, the prompt flag only skips the global ~/.claude/CLAUDE.md
fallback; OPENCODE_DISABLE_CLAUDE_CODE skips every CLAUDE.md. Split the
switch into instructions.claude and instructions.claudeGlobal.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My earlier point is fixed. OPENCODE_DISABLE_CLAUDE_CODE_PROMPT now skips only ~/.claude/CLAUDE.md through the new claudeGlobal option, matching V1, and the docs say the same. I re-ran the #53402 repro with a simulated model:

  • No flags: the project CLAUDE.md is loaded.
  • _PROMPT=1: it is still loaded.
  • OPENCODE_DISABLE_CLAUDE_CODE=1: it is skipped.

The nearby core tests pass, and core, server and cli type-check.

Public API: on top of the earlier instructions.claude, this adds the server option instructions.claudeGlobal and InstructionDiscovery.Options.claudeGlobal (optional booleans, default on). instructions.claude now covers only the per-directory fallback. Both are new in this PR, so nothing existing breaks.

No new concerns.

@neriousy
neriousy merged commit 7828491 into dev Nov 17, 2026
15 of 16 checks passed
@neriousy
neriousy deleted the fix/claude-md-fallback branch November 17, 2026 17:05
cevr added a commit to cevr/opencode that referenced this pull request Nov 17, 2026
…e/CLAUDE.md never joins them

The CLAUDE.md fallback (anomalyco#64474) reads ~/.claude/CLAUDE.md from Global.home. tempGlobalLayer and instruction-discovery's layer with only a config dir kept the real home, so three ConfigInstructionPlugin tests failed on any machine with a ~/.claude/CLAUDE.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

v2: no CLAUDE.md fallback (compatibility issue, as migrate-v1 asks)

3 participants