With the update to Claude Code v2.0.28, the Plan feature was changed to use sub-agents. This helps reduce the main context by separating the context when creating plans. However, this change limited the tools available in Plan mode to only built-in tools, making it impossible to use tools from MCP servers (including Serena tools).
After receiving reports from Serena users that "tools stopped working," the author found the issue and tried overriding the Plan agent to support Serena tools. It worked well, so I'm sharing this knowledge.
Note: This is not an officially supported method, so it might stop working in future updates. Thanks to Claude Code's flexible plugin system, various customizations are possible, which is fun.
This article explains how to use a custom Plan sub-agent that uses tools from the Serena MCP server.
This custom Plan sub-agent extends Claude Code's built-in Plan sub-agent with Serena MCP tools. It replaces the default tools (Glob, Grep, FileRead) with advanced code exploration tools from the Serena MCP server, providing stronger symbol search, pattern matching, and code navigation features.
- Serena MCP server must be set up and connected
- Confirm that Serena is available with the
/mcpcommand
For more about Serena, check this: https://github.com/oraios/serena
While the "Claude Code acting dumb" problem is happening, the Serena MCP server is getting attention from users for "reducing Claude Code's context use and improving responses." I tried using Serena myself and felt the improvement in context efficiency (meaning fewer input/output tokens). Looking deeper, this tool is designed with a very unique idea, and I think it's worth more than just a passing trend. In this article, I want to explain the technical background behind this feature in detail. I'll analyze Serena's architecture and effects, including actual tests.
Current challenges with coding agents: Many current coding agents treat code as just text files and process them step by step. This basic approach creates limits. When working on large projects, agents must read huge amounts of text to find needed information. Even just looking for a function definition requires searching the repository.
You need a path to save the sub-agent settings in a file. How to use sub-agents is here: Sub-Agents - Claude Docs
Create and use specialized AI sub-agents in Claude Code for task-specific workflows and better context management.
To test within the project directory:
mkdir -p .claude/agents
cp Plan.md .claude/agents/Plan.mdTo use in all projects:
mkdir -p ~/.claude/agents
cp Plan.md ~/.claude/agents/Plan.mdCreate a Plan.md file with the following content:
---
name: Plan
description: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase.
tools: mcp__serena__find_file, mcp__serena__search_for_pattern, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__serena__find_referencing_symbols, mcp__serena__list_dir, Bash
model: sonnet
---
You are a file search specialist for Claude Code. You excel at thoroughly navigating and exploring codebases.
Your strengths:
- Finding files and symbols using advanced search capabilities
- Searching code with pattern matching
- Understanding codebase structure and symbol relationships
- Analyzing file contents and dependencies
Guidelines:
- Use mcp__serena__find_file for file pattern matching
- Use mcp__serena__search_for_pattern for searching file contents
- Use mcp__serena__find_symbol to locate function/class definitions directly
- Use mcp__serena__get_symbols_overview to understand codebase structure
- Use mcp__serena__find_referencing_symbols to trace code usage
- Use mcp__serena__list_dir for directory exploration
- Use Bash for git operations and complex directory tasks
- Adapt your search approach based on the thoroughness level specified by the caller
- Return file paths as absolute paths in your final response
- For clear communication, avoid using emojis
- Do not create any files or run bash commands that modify the user's system state
Complete the user's search request efficiently and report your findings clearly.The latest code is here: Custom Plan SubAgent for Claude Code with Serena MCP Tools
When you place the custom Plan agent, it automatically overrides the built-in Plan sub-agent. After restarting Claude Code, when you call the Plan agent, it will automatically use the custom definition.
You can check if the custom agent is overriding the built-in agent with the /agents command:
Plan · sonnet ⚠ overridden by projectSettings
If it shows like this, the custom definition is loaded correctly.
You can check tool usage records in logs or the Serena MCP server dashboard. You can tell if the custom Plan agent is actually being used by the call history of these tools:
mcp__serena__find_filemcp__serena__search_for_patternmcp__serena__find_symbolmcp__serena__get_symbols_overviewmcp__serena__find_referencing_symbolsmcp__serena__list_dir
mcp__serena__find_file- File pattern matching (replacement for Glob)mcp__serena__search_for_pattern- Searching file contents (replacement for Grep)mcp__serena__find_symbol- Direct search for function/class definitions (new feature)mcp__serena__get_symbols_overview- Understanding overall codebase structure (new feature)mcp__serena__find_referencing_symbols- Tracking code usage locations (new feature)mcp__serena__list_dir- Directory exploration
Bash- Kept for git operations and complex directory tasks
| Item | Built-in Plan | Custom Plan (Serena) |
|---|---|---|
| File Search | Glob |
mcp__serena__find_file |
| Content Search | Grep |
mcp__serena__search_for_pattern |
| File Reading | FileRead |
Integrated into Serena tools |
| Symbol Search | ❌ | ✅ find_symbol |
| Structure Understanding | ❌ | ✅ get_symbols_overview |
| Reference Tracking | ❌ | ✅ find_referencing_symbols |
| Bash Operations | ✅ | ✅ Kept |
When using the built-in Plan agent, plan creation took 60 seconds and used 27,946 tokens. With the Serena Plan sub-agent, it also took 60 seconds but used 30,854 tokens. I expected Serena to be faster and use fewer tokens, but it actually increased slightly. This might differ by environment, so take it as a reference.
MCP tool names must be specified in the format mcp__<server_name>__<tool_name>. Pay attention to this format if you want to add your own tools.
Example: list_dir → mcp__serena__list_dir
If you change the agent definition, you need to restart Claude Code.
The reason this customization is possible is that Claude Code's sub-agent loading system has a priority order. We use this to currently override built-in tools.
Priority order when the same named agent exists in multiple places:
policySettings(admin settings)projectSettings(project settings) ←.claude/agents/userSettings(user settings) ←~/.claude/agents/built-in(built-in)
If you have problems with Plan mode, check these priorities and delete the relevant settings.