[FEATURE] Per-project agent configuration (whitelist/blacklist)

[gounthar]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Previously raised in #16836 (auto-closed and locked).

Agents are managed globally in ~/.claude and apply to all projects. This causes performance warnings when the cumulative agent descriptions exceed ~15k tokens, even though many agents are only relevant to specific projects.

A developer working across multiple domains (mobile, infrastructure, documentation, blockchain, AI) accumulates 200+ agents globally. A documentation repo doesn't need Kubernetes or blockchain agents. An embedded systems project doesn't need React or Django agents. But today the only option is to delete agents entirely, removing them from all projects.

Proposed Solution

Add per-project agent configuration, similar to how CLAUDE.md provides project-specific instructions.

Option A: Project-level .claude/agents.json

{
  "mode": "whitelist",
  "agents": ["brain-dump-organizer", "session-journalist", "content-writer"]
}

Option B: Setting in .claude/settings.json (project-level)

{
  "agents": {
    "mode": "blacklist",
    "list": ["mobile-developer", "kubernetes-specialist", "blockchain-developer"]
  }
}

Either approach:

1. Only loads relevant agents per project, reducing token overhead
2. Falls back to global configuration if no project config exists
3. No breaking changes

Alternative Solutions

Current workarounds:

1. Accept performance warnings (soft limit, not blocking)
2. Manually delete/reinstall agents when switching project types
3. Maintain minimal global agent set (limiting capabilities in specialized repos)

None of these are satisfactory for users with large agent libraries working across diverse projects.

Priority

Medium - Would be very helpful

Feature Category

Performance and speed

Use Case Example

1. Developer has 220+ agents across categories (DevOps, mobile, data, content, security, etc.)
2. Opens a documentation-only repository
3. Claude Code loads all 220 agent descriptions (~15k+ tokens), triggering performance warning
4. With per-project config: only 5-10 relevant agents load, no warning, faster context
5. Switching to an infrastructure repo loads a different agent subset automatically

Additional Context

• References: [FEATURE] Per-project agent configuration (whitelist/blacklist) #35017 and [FEATURE] Per-Project Agent Configuration #16836 (same request, auto-closed/locked)
• This is a scaling problem: the more productive you are with agents, the worse the performance tax in unrelated projects
• The existing .claude/settings.json per-project override mechanism could be extended naturally to support this

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] Per-project agent configuration (whitelist/blacklist) #35017
2. [FEATURE] Per-Project Agent Configuration #16836
3. [FEATURE] Add a setting to opt out of recursive skill/agent inheritance from parent directories #44691

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code