Merge remote-tracking branch 'origin/main' into v1-beta

README.md

@@ -106,7 +106,7 @@ See our [documentation page](https://oraios.github.io/serena/02-usage/025_jetbra
 Issue this command to see available options:
 
 ```bash
-uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help
+uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --help
 ```
 
 **Configuring Your Client**. To connect Serena to your preferred MCP client, you typically need to [configure a launch command in your client](https://oraios.github.io/serena/02-usage/030_clients.html).

docs/02-usage/020_running.md

@@ -21,7 +21,7 @@ In general, to get help, append `--help` to the command, i.e.
 
 `uvx` is part of `uv`. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation.
 
-    uvx --from git+https://github.com/oraios/serena serena 
+    uvx -p 3.13 --from git+https://github.com/oraios/serena serena 
 
 Explore the CLI to see some of the customization options that serena provides (more info on them below).
 
@@ -124,7 +124,7 @@ case, you can simply run the `start-mcp-server` command without any additional o
 
 For example, to run the server in stdio mode via `uvx`, you would run:
 
-    uvx --from git+https://github.com/oraios/serena serena start-mcp-server 
+    uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server 
  
 See the section ["Configuring Your MCP Client"](030_clients) for specific information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.)
 to use such a launch command.
@@ -143,7 +143,7 @@ via the `--port` option.
 For example, to run the Serena MCP server in streamable HTTP mode on port 9121 using uvx,
 you would run
 
-    uvx --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121
+    uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121
 
 and then configure your client to connect to `http://localhost:9121/mcp`.
 

docs/02-usage/030_clients.md

@@ -79,7 +79,7 @@ Serena is a great way to make Claude Code both cheaper and more powerful!
 use this command:
 
 ```shell
-claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
+claude mcp add serena -- uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
 ```
 
 Note:
@@ -92,7 +92,7 @@ Note:
 **Global Configuration**. Alternatively, use `--project-from-cwd` for user-level configuration that works across all projects:
 
 ```shell
-claude mcp add --scope user serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd
+claude mcp add --scope user serena -- uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd
 ```
 
 Whenever you start Claude Code, Serena will search up from the current directory for `.serena/project.yml` or `.git` markers,
@@ -128,6 +128,8 @@ While serena can be directly installed from the GitHub MCP server registry, we r
       "type": "stdio",
       "command": "uvx",
       "args": [
+        "-p",
+        "3.13",
         "--from",
         "git+https://github.com/oraios/serena",
         "serena",
@@ -153,25 +155,18 @@ For example, when using `uvx`, add the following section:
 
 ```toml
 [mcp_servers.serena]
+startup_timeout_sec = 25
 command = "uvx"
-args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]
+args = ["-p", "3.13", "--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--project-from-cwd", "--context", "codex"]
 ```
 
-After codex has started, you need to activate the project, which you can do by saying:
+The larger startup timeout is to permit uvx to download the necessary dependencies. Once downloaded, the startup time is much faster.
 
-> Call serena.activate_project, serena.check_onboarding_performed and serena.initial_instructions
-
-**If you don't activate the project, you will not be able to use Serena's tools!**
-
-It is recommend to set this prompt as a [custom prompt](https://developers.openai.com/codex/custom-prompts), so you don't need to type this every time.
-
-That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred.
-
-Serena's dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing, the web browser
-may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if
-that was already taken).
-
-> Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected.
+:::{attention}
+Codex currently ignores the [instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/) 
+property of MCP servers, so it is recommended to prompt the agent to 
+"read initial instructions for Serena" when starting your session, e.g. by mentioning this in your `AGENT.md`.
+:::
 
 ## Claude Desktop
 
@@ -189,6 +184,8 @@ Add the `serena` MCP server configuration
     "serena": {
       "command": "uvx",
       "args": [
+        "-p",
+        "3.13",
         "--from",
         "git+https://github.com/oraios/serena",
         "serena",
@@ -225,6 +222,8 @@ MCP server configuration:
     "serena": {
       "command": "uvx",
       "args": [
+        "-p",
+        "3.13",
         "--from",
         "git+https://github.com/oraios/serena",
         "serena",
@@ -253,6 +252,8 @@ Go to Settings / Tools / AI Assistant / MCP and add a new **local** configuratio
     "serena": {
       "command": "uvx",
       "args": [
+        "-p",
+        "3.13",
         "--from",
         "git+https://github.com/oraios/serena",
         "serena",
@@ -279,6 +280,8 @@ Add this configuration:
     "serena": {
       "command": "uvx",
       "args": [
+        "-p",
+        "3.13",
         "--from",
         "git+https://github.com/oraios/serena",
         "serena",

docs/02-usage/040_workflow.md

@@ -29,7 +29,7 @@ To explicitly create a project, use the following command while in the project d
 
 For instance, when using `uvx`, run
 
-    uvx --from git+https://github.com/oraios/serena serena project create [options]
+    uvx -p 3.13 --from git+https://github.com/oraios/serena serena project create [options]
 
  * For an empty project, you will need to specify the programming language
    (e.g., `--language python`). 
@@ -201,7 +201,7 @@ Depending on the language backend being used, the management of resources for th
 
   where `<serena>` is your way of running Serena. For example, when using `uvx`, run
 
-      uvx --from git+https://github.com/oraios/serena serena start-project-server
+      uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-project-server
 
 ### Multiple Agents Accessing a Single Serena Instance
 

docs/03-special-guides/serena_on_chatgpt.md

@@ -17,7 +17,7 @@ Run the following command to launch Serena as http server (assuming port 8000):
 
 ```bash
 uvx mcpo --port 8000 --api-key <YOUR_SECRET_KEY> -- \
-  uvx --from git+https://github.com/oraios/serena \
+  uvx -p 3.13 --from git+https://github.com/oraios/serena \
   serena start-mcp-server --context chatgpt --project $(pwd)
 ```
 
@@ -28,7 +28,7 @@ You can also use other options, and you don't have to pass `--project` if you wa
 or want to activate it later. See 
 
 ```shell
-uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help
+uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --help
 ```
 
 ---

src/serena/util/file_system.py

@@ -165,10 +165,14 @@ class GitignoreParser:
 
         def scan(abs_path: str | None) -> Iterator[str]:
             for entry in os.scandir(abs_path):
-                if entry.is_dir(follow_symlinks=follow_symlinks):
-                    queue.append(entry.path)
-                elif entry.is_file(follow_symlinks=follow_symlinks) and entry.name == ".gitignore":
-                    yield entry.path
+                try:
+                    if entry.is_dir(follow_symlinks=follow_symlinks):
+                        queue.append(entry.path)
+                    elif entry.is_file(follow_symlinks=follow_symlinks) and entry.name == ".gitignore":
+                        yield entry.path
+                except PermissionError as ex:
+                    log.debug(f"Skipping entry due to permission error: {entry.path}", exc_info=ex)
+                    continue
 
         while queue:
             next_abs_path = queue.pop(0)