From e22893862cc0f715af93b0b1710d077686e23c74 Mon Sep 17 00:00:00 2001
From: Dominik Jain <dominik.jain@oraios-ai.de>
Date: Fri, 10 Apr 2026 16:02:23 +0200
Subject: [PATCH] ClientSetupClaudeCode: Add hook recommendation with link to
 docs

---
 src/serena/config/client_setup.py | 33 +++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/src/serena/config/client_setup.py b/src/serena/config/client_setup.py
index ba0fc23d..9116d01f 100644
--- a/src/serena/config/client_setup.py
+++ b/src/serena/config/client_setup.py
@@ -1,5 +1,7 @@
 from abc import ABC, abstractmethod
 
+import click
+
 from serena.util.shell import execute_shell_command
 
 
@@ -20,6 +22,25 @@ class ClientSetupHandler(ABC):
     def get_mcp_server_command(self) -> str:
         return f"serena start-mcp-server {' '.join(self.get_mcp_server_options())}"
 
+    def _run_shell_command(self, cmd: str) -> bool:
+        """
+        Runs the given shell command.
+        If the command fails (i.e., with non-zero exit code), prints the stdout and stderr of the command for debugging.
+
+        :param cmd: the shell command to execute
+        :return: whether the command executed successfully (i.e., with exit code 0)
+        """
+        click.echo("Running command:")
+        click.echo(cmd)
+        result = execute_shell_command(cmd)
+        is_success = result.return_code == 0
+        if not is_success:
+            if result.stdout:
+                click.echo(result.stdout)
+            if result.stderr:
+                click.echo(result.stderr)
+        return is_success
+
     @abstractmethod
     def apply(self) -> bool:
         """
@@ -39,8 +60,13 @@ class ClientSetupHandlerClaudeCode(ClientSetupHandler):
         return ["--context=claude-code", "--project-from-cwd"]
 
     def apply(self) -> bool:
-        result = execute_shell_command(f"claude mcp add --scope user serena -- {self.get_mcp_server_command()}")
-        return result.return_code == 0
+        cmd = f"claude mcp add --scope user serena -- {self.get_mcp_server_command()}"
+        is_success = self._run_shell_command(cmd)
+        if is_success:
+            click.echo("\nIMPORTANT: We additionally recommend to set up hooks for Claude Code to ensure the best experience.")
+            click.echo("   Please read the instructions here:")
+            click.echo("   https://oraios.github.io/serena/02-usage/030_clients.html#claude-code")
+        return is_success
 
 
 class ClientSetupHandlerCodex(ClientSetupHandler):
@@ -59,8 +85,7 @@ class ClientSetupHandlerCodex(ClientSetupHandler):
         return ["--context=codex", "--project-from-cwd"]
 
     def apply(self) -> bool:
-        result = execute_shell_command(f"codex mcp add serena -- {self.get_mcp_server_command()}")
-        return result.return_code == 0
+        return self._run_shell_command(f"codex mcp add serena -- {self.get_mcp_server_command()}")
 
 
 client_setup_handlers = [ClientSetupHandlerClaudeCode(), ClientSetupHandlerCodex()]