Repository navigation
fix(core): fall back to CLAUDE.md where no AGENTS.md exists - #64474
Conversation
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.
There was a problem hiding this comment.
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: { |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.mdis 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.
…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.
Issue for this PR
Closes #53402
Type of change
What does this PR do?
V1 read
CLAUDE.mdwhen a directory had noAGENTS.md, and~/.claude/CLAUDE.mdwhen~/.config/opencode/AGENTS.mdwas missing. V2 discovery never ported that, so this restores it:config/plugin/instruction.ts): the ancestor walk looks for both names and keepsCLAUDE.mdonly in directories without anAGENTS.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).tool/plugin/read.ts): nested discovery uses the same per-directory rule.InstructionDiscoverygetsclaude(per-directory fallback) andclaudeGlobal(~/.claude/CLAUDE.md) options, passed through as serverinstructions.claude/instructions.claudeGlobal. Matching V1, the CLI turns both off withOPENCODE_DISABLE_CLAUDE_CODEand only the global one withOPENCODE_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.mdhid everyCLAUDE.md. V2 loads every ancestor, so this PR picks per directory instead. ACLAUDE.md→AGENTS.mdsymlink (or the reverse) loads once.Docs:
instructions.mdxandmigrate-v1.mdxno longer say V2 skipsCLAUDE.md.How did you verify your code works?
AGENTS.mdprecedence,claudeGlobal: falsekeeping projectCLAUDE.md, and both switches off (instruction-discovery.test.ts), plus read-time fallback (session-instructions.test.ts). The existing watch andfs.upexpectations are updated.bun testfor 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 ondev.bun turbo typecheckpasses for core, server and cli; oxlint is clean on the changed files.Screenshots / recordings
n/a
Checklist
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.claudeGlobaland matchingInstructionDiscoveryoptions; CLAUDE.md fallback is on by default, gated byOPENCODE_DISABLE_CLAUDE_CODE/OPENCODE_DISABLE_CLAUDE_CODE_PROMPT(additive)