Custom Exploring Subagent — inject MCP-aware agent definitions on integration

[jasperfue]

What problem does this solve?

When Claude Code explores a codebase, it spawns a predefined Explore Subagent that only has access to a fixed set of tools: Grep, Glob, and Read.

This means that even when codebase-memory is installed and configured as an MCP server, the Explore Subagent is completely unaware of it — and exploration happens without leveraging codebase-memory's capabilities. The result is slower, less context-aware exploration that ignores a tool specifically designed for this purpose.

Concrete example:

Claude Code is asked to implement a new feature. It spawns the Explore Subagent to understand the codebase structure. Because the subagent only has Grep/Glob/Read, it manually scans files instead of querying codebase-memory — defeating the purpose of having codebase-memory installed.

Proposed solution

When codebase-memory is integrated into a host system (e.g. Claude Code), it should automatically generate and register a custom agent definition file — e.g. a explore-agent.md or equivalent — that:

• Defines a drop-in replacement (or extension) of the default Explore Subagent
• Includes codebase-memory's MCP tools in the agent's available tool set
• Follows the host system's agent definition format (e.g. Claude Code's .claude/agents/ directory)
  This way, when Claude Code decides to spawn an Explore Subagent, it picks up the codebase-memory-aware version instead of the built-in default.

Why this matters

Without this feature	With this feature
Explore Subagent ignores MCP tools	Explore Subagent leverages codebase-memory
Redundant file scanning	Semantic/indexed codebase queries
MCP integration is "opt-in per prompt"	MCP integration is seamless & automatic

---

Additional context

• Claude Code stores custom subagent definitions under .claude/agents/
• The generated agent file could be created during codebase-memory init or on first MCP connection
• Should be idempotent — re-running init updates the file rather than duplicating it

Alternatives considered

No response

Confirmations

• I searched existing issues and this is not a duplicate.