[FEATURE] Per-Project Agent Configuration

Preflight Checklist

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

Problem Statement

Problem

Currently, 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.

Example: A brain-dumps/documentation repository doesn't need mobile development, blockchain, or infrastructure agents, but a developer working across multiple domains needs these agents available in other projects.

## Current Limitation

• Agents are enabled/disabled globally across all projects
• The only option is to delete agents entirely (removing them from all projects)
• This creates a trade-off: either accept performance warnings or lose agent availability in projects where they're needed

Proposed Solution

Proposed Solution

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

### Option 1: Project-level .claude/agents.json

  {
    "enabled": ["brain-dump-organizer", "session-journalist", "content-writer"],
    "disabled": ["mobile-developer", "kubernetes-specialist", "blockchain-developer"]
  }

Option 2: Setting in CLAUDE.md or .claude/settings.json

  agents:
    mode: "whitelist"  # or "blacklist"
    list:
      - brain-dump-organizer
      - session-journalist
      - content-writer

Benefits

1. Performance: Only load relevant agents per project, reducing token overhead
2. Clarity: Explicit about which agents are available in each context
3. Flexibility: Keep global agent library while optimizing per-project
4. No breaking changes: Falls back to global configuration if no project config exists

Alternative Solutions

Workaround

Currently, users must either:

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)

Priority

Medium - Would be very helpful

Feature Category

Performance and speed

Use Case Example

Use Cases

• Documentation repos: Only content/writing agents
• Infrastructure projects: Only DevOps/cloud agents
• Full-stack apps: Frontend, backend, database agents
• Mobile apps: Only mobile-specific agents

Additional Context

---
Environment: Claude Code CLI
Current behavior: Agents are global across all projects
Expected behavior: Ability to configure which agents are active per-project