Skip to content

feat(agent): AGENTS.md priority over CLAUDE.md per directory - #10503

Closed
iRonin wants to merge 1 commit into
NousResearch:mainfrom
iRonin:ironin/agents-priority-over-claude
Closed

feat(agent): AGENTS.md priority over CLAUDE.md per directory#10503
iRonin wants to merge 1 commit into
NousResearch:mainfrom
iRonin:ironin/agents-priority-over-claude

Conversation

@iRonin

@iRonin iRonin commented Apr 15, 2026

Copy link
Copy Markdown
Contributor

Problem

When both AGENTS.md and CLAUDE.md exist in the same directory, compose mode loads both. But users typically want AGENTS.md to be the authoritative agent instructions, with CLAUDE.md as a fallback for directories that don't have AGENTS.md.

Solution

New config option context.agents_priority (default: true):

When enabled, at each directory level during the walk:

  • If AGENTS.md exists -> load it, skip CLAUDE.md from that directory
  • If AGENTS.md doesn't exist -> load CLAUDE.md if present
  • .hermes.md is always loaded regardless (complementary Hermes instructions)

This means users get:

  • AGENTS.md where project-specific agent conventions exist
  • CLAUDE.md as fallback in dirs without AGENTS.md
  • .hermes.md on top as Hermes-specific additions

Config

context:
  agents_priority: true  # default: AGENTS.md wins over CLAUDE.md per dir

Testing

  • 135 tests pass, 1 skipped
  • Also fixes case-sensitivity bug in _resolve_walk_limit where .lower() broke path matching on macOS (/T/ vs /t/)

When compose=True and agents_priority=True (default), AGENTS.md takes
priority over CLAUDE.md at each directory level. If both exist in the
same directory, only AGENTS.md is loaded from that directory.
CLAUDE.md is loaded from directories that don't have AGENTS.md.
.hermes.md is always loaded as complementary Hermes-specific instructions.

Config: context.agents_priority (default: true)
Also fixes case-sensitivity bug in _resolve_walk_limit where .lower()
broke path matching on macOS (/T/ vs /t/).
@alt-glitch alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint area/config Config system, migrations, profiles labels Apr 26, 2026
@teknium1

Copy link
Copy Markdown
Contributor

Thanks for the detailed PR, @iRonin! This is an automated hermes-sweeper review.

After inspecting current main, the core behavior this PR implements — AGENTS.md taking priority over CLAUDE.md — is already present.

Evidence:

  • agent/prompt_builder.py lines 1068–1076: build_context_files_prompt uses a chained or: _load_agents_md(cwd_path) or _load_claude_md(cwd_path). First match wins, so AGENTS.md is loaded and CLAUDE.md is skipped whenever AGENTS.md exists in the directory. This is exactly the behavior this PR requests.
  • The function _resolve_walk_limit (which the PR's commit message claims to fix a case-sensitivity bug in) does not exist anywhere on current main. This indicates the PR was developed against a branch that includes the cascading walk-up work from feat(agent): cascading context file discovery with pluggable context loaders #10299 and feat(agent): cascading context file discovery with walk-up #10482, which are not yet merged.
  • The context.agents_priority config key and "compose mode" scaffolding in this PR have no counterpart on main.

If the intent is to extend this priority logic to multi-directory recursive walks once #10299/#10482 land, please rebase onto those branches and re-open against them. The single-directory case is already handled on main.

@teknium1 teknium1 closed this Apr 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/config Config system, migrations, profiles comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint P3 Low — cosmetic, nice to have type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants