Merge branch 'main' of github.com:oraios/serena

README.md

@@ -44,7 +44,40 @@ With Serena, we provide
 Further languages can easily be supported by providing a shallow adapter for a new language server
 implementation.
 
-## Is It Really Free?
+<!-- Created with  markdown-toc -i README.md -->
+<!-- Install it with npm install -g markdown-toc -->
+<!-- toc -->
+
+- [Is It Really Free to Use?](#is-it-really-free-to-use)
+- [What Can I Use Serena For?](#what-can-i-use-serena-for)
+- [Quick Start](#quick-start)
+  * [MCP Server (Claude Desktop)](#mcp-server-claude-desktop)
+  * [Agno](#agno)
+- [Serena's Tools and Configuration](#serenas-tools-and-configuration)
+- [Comparison with Other Coding Agents](#comparison-with-other-coding-agents)
+  * [Subscription-Based Coding Agents](#subscription-based-coding-agents)
+  * [API-Based Coding Agents](#api-based-coding-agents)
+  * [Other MCP-Based Coding Agents](#other-mcp-based-coding-agents)
+- [Limitations of MCP Servers](#limitations-of-mcp-servers)
+  * [Serena Logging](#serena-logging)
+- [Onboarding and Memories](#onboarding-and-memories)
+- [Recommendations on Using Serena](#recommendations-on-using-serena)
+  * [Which Model to Choose?](#which-model-to-choose)
+  * [Onboarding](#onboarding)
+  * [Before Editing Code](#before-editing-code)
+  * [Potential Issues in Code Editing](#potential-issues-in-code-editing)
+  * [Running Out of Context](#running-out-of-context)
+  * [Controlling Tool Execution](#controlling-tool-execution)
+  * [Structuring Your Codebase](#structuring-your-codebase)
+  * [Logging, Linting, and Testing](#logging-linting-and-testing)
+  * [General Advice](#general-advice)
+- [Acknowledgements](#acknowledgements)
+- [Customizing Serena](#customizing-serena)
+- [Full List of Tools](#full-list-of-tools)
+
+<!-- tocstop -->
+
+## Is It Really Free to Use?
 
 Yes! Even the free tier of Anthropic's Claude has support for MCP Servers, so you can use Serena with Claude for free.
 Presumably, the same will soon be possible with ChatGPT Desktop once support for MCP servers is added.  
@@ -61,6 +94,7 @@ We thus built Serena with the prospect of being able to cancel most other subscr
 ## What Can I Use Serena For?
 
 You can use Serena for any coding tasks - analyzing, planning, editing and so on.
+Serena can read, write and execute code, read logs and the terminal output. 
 Vibe coding is possible, and if you want to almost feel like "the code no longer exists"
  you may find Serena even more adequate for vibing than an agent inside an IDE
 (since you will have a separate GUI that really lets you forget).
@@ -382,6 +416,9 @@ executing tests, running scripts, linting and so on. It is often very helpful to
 messages with explicit information and to have good tests. Especially the latter often help the agent
 to self-correct.
 
+We generally recommend to start an editing task from a state where all linting checks and tests pass, this
+way the info extracted from running these commands is of most use to the agent.
+
 ### General Advice
 
 We found that it is often a good idea to spend some time conceptualizing and planning a task

src/serena/agent.py

@@ -373,10 +373,15 @@ class GetDirOverviewTool(Tool):
             no content will be returned. Don't adjust unless there is really no other way to get the content
             required for the task. If the overview is too long, you should use a smaller directory instead,
             (e.g. a subdirectory).
-        :return: a JSON object mapping relative paths of all contained files to info about top-level symbols in the file (name, kind, line).
+        :return: a JSON object mapping relative paths of all contained files to info about top-level symbols in the file (name, kind, line, column).
         """
-        result = json.dumps(self.language_server.request_dir_overview(relative_path))
-        return self._limit_length(result, max_answer_chars)
+        path_to_symbol_infos = self.language_server.request_dir_overview(relative_path)
+        result = {}
+        for file_path, symbols in path_to_symbol_infos.items():
+            result[file_path] = [_tuple_to_info(*symbol_info) for symbol_info in symbols]
+
+        result_json_str = json.dumps(result)
+        return self._limit_length(result_json_str, max_answer_chars)
 
 
 class GetDocumentOverviewTool(Tool):
@@ -394,10 +399,11 @@ class GetDocumentOverviewTool(Tool):
         :param max_answer_chars: if the overview is longer than this number of characters,
             no content will be returned. Don't adjust unless there is really no other way to get the content
             required for the task.
-        :return: a JSON object with the list of tuples (name, kind, line, column) of all top-level symbols in the file.
+        :return: a JSON object with the info (name, kind, line, column) of all top-level symbols in the file.
         """
-        result = json.dumps(self.language_server.request_document_overview(relative_path))
-        return self._limit_length(result, max_answer_chars)
+        result = self.language_server.request_document_overview(relative_path)
+        result_json_str = json.dumps([_tuple_to_info(*symbol_info) for symbol_info in result])
+        return self._limit_length(result_json_str, max_answer_chars)
 
 
 class FindSymbolTool(Tool):
@@ -960,3 +966,7 @@ def _print_tool_overview(tools: Iterable[type[Tool] | Tool]) -> None:
     for tool_name in sorted(tool_dict.keys()):
         tool = tool_dict[tool_name]
         print(f" * `{tool_name}`: {tool.get_tool_description().strip()}")
+
+
+def _tuple_to_info(name: str, symbol_type: SymbolKind, line: int, column: int) -> dict[str, int | str]:
+    return {"name": name, "symbol_kind": symbol_type, "line": line, "column": column}