skip to content

When Claude Code finds subagent definitions with the same name in managed settings, `--agents`, project, user and plugin scopes, which one runs?

level: middleimportance: should knowfreq 12%

answer

  1. five sources, one winner
  2. organisation outranks everything
  3. session flag beats files on disk
  4. project beats personal
  5. plugins rank last and are namespaced

basics

~10 s

The highest-priority source wins: managed settings, then the --agents flag, then the project's .claude/agents/, then ~/.claude/agents/, then plugins. Among nested project directories, the definition closest to the working directory wins.

solid answer

~40 s

Claude Code ranks subagent sources: managed settings (organisation-wide) first, the `--agents` JSON flag (this session only) second, the project's `.claude/agents/` third, your `~/.claude/agents/` fourth, and a plugin's `agents/` directory last. The highest-priority definition with a given `name` runs. Project agents are found by walking up from the working directory, and the closest `.claude/agents/` wins between nested ones. Two files with the same `name` in one directory tree is undefined: one loads by filesystem order, and `/doctor` reports it. A user or project file named `Explore` overrides the built-in Explore. Plugin agents also get a scoped name such as `my-plugin:reviewer`, and they ignore `hooks`, `mcpServers` and `permissionMode` for security.

code

bash · 8 lines
bash
claude --agents '{
  "security-reviewer": {
    "description": "Reviews changed code for injection and authorization flaws.",
    "prompt": "You are a security reviewer. Report findings as file:line, severity, fix.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

go deeper

for a junior

Know the two file locations and that a project agent beats a personal one with the same name.

for a middle

Recite the five-source order, the closest-directory rule for nested projects, and why a duplicate name in one directory tree is a defect.

for a senior

Use precedence on purpose: a managed agent nobody can shadow, --agents for one-run overrides, and plugin agents reached by scoped name with their ignored fields understood.

for a principal

Design the naming and ownership scheme for agents across an organisation so mandated agents stay authoritative and personal ones never silently replace team ones.

## Why precedence matters A subagent's **`name`** is its identity: it is what Claude delegates to, what an @-mention resolves, and what a `SubagentStart` hook matches. Teams quickly end up with the same name in several places, a `reviewer` in the repository, another in someone's home directory, a third shipped by a plugin. Claude Code resolves that clash by **source priority**, not by which file is newer or more specific in content. ## The five sources | Priority | Source | Scope | How it gets there | |---|---|---|---| | 1 (highest) | **Managed settings** | Organisation-wide | Markdown files in `.claude/agents/` inside the managed settings directory, deployed by administrators | | 2 | **`--agents` flag** | Current session only | JSON passed when launching Claude Code; never written to disk | | 3 | **Project** `.claude/agents/` | One repository | Committed with the code | | 4 | **User** `~/.claude/agents/` | All your projects | Personal files | | 5 (lowest) | **Plugin** `agents/` | Wherever the plugin is enabled | Installed with the plugin | Read the table as two rules: the **organisation beats the session, the session beats files**, and among files the **project beats the person**. A developer cannot shadow a managed `security-reviewer` with a personal copy, and a project's shared `reviewer` beats the same name in your home directory. ## Ties inside one scope Priority settles clashes **between** sources. Inside a source: - **Nested project directories.** Claude Code walks up from the working directory to the repository root and scans every `.claude/agents/` on the way. When two define the same `name`, the one **closest to the working directory** wins, which lets a package in a monorepo specialise a repository-wide agent. - **The same directory tree.** Directories are scanned recursively, and subfolders do not change identity. If two files under one `.claude/agents/` declare the same `name`, only one loads, chosen by **filesystem read order**, which is not a documented precedence. Treat it as a defect; `/doctor` reports such files and proposes keeping one. - **Added directories.** A directory added with `--add-dir` contributes its own `.claude/agents/` alongside your project agents. ## Built-ins and plugins **Built-in agents** can be shadowed: a user or project subagent named `Explore` **overrides** the built-in Explore and keeps its own fields, which is the documented way to run exploration on a cheaper model. **Plugin agents** are different in two ways: 1. They also register under a **scoped identifier**, `plugin-name:agent-name` (with subfolders included, such as `my-plugin:review:security`), so you can always reach a specific plugin's agent even when a bare name is taken. 2. For security, Claude Code **ignores `hooks`, `mcpServers` and `permissionMode`** in a plugin agent's frontmatter. If you need them, copy the file into `.claude/agents/` or `~/.claude/agents/`, where the fields apply. How plugins are packaged and installed belongs to the plugin material; the point here is what the definition can and cannot carry. ## The `--agents` flag in practice `--agents` takes a JSON object whose keys are agent names and whose values are definitions. The **`prompt`** field plays the role of the Markdown body; the other keys are the same frontmatter fields (`description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `memory`, `effort`, `isolation` and the rest), while `color` and `experimental` are ignored there. Because it outranks project and user files, it is a clean way to **override a team agent for one run** (a script, an experiment, a CI job) without editing anything on disk. Claude Code validates the value at startup and exits on an invalid one. ## How the winner shows up elsewhere Only the winning definition is visible to the rest of Claude Code. The @-mention typeahead lists your local agents by `name` and plugin agents by their scoped name, and you can type `@agent-<name>` by hand. `SubagentStart` and `SubagentStop` hooks match on the same identifiers: the frontmatter `name` for project and user agents, the scoped identifier for plugin agents. Because a scoped name contains a colon, a hook matcher for it is read as a regular expression, so anchor it as `^my-plugin:db-agent$` to match only that agent. ## Practical guidance - Use **managed** definitions for agents the organisation must control, such as a mandated security reviewer. - Commit **project** agents the team relies on, and give them names unlikely to collide with personal ones. - Keep **user** agents for personal workflow, knowing a project file of the same name will hide yours in that repository. - Use **`--agents`** for throwaway or automated overrides. - Expect **plugin** agents to lose to anything local, and reach them by scoped name when you need a specific one.

  • Your team's plugin ships a `db-migrator` agent with a `PreToolUse` hook, but the hook never fires. Why?
    Claude Code ignores `hooks`, `mcpServers` and `permissionMode` in plugin subagents for security. Copy the agent file into `.claude/agents/` or `~/.claude/agents/`, where the hook applies, or have the plugin ship the hook in its own hooks configuration so it applies whenever the plugin is enabled.
  • In a monorepo, `packages/api/.claude/agents/` and the root `.claude/agents/` both define `reviewer`. Which runs when you start Claude in `packages/api`?
    The one in `packages/api/.claude/agents/`. Project agents are discovered by walking up from the working directory, and between nested directories the definition closest to the working directory wins.

  • Project subagents beat managed ones because the closest scope wins.
  • A file in ~/.claude/agents/ overrides the project's agent with the same name.
  • Putting a project agent in agents/review/ changes the name you call it by.
  • A plugin subagent's hooks and permissionMode apply like any other agent's.
  • Definitions passed with --agents are saved for later sessions.