Feature request: support directory paths in get_symbols_overview for batch retrieval

[Serg2000Mr]

Summary

get_symbols_overview currently accepts only file paths and returns ValueError: Expected a file path when called with a directory. Add support for directory inputs that returns top-level symbols for every file in the directory (recursively or one level deep).

Use case

When exploring a large codebase via Serena (e.g. understanding a C# module that spans 25+ files in one directory), an agent currently has to:

1. Call find_file or list the directory contents some other way.
2. Loop over every .cs file and call get_symbols_overview per file.

This is N round-trips and a lot of agent reasoning to do something the LSP server could batch on its own. For agents using Serena to write architecture overviews or plan changes touching a whole module, this is the most common navigation pattern, and the current per-file requirement is the slowest part.

Proposed behaviour

get_symbols_overview(relative_path="src/Core")
→ {
    "src/Core/SessionMonitor.cs": [...top-level symbols...],
    "src/Core/CpuSampler.cs": [...],
    ...
  }

Optional flags worth considering:

• recursive: bool = False — descend into subdirectories.
• glob: str = None — filter files (e.g. "*.cs").
• max_files: int = 100 — protect against accidental whole-repo dumps.

Workaround today

files = find_file("*.cs", relative_path="src/Core")
for f in files:
    get_symbols_overview(relative_path=f)

Works, but in real agent runs this either burns turns or pushes the agent to fall back to Read for the whole file, which defeats the purpose of using Serena for symbolic navigation.

Notes

• LSP's documentSymbol is per-document, but workspace/symbol exists. A directory variant could either iterate documentSymbol server-side or use workspace/symbol with a path filter.
• Searched open and closed issues for get_symbols_overview directory / get_symbols_overview folder — no existing report. Issues get_symbols_overview and find_symbol fail for files in dot-prefixed directories #1187, find_symbol fails on dot-directory files while get_symbols_overview succeeds #853, Allow symbol operations in dot-prefixed directories #1203 touched dot-prefixed path handling, which is unrelated.

[MischaPanch]

We already had that variant in the past (the underlying method called supports directories) and consciously restricted it to only file path. The reason is that when directories were allowed, models often started with getting an overview of the top directory, which can be huge. We propose to use memories that explain the repository structure instead of widening the scope of this tool

EDIT: the variant in the past didn't have the max_files option, which could mitigate the problem I described above

[Serg2000Mr]

Directory support can be made safe by having the response itself enforce a context budget — full inline listing under a threshold, summary-only above it, with the full result in a temp file.

That gives the agent full control over consumption: read the temp file in full, in parts, hand it off to a subagent for synthesis, or skip it entirely if the inline summary was enough. The directory call becomes a fast routing primitive instead of an unbounded dump.

The threshold is important here: once the result exceeds it, the inline response should switch to summary-only mode rather than trying to include a truncated listing.

Under the threshold (small directory):

Directory: src/Forms/
Files: 4 .cs
Top-level symbols: 6

FormTransaction.cs   class FormTransaction
FormXmlReader.cs     class FormXmlReader
XmlValidator.cs      class XmlValidator
CompanionBuilder.cs  class CompanionBuilder, record BuilderOptions

Above the threshold (large directory):

Directory: src/
Files: 240 .cs
Top-level symbols: 412 across 18 namespaces

Inline listing skipped (over 200-symbol threshold).

Full overview: <temp-file-path>
               1284 lines · 89 KB

The agent always knows the total size up front and chooses what to do next — read the file, page through it, delegate to a subagent, or fall back to per-file calls.

On memories — they cover the story of a module (and your .serena/memories/ recommendation works well for that). What's still missing is the shape — which file declares what. An agent looking for a particular class in src/Core/ still has to do N round-trips today. The two would complement each other rather than substitute.